TaskDoc MCP

中文使用说明 / Chinese guide

TaskDoc MCP is a desktop-only Obsidian plugin for Kanban-backed task checkpoint documents. It keeps long-term task records concise while preserving large tables, Mermaid diagrams, CP checklists, specifications, and test evidence as addressable rich blocks.

This repository is an early test release extracted from the Taskflow design in win-console.

Alpha scope

• Register one or more Obsidian Kanban Markdown boards.

• Treat a board as a project, a column as a task type, and a linked card as a task.

• Create a linked task document and card through MCP.

• Commit validated checkpoint cores with fixed rendering.

• Store Markdown tables, Mermaid, domain checklists, configuration, specifications, and evidence as rich blocks up to 24,576 characters by default.

• Write a mutable handoff capsule and resume a task without loading its full history or rich block bodies.

• Move a card between type columns and synchronize its checkbox completion state.

• Run a token-authenticated Streamable HTTP MCP endpoint on loopback, a specific VM/LAN adapter, or all IPv4/IPv6 interfaces.

• Configure boards, MCP, document budgets, and diagnostics from the Obsidian plugin settings page.

PHA synchronization is intentionally unavailable in this alpha. The adapter/outbox boundary and settings placeholder are included, but a real implementation requires the concrete PHA task/comment API, especially comment update semantics.

Related MCP server: Obsidian MCP Server

Requirements

• Obsidian Desktop 1.11.4 or newer.

• An Obsidian Kanban board represented as Markdown headings and checkbox cards.

• An MCP client that supports remote/Streamable HTTP servers.

Do not enable the old win-console Taskflow writer and TaskDoc MCP against the same files at the same time.

Install from a release

1. Download taskdoc-mcp-0.1.0-alpha.2.zip from the GitHub Release.

2. Extract it to <vault>/.obsidian/plugins/taskdoc-mcp/.

3. Confirm that the folder directly contains main.js, manifest.json, and styles.css.

4. Enable TaskDoc MCP under Obsidian → Settings → Community plugins.

5. Open Obsidian → Settings → TaskDoc MCP.

The plugin is desktop-only because the MCP server uses the Node.js HTTP API.

Configure a board

1. In Boards, choose Add.

2. Enter a vault-relative board file such as Projects/win-console.md.

3. Enter the task document folder, for example Tasks/win-console.

4. Choose Scan headings.

5. Give each discovered column a stable type ID and validation profile.

Task semantics are fixed:

Connect an MCP client

Use Copy client config on the settings page. The generated configuration contains the current endpoint and Bearer token. A representative OpenCode configuration is:

{
  "mcp": {
    "taskdoc": {
      "type": "remote",
      "url": "http://127.0.0.1:27124/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer <generated-token>"
      }
    }
  }
}

Network settings separate the listener from the generated client URL:

• Bind host controls which Windows interface accepts connections. Keep 127.0.0.1 for local-only access, use a specific Host-only/bridged adapter address, or use 0.0.0.0 / :: for all IPv4 / IPv6 interfaces.

• Client host is the concrete IP address or hostname that the MCP client can reach. It cannot be a wildcard address; IPv6 URLs are bracketed automatically.

• IP literal Host headers are accepted without a source-IP allowlist. DNS Host headers must be localhost or match the configured client host, preserving DNS-rebinding protection.

Bearer authentication does not encrypt HTTP traffic. When listening beyond loopback, restrict the port with Windows Firewall to trusted VM addresses/subnets and use TLS or a VPN before crossing an untrusted network. Never expose the plain HTTP endpoint directly to the public internet.

The token is stored in Obsidian SecretStorage. Regenerating it invalidates all copied client configurations.

MCP tools

Writes use stable IDs, expected revisions, and request idempotency keys. Free-form append logs, session todo lists, and arbitrary frontmatter mutation are not exposed. The alpha idempotency-result cache lasts for the current plugin runtime; after reloading Obsidian, reread the task before retrying an uncertain write.

Development

npm.cmd install
npm.cmd run check

The production bundle is written to main.js.

Known alpha limitations

• PHA remote synchronization is not active without its API specification.

• Direct manual edits inside plugin-managed checkpoint regions are detected as conflicts; import/reconciliation UI is intentionally conservative.

• The plugin understands the standard Markdown shape of Kanban boards. It does not depend on private runtime APIs from a Kanban fork.

• Automatic conversion of manually typed, unlinked cards is reserved but not enabled in this alpha; create tasks through MCP.

• A crash between rich-block asset and manifest writes can leave a detectable mismatch; there is no automatic mutation-journal repair yet.

• Obsidian must remain running for MCP access.

• Non-loopback MCP access uses plain HTTP; token authentication is not transport encryption.

• The request-id result cache is not yet persisted across an Obsidian/plugin restart.

See TASKFLOW_VNEXT_DESIGN.md for the complete design and acceptance criteria.