GitDocket docs

MCP & workflows.

Connect your coding agent to the project’s docs and tasks, and use editable workflows to guide the work.

Connect over stdio

Install with Homebrew; npm users install @gitdocket/cli and @gitdocket/mcp. Check docket-mcp --version before configuring your agent. Configure your MCP client to launch that command with the project repository as its working directory. It resolves the nearest docket.yaml. There is no HTTP MCP endpoint.

For supported coding agents, docket init --agent cursor, docket init --agent claude, or docket init --agent codex installs the native integration. For Cursor, enable Docket once in Customize → MCPs after initialization. Other clients use their own stdio server configuration.

Available tools

The current reference contains twenty-five tools captured by a real tools/list from the published npm GitDocket 0.6.4 server on October 5, 2026. Schemas and descriptions are unmodified. See the capture provenance and hashes. The historical 0.6.0 snapshot remains available separately. Download the input schemas (JSON), or request tools/list from your installed server for its exact contract.

Tool	Required input	Purpose
`overview`	None; optional `view`	Project orientation.
`ready`	None	Ready work; optional limit.
`task_list`	None	Work items with status/type filters, optional open-only selection and pagination.
`task_get`	`id`	Full task, epic or decision source.
`task_progress`	None	Saved progress across linked worktrees; optional `id`.
`search`	`query`	Ranked bundle search.
`project_guidance`	None	Optional project standards, scoped source links and diagnostics.
`workflow_extensions`	Optional package ID and paging	Installed packages, project choices and workflow sources.
`source_page`	`path`	Bounded source with a continuation cursor.
`lint`	None	Full or bounded summary diagnostics; optional changed-path and baseline selection.
`index`	None	Refresh wiki discovery after authoring.
`document_create`	`path`, `type`, `title`, `body`	Create a Reference, Spec or Playbook; writes files.
`document_read`	`path`	Complete editable document and source version, or one named section.
`document_edit`	`path`, `expectedVersion`, `patch`	Save a versioned edit; writes files.
`document_move_plan`	`from`, `to`	Inspect a wiki move without writing.
`document_move_apply`	`from`, `to`, `expectedVersion`	Apply a reviewed wiki move; writes files.
`document_move_recover`	`token`	Recover an interrupted wiki move.
`decision_create`	`title`	Record an accepted Decision; writes files. Supply context, decision and consequences when you have them.
`task_create`	`title`	Create a task or epic; writes files.
`set_status`	`id`, `to`	Change stored status; writes files.
`append_log`	`id`, `entry`	Append a dated work note; writes files.
`reconcile_plan`	`selection`	Inspect Docket records from a local source ref without writing.
`reconcile_source`	`selection`, `expectedVersion`, `path`, `side`	Read an exact base/local/incoming/proposed source page.
`reconcile_apply`	`selection`, `expectedVersion`, `choices`	Apply reviewed Docket reconciliation choices; writes files.
`reconcile_recover`	`token`	Recover a recorded interrupted reconciliation.

Current-release inputs

overview accepts view: "brief" (default) or "full". For a complete open inventory, use task_list with open: true and follow pagination; an explicit status takes precedence. Without those filters the MCP list includes history.

lint accepts view: "summary", changed_paths, baseline_path, offset and limit. A summary changes presentation, not the global error or strict-warning policy. Applicable writes accept response: "compact" or "full"; read the tool’s schema for support. task_create.body accepts complete authored Markdown up to 64 KiB; supply real Context and Acceptance Criteria rather than treating a skeleton as finished.

document_read optionally accepts section. document_edit.patch supports body, section, title and description. A section patch uses {"section":{"heading":"Current state","body":"Replacement content."}} with the returned whole-source version. Do not combine body and section edits; body: null inside the section removes it. See the section-edit contract.

Review incoming Docket records

These are MCP calls, not shell commands. Replace the source ref and path with an existing local ref and Docket source. Plan first:

reconcile_plan {"selection":{"sourceRef":"feature/docs","paths":["reference/onboarding.md"]}}

Inspect every plan page, warning and relevant source before choosing an action. selection may include an absolute sourceRoot for a linked worktree, saved: true for saved drafts, or a pinned baseRef. Use reconcile_source with the exact plan version and side to read omitted evidence.

reconcile_apply requires that plan’s version and explicit choices: keep-local, merge-compatible, take-incoming or resolve. Semantic choices require reasons; terminal imports require acceptCompletion. On an interrupted apply, retain the receipt and pass its recovery token to reconcile_recover. These tools do not fetch or merge implementation code, commit, or prove integration.

Workflow: get oriented

Start with overview. If you need the ready queue, call ready, then inspect a returned ID with task_get. Reading status does not start work.

These are individual MCP tool calls for your agent or MCP client, not shell commands. Copy one example at a time.

overview    {}

ready       {"limit": 5}

Replace HBR-4 with an actual task ID returned by ready before asking your MCP client to call:

task_get    {"id": "HBR-4"}

Examples show tool names and argument objects, not shell commands. HBR-4 belongs to the synthetic demo; use an ID from your own repository.

Workflow: run a named epic

Ask your agent to run an existing epic through completion. It reads the epic and the repository’s procedure, then works through eligible children, verifies results, and reconciles affected docs.

In your MCP client, replace HBR-1 with the actual epic ID, then call:

task_get     {"id": "HBR-1"}

Read the epic procedure with a separate MCP call:

source_page  {"path": "workflows/docket-epic.md"}

If the source is paged, pass the returned nextCursor as cursor with the same path until the procedure is complete. A stale cursor requires restarting the read.

The agent also needs repository editing, Git, and CLI tools. MCP does not itself run an epic. Named Task pickup uses docket task start <ID>. Named Epic start returns a non-mutating docket-epic route, without changing status or the active marker or picking a child; the agent continues through that procedure. closure follows the close workflow and docket task close <ID>. set_status alone does not perform those procedures.

Workflow: leave a useful handoff

After checking a change, update affected docs and record the result with links to its commits. Use append_log for a dated note and lint to check the bundle. A new session can use overview and source reads to recover the next step.

Inspectable example

The Harbor welcome guide

A script executed a two-task epic with the real CLI: write a contributor guide, then link it from README and update onboarding. Both tasks and the epic completed; a feedback task became ready next.

The run checked headings, links, recorded Outcomes, and bundle lint. A fresh reader recovered the result from a clean clone. This is a synthetic, scripted example—not a captured agent conversation.

Overview views: GitDocket 0.6.4

GitDocket 0.6.4 makes overview return a bounded live briefing by default. Read omitted counts and follow source paths for details. Pass { "view": "full" } for the previous evidence model and state-of-play refresh. The primary schema download above describes the published 0.6.4 contract.