# 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:

```bash
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:

```json
{
  "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)

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

### Windows Native

```json
{
  "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`:

```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:

```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 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):

```bash
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.

```bash
./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).