# MCP Tools Reference

Domscribe exposes 12 tools and 4 prompts via the [Model Context Protocol](https://modelcontextprotocol.io/). Any MCP-compatible coding agent can use these tools to query runtime context, resolve source locations, and process annotations.

The MCP server communicates over stdio and connects to the Domscribe relay daemon running on localhost. The relay must be running (it starts automatically with your dev server) for the tools to function.

## Configuration

Add the MCP server to your agent configuration:

```json
{
  "mcpServers": {
    "domscribe": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@domscribe/mcp"]
    }
  }
}
```

* * *

## Source Query Tools

These tools let the agent query source locations and retrieve live runtime context from the running browser.

### `domscribe.query.bySource`

Query a source file and line number to get live runtime context from the browser (props, state, DOM snapshot).

**Input:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | `string` | Yes | Absolute file path as stored in the manifest |
| `line` | `number` | Yes | Line number (1-indexed) |
| `column` | `number` | No | Column number (0-indexed) |
| `tolerance` | `number` | No | Max line distance to consider (default: 0) |
| `includeRuntime` | `boolean` | No | Query live runtime context via WebSocket (default: true) |

**Response:**

```json
{
  "sourceLocation": {
    "file": "src/components/Button.tsx",
    "line": 12,
    "column": 4,
    "componentName": "Button",
    "tagName": "button"
  },
  "runtime": {
    "componentProps": { "variant": "secondary", "onClick": "[Function]" },
    "componentState": { "hook_0": false, "hook_1": "idle" },
    "domSnapshot": {
      "tagName": "button",
      "attributes": { "class": "btn-secondary", "type": "submit" },
      "innerText": "Save changes"
    }
  },
  "browserConnected": true
}
```

The `runtime` field is only present when a browser client is connected via WebSocket and `includeRuntime` is true.

### `domscribe.manifest.query`

Find manifest entries by file path, component name, or element ID.

**Input:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | `string` | No | Filter by file path |
| `componentName` | `string` | No | Filter by component name |
| `id` | `string` | No | Filter by specific element ID |

At least one parameter must be provided.

### `domscribe.manifest.stats`

Returns manifest coverage statistics.

**Response fields:**

| Field | Type | Description |
| --- | --- | --- |
| `entryCount` | `number` | Total manifest entries |
| `fileCount` | `number` | Number of unique source files |
| `componentCount` | `number` | Number of unique component names |
| `cacheHitRate` | `number` | IDStabilizer cache hit rate (0-1) |

* * *

## Element Resolution Tools

Resolve `data-ds` element IDs (injected at build time) back to their source locations.

### `domscribe.resolve`

Resolve a single `data-ds` element ID to its ManifestEntry.

**Input:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes | The `data-ds` element ID |

**Response:**

```json
{
  "found": true,
  "entry": {
    "id": "A1B2C3D4",
    "file": "src/components/Button.tsx",
    "start": { "line": 12, "column": 4 },
    "end": { "line": 12, "column": 42 },
    "tagName": "button",
    "componentName": "Button"
  }
}
```

### `domscribe.resolve.batch`

Resolve multiple element IDs in one call.

**Input:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `ids` | `string[]` | Yes | Array of `data-ds` element IDs |

Returns an array of resolved entries.

* * *

## Annotation Workflow Tools

Annotations are created when a developer clicks an element in the overlay and describes a change. These tools drive the agent-side processing loop.

### `domscribe.annotation.process`

Atomically claim the next queued annotation. This prevents concurrent agent conflicts by transitioning the annotation from `QUEUED` to `PROCESSING` in a single operation.

**Input:** No parameters required.

**Response:**

```json
{
  "found": true,
  "annotationId": "ann_A1B2C3D4_1710500000",
  "userIntent": "Make this button use the primary color from the design system",
  "element": {
    "tagName": "button",
    "dataDs": "A1B2C3D4",
    "selector": "main > div > button",
    "attributes": { "class": "btn-secondary", "type": "submit" },
    "innerText": "Save changes"
  },
  "sourceLocation": {
    "file": "src/components/Button.tsx",
    "line": 12,
    "column": 4,
    "componentName": "Button",
    "tagName": "button"
  },
  "runtimeContext": {
    "componentProps": { "variant": "secondary", "onClick": "[Function]" },
    "componentState": { "hook_0": false, "hook_1": "idle" }
  }
}
```

Returns `{ "found": false }` when no queued annotations are available.

### `domscribe.annotation.respond`

Attach the agent's response to an annotation and transition it to `PROCESSED`.

**Input:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes | Annotation ID (`ann_*`) |
| `response` | `string` | Yes | Agent's response text |

### `domscribe.annotation.updateStatus`

Manually transition an annotation's status.

**Input:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes | Annotation ID |
| `status` | `string` | Yes | Target status: `QUEUED`, `PROCESSING`, `PROCESSED`, `FAILED`, or `ARCHIVED` |

### `domscribe.annotation.get`

Retrieve a single annotation by ID.

**Input:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes | Annotation ID |

### `domscribe.annotation.list`

List annotations with optional status filtering.

**Input:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `string` | No | Filter by status (e.g. `QUEUED`) |

### `domscribe.annotation.search`

Full-text search across annotation content.

**Input:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | `string` | Yes | Search query text |

* * *

## System Tools

### `domscribe.status`

Returns relay daemon health, manifest stats, and annotation queue counts.

**Response fields:**

| Field | Type | Description |
| --- | --- | --- |
| `relayRunning` | `boolean` | Whether the relay daemon is healthy |
| `browserConnected` | `boolean` | Whether a browser client is connected |
| `manifestStats` | `object` | Entry count, file count, component count |
| `queueCounts` | `object` | Annotation counts by status |

* * *

## MCP Prompts

Pre-built prompts that guide agents through common Domscribe workflows. These are exposed as MCP prompt resources that agents can invoke.

### `process_next`

Guides the agent through the complete annotation processing workflow: claim the next queued annotation, navigate to the source file, implement the change, and respond with a summary.

### `check_status`

Checks the relay daemon status, manifest statistics, and queue counts. Useful for verifying the system is healthy before starting work.

### `explore_component`

Deep-dive into a specific component's metadata. Queries the manifest and runtime context to build a complete picture of a component's props, state, and DOM output.

### `find_annotations`

Searches for annotations matching specific criteria. Useful for discovering pending work or finding annotations related to a particular component or file.