# SigMap MCP Server Setup

SigMap ships a zero-dependency [MCP](https://modelcontextprotocol.io) server that exposes your project's code signatures to any MCP-compatible AI tool — Claude Code, Cursor, Windsurf, and others.

---

## Quick start

### 1. Generate context first

The MCP server reads files generated by `gen-context.js`. Run it at least once before starting the server:

```bash
node gen-context.js
```

### 2. Start the server manually

```bash
node gen-context.js --mcp
```

The server runs on **stdio** — the MCP host manages the process lifecycle. You don't start it manually; your AI tool does.

### 3. Auto-register during setup

When you run `--setup`, SigMap automatically detects and updates `.claude/settings.json` and `.cursor/mcp.json` if they exist:

```bash
node gen-context.js --setup
```

It also prints a manual config snippet you can paste into any other tool.

---

## Manual configuration

### Claude Code

Add to `.claude/settings.json` (project-level) or `~/.claude/settings.json` (global):

```json
{
  "mcpServers": {
    "sigmap": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/gen-context.js", "--mcp"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "sigmap": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/gen-context.js", "--mcp"]
    }
  }
}
```

### Both servers (SigMap + Repomix)

See [examples/claude-code-settings.json](../examples/claude-code-settings.json) for a ready-to-use config with both servers configured.

---

## Available tools

### `read_context`

Returns extracted code signatures for the whole project or a specific module.

| Argument | Type | Required | Description |
|---|---|---|---|
| `module` | string | No | Subdirectory path to scope results (e.g. `src/services`) |

**Examples:**

```
# Full codebase (~500–4K tokens)
read_context()

# Single module (~50–500 tokens)
read_context(module="src/auth")
```

**Returns:** Contents of `.github/copilot-instructions.md`, optionally filtered to the requested module path.

---

### `search_signatures`

Case-insensitive keyword search across all extracted signatures.

| Argument | Type | Required | Description |
|---|---|---|---|
| `query` | string | Yes | Keyword to search for |

**Example:**

```
search_signatures(query="handleRequest")
```

**Returns:** Matching signature lines grouped by file path.

---

### `get_map`

Returns a section from `PROJECT_MAP.md` (requires `gen-project-map.js` to have been run).

| Argument | Type | Required | Description |
|---|---|---|---|
| `type` | `imports` \| `classes` \| `routes` | Yes | Which section to retrieve |

**Example:**

```
get_map(type="routes")
```

**Returns:** The import graph, class hierarchy, or route table section from `PROJECT_MAP.md`. Returns a helpful error message if the file doesn't exist yet.

---

## Token costs

| Tool call | Approx. tokens |
|---|---|
| `read_context()` full codebase | 200–4 000 |
| `read_context(module="src/auth")` | 20–500 |
| `search_signatures(query="login")` | 10–200 |
| `get_map(type="routes")` | 50–800 |

---

## Keeping context fresh

The MCP server reads files from disk on every call — no in-memory state — so it always serves the latest generated context without needing a restart.

To keep context up-to-date automatically, use one of:

```bash
# Post-commit hook (installed by --setup)
node gen-context.js --setup

# Continuous watcher
node gen-context.js --watch
```

---

## Troubleshooting

**"No context file found"**
Run `node gen-context.js` first to generate `.github/copilot-instructions.md`.

**"PROJECT_MAP.md not found"**
Run `node gen-project-map.js` to generate the project map (available in v0.4+).

**Server not appearing in tool list**
Check that the absolute path in your settings file points to the correct `gen-context.js`. Use `node /path/to/gen-context.js --version` to verify it resolves correctly.

**Port/connection issues**
The MCP server uses stdio, not a network port. If your tool reports connection errors, check the command path — it's not a network problem.