MCP Client Setup

Claude Code

Registered automatically by ./build.sh via claude mcp add --scope user — idempotent, re-runnable. To re-register without rebuilding, run:

npm run register-mcp

This calls claude mcp add --scope user FileScopeMCP <node> <path-to-dist/mcp-server.js>. User scope means one registration covers every Claude Code session on the host. If the claude CLI is not installed, the script prints a hint and exits 0 — the build does not fail.

Contributor dogfood

Opening the FileScopeMCP repo itself in Claude Code auto-discovers the server via the committed .mcp.json at the repo root:

{
  "mcpServers": {
    "FileScopeMCP": {
      "command": "node",
      "args": ["dist/mcp-server.js"]
    }
  }
}

This only takes effect when Claude Code is open on this repo (its CWD is this repo root). End users do not need this file — npm run register-mcp covers them globally.

Selecting a different project

FileScopeMCP auto-initializes to the CWD Claude Code starts it in. To analyze a different directory at runtime:

set_base_directory(path: "/path/to/your/project")

Cursor AI

Cursor does not have a claude mcp add equivalent, so registration is manual. Copy the appropriate JSON block below into your project's .cursor/mcp.json.

Linux / macOS Native (default)

{
  "mcpServers": {
    "FileScopeMCP": {
      "command": "node",
      "args": ["/path/to/FileScopeMCP/dist/mcp-server.js", "--base-dir=${projectRoot}"],
      "transport": "stdio"
    }
  }
}

Windows Native

{
  "mcpServers": {
    "FileScopeMCP": {
      "command": "node",
      "args": ["C:\\FileScopeMCP\\dist\\mcp-server.js", "--base-dir=${projectRoot}"],
      "transport": "stdio",
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

WSL (alternative — Cursor on Windows, FileScopeMCP in WSL)

Build inside WSL (./build.sh), then add to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "FileScopeMCP": {
      "command": "wsl",
      "args": ["-d", "Ubuntu-24.04", "/home/yourname/FileScopeMCP/run.sh", "--base-dir=${projectRoot}"],
      "transport": "stdio",
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Replace Ubuntu-24.04 with your WSL distro name (wsl -l -q to list) and /home/yourname/FileScopeMCP with the WSL path to this repo.

Cross-host alternative (WSL → Windows)

If FileScopeMCP runs in WSL and Claude Code runs on the Windows host, automatic registration via npm run register-mcp does not apply — the claude CLI on Windows cannot spawn a WSL process directly. Configure this manually by editing the Windows-side .claude.json (or using claude mcp add on Windows) with a wsl shim:

{
  "mcpServers": {
    "FileScopeMCP": {
      "command": "wsl",
      "args": ["-d", "Ubuntu-24.04", "/home/yourname/FileScopeMCP/run.sh", "--base-dir=${projectRoot}"],
      "transport": "stdio",
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Replace Ubuntu-24.04 with your distro (wsl -l -q) and /home/yourname/FileScopeMCP with the WSL path. run.sh is generated by ./build.sh in WSL and simply forwards arguments to node dist/mcp-server.js.

Daemon Mode

Run FileScopeMCP as a standalone background process (no MCP client required):

node dist/mcp-server.js --daemon --base-dir=/path/to/project

Logs go to .filescope-daemon.log in the project root. A PID file at .filescope/instance.pid prevents concurrent daemons on the same project.

Multi-Repo Watchers (systemd, Linux only)

Run one MCP server per repo registered in ~/.filescope/nexus.json continuously, even when no MCP client is open. Backed by a systemctl --user unit and a small Node supervisor.

./scripts/nexus.sh install-watchers     # writes the unit, enables it, starts it
systemctl --user status filescope-watchers.service
./scripts/nexus.sh uninstall-watchers   # symmetric removal

What install-watchers does:

• Renders scripts/filescope-watchers.service.tmpl to ~/.config/systemd/user/filescope-watchers.service with the absolute paths of node and scripts/watchers.mjs substituted in.
• Runs systemctl --user daemon-reload, then enables and starts the unit.
• Idempotent — re-running picks up template/path changes and warns rather than restarts when already active (matches setup-llm.sh --install-service style).

What the supervisor does (scripts/watchers.mjs):

• Reads the repo list via readRegistry() from ~/.filescope/nexus.json. Falls back to a 2-level filesystem scan (discoverRepos()) if the registry is missing.
• Spawns one dist/mcp-server.js --base-dir=<repo> child per registered repo and drives an initial scan_all over the MCP stdio handshake.
• Restarts crashed children after 10 s.
• On SIGTERM/SIGINT (including systemctl stop), SIGTERMs every child, waits up to 8 s for graceful exit, then SIGKILLs stragglers and exits 0.

Logs:

• ~/.filescope/watchers.log — supervisor (start/stop, child PIDs, restart events)
• ~/.filescope/watcher-logs/<repo-path-flattened>.log — per-child stderr

The unit declares Requires=filescope-broker.service, so install your broker user unit first. The repo does not currently ship a broker user-unit installer (intentional — out of scope).