MCP Tools Reference

Domscribe exposes 12 tools and 4 prompts via the Model Context Protocol. 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:

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

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

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

{
  "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.