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

# dotbot MCP server overview and tool reference

> The dotbot MCP server connects your AI tool to the task queue, decision log, and session tracker. Reference for all 31 built-in tools across seven categories.

The dotbot MCP server connects your AI coding assistant directly to dotbot's task queue, decision log, session tracker, and development lifecycle. It is implemented in pure PowerShell with no npm, pip, or Docker dependencies, and communicates over stdio using the Model Context Protocol. Any MCP-compatible AI tool - Claude, Warp, and others - can connect to it and use its tools to read and write project state.

## Protocol details

| Property             | Value                                     |
| -------------------- | ----------------------------------------- |
| Transport            | stdio                                     |
| Protocol version     | 2024-11-05                                |
| Server name          | dotbot                                    |
| Server version       | 4.0.0                                     |
| Tool discovery       | Automatic (scans `tools/` subdirectories) |
| Total built-in tools | 31                                        |

## Tool categories

The 31 built-in tools are organized into seven categories. Each category targets a distinct layer of dotbot's project state.

### Task management (10 tools)

These tools read and write the task queue stored in `.bot/workspace/tasks/`. Tasks move through the lifecycle via `task_set_status`, which handles all transitions. Terminal states include `done`, `failed`, `skipped`, and `cancelled`. The full set of task management tools is:

`task_create`, `task_create_bulk`, `task_get`, `task_get_context`, `task_get_next`, `task_list`, `task_set_status`, `task_update`, `task_mark_needs_review`, `task_submit_review`

Use `task_get_next` to retrieve the highest-priority available task, `task_get_context` to load the full context for a specific task before starting work, and `task_set_status` to advance tasks through the lifecycle. When a task requires human approval before completion, use `task_mark_needs_review` to park it, then `task_submit_review` to approve or reject the work.

### Decision tracking (7 tools)

These tools manage the architectural decision log stored in `.bot/workspace/`. When the AI makes a structural choice - selecting a data model, choosing an approach, or identifying a trade-off - it records a decision entry so you can review and challenge it later.

`decision_create`, `decision_get`, `decision_list`, `decision_update`, `decision_mark_accepted`, `decision_mark_deprecated`, `decision_mark_superseded`

### Session management (5 tools)

These tools read and update the AI session state that dotbot's runtime uses to track token spend, costs, and turn counts. They are used by the AI internally during task execution.

`session_initialize`, `session_get_state`, `session_get_stats`, `session_update`, `session_increment_completed`

### Plans (3 tools)

These tools create and retrieve execution plans that the analysis phase produces before implementation begins. The analysis phase uses `plan_create` to record its approach; the execution phase retrieves the plan with `plan_get` before starting work.

`plan_create`, `plan_get`, `plan_update`

### Steering (1 tool)

`steering_heartbeat` - allows an operator to send a "whisper" interrupt to a running AI session without stopping it. This is the mechanism behind dotbot's human-in-the-loop steering feature, which lets you redirect an in-progress session by injecting guidance mid-run.

### Development (2 tools)

`dev_start`, `dev_stop` - wrap the project's `hooks/dev/Start-Dev.ps1` and `Stop-Dev.ps1` scripts so that the AI can start and stop the development environment as part of task execution. Use these when tasks require the dev server to be running for testing or validation steps.

### Workflow management (3 tools)

These tools read and start workflow runs. A workflow run is an orchestrated sequence of tasks generated from a workflow definition.

`workflow_get`, `workflow_list`, `workflow_start`

Use `workflow_start` to kick off a new workflow run, `workflow_list` to view all runs and their current state, and `workflow_get` to retrieve the details of a specific run.

## Workflow and stack extensions

The server discovers tools from three locations:

1. **Built-in tools** - `src/mcp/tools/` inside the dotbot install (the 31 tools listed above)
2. **Workflow tools** - `<workflow-path>/tools/` or `<workflow-path>/systems/mcp/tools/` for each installed workflow
3. **Stack tools** - `<stack-path>/tools/` or `<stack-path>/systems/mcp/tools/` for each active stack

For example, the `start-from-jira` workflow adds `repo_clone`, `repo_list`, `atlassian_download`, and `research_status` to the tool set. No registration step is required - the server finds any tool folder that contains both a `metadata.json` and a `script.ps1`.

<Warning>
  Tool name collisions are possible if two installed workflows or stacks define a tool with the same `name` field in their `metadata.json`. Use unique, workflow-prefixed names (for example, `jira_repo_clone` rather than `repo_clone`) to avoid conflicts.
</Warning>

See [Adding tools](/mcp/adding-tools) for instructions on creating your own tools, and [Configuration](/mcp/configuration) for how to connect your AI tool to the server.