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
The 31 built-in tools are organized into seven categories. Each category targets a distinct layer of dotbot’s project state.
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.
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.
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:
- Built-in tools -
src/mcp/tools/ inside the dotbot install (the 31 tools listed above)
- Workflow tools -
<workflow-path>/tools/ or <workflow-path>/systems/mcp/tools/ for each installed workflow
- 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.
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.