> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Model Context Protocol server for Claude Code and other MCP-compatible clients

profClaw includes a standalone MCP (Model Context Protocol) server that lets Claude Code and other MCP clients report task progress, track files modified, and interact with the profClaw task queue.

```mermaid theme={null}
sequenceDiagram
  participant CC as Claude Code
  participant MCP as MCP Server\n(stdio)
  participant API as profClaw API\nlocalhost:3000
  participant Q as Task Queue
  participant DB as LibSQL

  CC->>MCP: tools/list
  MCP-->>CC: report_progress, get_task,\ncomplete_task, fail_task, ...

  CC->>MCP: report_progress(taskId, 65%)
  MCP->>API: PATCH /api/tasks/:id/progress
  API->>DB: update task

  CC->>MCP: complete_task(taskId, output, files)
  MCP->>API: POST /api/tasks/:id/complete
  API->>Q: dispatch notifications
  API->>DB: store result
  MCP-->>CC: ok
```

## What is MCP?

The Model Context Protocol is a standard for AI tools to expose capabilities to AI models. profClaw's MCP server exposes profClaw's task management and session tracking as MCP tools.

## Running the MCP Server

The MCP server runs as a separate process communicating over stdio:

```bash theme={null}
# Via npx
npx @profclaw/task-manager-mcp

# Or directly
node dist/mcp/server.js
```

Configure `PROFCLAW_API_URL` to point at your running profClaw instance:

```bash theme={null}
PROFCLAW_API_URL=http://localhost:3000 npx @profclaw/task-manager-mcp
```

## Claude Code Integration

Add to `~/.claude/settings.json` (or `.claude/settings.json` in your project):

```json theme={null}
{
  "mcpServers": {
    "profclaw": {
      "command": "npx",
      "args": ["@profclaw/task-manager-mcp"],
      "env": {
        "PROFCLAW_API_URL": "http://localhost:3000"
      }
    }
  }
}
```

After adding, run `/mcp` in Claude Code to verify the tools are available.

## Available MCP Tools

The MCP server (`src/mcp/server.ts`) exposes these tools to MCP clients:

### `report_progress`

Report task execution progress back to profClaw.

```json theme={null}
{
  "taskId": "task_01",
  "progress": 65,
  "message": "Running tests...",
  "filesModified": ["src/auth.ts", "src/auth.test.ts"]
}
```

### `get_task`

Fetch task details from the profClaw queue.

```json theme={null}
{ "taskId": "task_01" }
```

### `complete_task`

Mark a task as completed with a result summary.

```json theme={null}
{
  "taskId": "task_01",
  "output": "Fixed the session expiry bug in auth-service.ts. Added test coverage.",
  "filesCreated": ["src/auth.test.ts"],
  "filesModified": ["src/auth.ts"]
}
```

### `fail_task`

Mark a task as failed with an error message.

```json theme={null}
{ "taskId": "task_01", "error": "Tests failed: 3 assertions failed" }
```

### `get_session_state`

Get the current MCP session state (token usage, files modified, active task).

### Browser Tools

The MCP server also exposes browser automation tools (`src/mcp/browser-tools.ts`) for screenshot capture, navigation, and DOM interaction - useful for visual testing and web scraping tasks.

## Session State

Each MCP server process maintains in-memory session state:

```typescript theme={null}
interface SessionState {
  sessionId: string;    // mcp-<timestamp>-<random>
  startTime: Date;
  filesModified: string[];
  filesCreated: string[];
  tokenUsage: { input: number; output: number };
  currentTask?: { id: string; title: string; startedAt: Date };
}
```

Session state persists for the lifetime of the stdio connection.

## MCP Server Configuration

```typescript theme={null}
const server = new Server(
  { name: 'profclaw', version: '1.0.0' },
  { capabilities: { tools: { listChanged: true } } }
);
```

The server uses `StdioServerTransport` - it reads from stdin and writes to stdout. This is the standard transport for Claude Code MCP integrations.

## Tool Adapter

`src/mcp/tool-adapter.ts` converts profClaw's internal tool format (`PluginToolDefinition`) to the MCP tool schema format, allowing all installed profClaw tools to be exposed via MCP if desired.

```mermaid theme={null}
flowchart LR
  Plugin["PluginToolDefinition\n(profClaw internal)"]
  Adapter["tool-adapter.ts\nformat conversion"]
  MCPSchema["MCP Tool Schema\n(JSON Schema)"]
  Client["MCP Client\nClaude Code / other"]

  Plugin --> Adapter
  Adapter --> MCPSchema
  MCPSchema --> Client
```

## REST API for MCP

The MCP route (`src/routes/mcp.ts`) provides HTTP endpoints for managing MCP server configuration and viewing connected MCP clients:

```
GET /api/mcp/servers     # List configured MCP servers
POST /api/mcp/servers    # Add an MCP server config
DELETE /api/mcp/servers/:id
GET /api/mcp/tools       # List all tools from connected servers
```