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 | 3.5.0 |
| Tool discovery | Automatic (scans tools/ subdirectories) |
| Total built-in tools | 33 |
.bot/workspace/tasks/. Tasks flow through the lifecycle: todo → analysing → analysed → in-progress → done. The full set of task management tools is:
task_create, task_create_bulk, task_get_next, task_get_context, task_list, task_get_stats, task_mark_todo, task_mark_analysing, task_mark_analysed, task_mark_in_progress, task_mark_done, task_mark_needs_input, task_mark_skipped, task_answer_question, task_approve_split
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 the task_mark_* tools to advance tasks through the lifecycle as the AI completes each phase.
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
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
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_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.
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 and stack extensions
The server discovers tools from two locations:
- Built-in tools —
systems/mcp/tools/ (the 33 tools listed above)
- Workflow and stack tools —
.bot/workflows/*/tools/ (added by installed workflows or stacks)
For example, the kickstart-via-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 that has a metadata.yaml and script.ps1 in its folder.
Tool name collisions are possible if two installed workflows define a tool with the same name field in their metadata.yaml. Use unique, workflow-prefixed names (for example, jira_repo_clone rather than repo_clone) to avoid conflicts.