feat: add MCP server for universal AI integrations

[afonsoft]

Summary

This PR adds an MCP (Model Context Protocol) server and related improvements to enable universal AI integration with Codex Taskboard across multiple CLI tools and AI platforms.

Key Changes

1. MCP Server (mcp/): A new Model Context Protocol server that exposes all Taskboard operations as MCP Tools, enabling integration with any AI platform that supports MCP (Claude, OpenCode, Cursor, Gemini, VS Code Copilot, Devin, WorkBuddy, DeepSeek, etc.)

2. Thread Attribution Enhancement: Extended cli/taskctl.mjs to support TASKBOARD_THREAD_ID environment variable alongside CODEX_THREAD_ID. Priority is now: --thread-id > TASKBOARD_THREAD_ID > CODEX_THREAD_ID.

3. Skill Documentation Update: Updated skills/manage-taskboard/SKILL.md with comprehensive AI integration guidance, including MCP server usage and non-Codex CLI support.

4. Documentation:

   • Added mcp/README.md with detailed setup, configuration, and troubleshooting
   • Updated README.md with AI integrations section
   • Updated AGENTS.md with Setup, MCP registration, and runtime setup sections

Problem Solved

Previously, AI integration was Codex-specific, requiring CDP injection and Codex-specific environment variables. This PR makes the Taskboard usable by any AI CLI or platform through:

• A universal MCP server that wraps the taskctl CLI
• Environment variable fallback chain that works across platforms
• Clear documentation for non-Codex CLIs (Claude, OpenCode, Cursor, Gemini)

Test plan

• MCP server starts and registers tools
• Thread attribution works via TASKBOARD_THREAD_ID, CODEX_THREAD_ID, or --thread-id
• All taskctl commands exposed as MCP tools
• Documentation updated and accurate

Implementation Notes

The MCP server is fully isolated (mcp/package.json is independent of root) and uses the existing taskctl CLI for all operations, ensuring consistency with the main implementation. This follows the project's philosophy of minimal, direct changes.

Files Changed

• mcp/index.mjs - MCP server implementation
• mcp/taskctl-runner.js - Utility to spawn taskctl
• mcp/package.json - Package configuration
• mcp/README.md - MCP server documentation
• cli/taskctl.mjs - Thread attribution enhancement
• skills/manage-taskboard/SKILL.md - Skill documentation update
• README.md - AI integrations section
• AGENTS.md - Setup and MCP registration guidance

[afonsoft]

@jack-atlas @jadon7 @ltx0633 @chuspeeism

[afonsoft]

Change breakdown — detailed notes

1. mcp/index.mjs (new)

The core MCP server. Uses @modelcontextprotocol/sdk with a stdio transport. It:

• Registers 11 tools (list_projects, get_project, create_project, list_issues, get_issue, create_issue, update_issue, move_issue, archive_issue, add_comment, upload_attachment).
• Parses each tool's arguments with zod schemas (status enums, required fields).
• Delegates execution to taskctl-runner.js, which spawns cli/taskctl.mjs with --json and injects TASKBOARD_THREAD_ID into the child environment.
• Surfaces taskctl errors as MCP isError responses so the calling agent sees a clean message instead of a crash.

2. mcp/taskctl-runner.js (new)

Thin wrapper around child_process.spawn('node', [taskctlPath, ...args]). Resolves the taskctl binary relative to the MCP server file, captures stdout/stderr, parses JSON, and throws a readable error on non-zero exit. Thread attribution is applied here so every downstream call is correctly bound.

3. cli/taskctl.mjs (modified)

resolveThreadId() now reads:

const value = options["thread-id"] ?? env.TASKBOARD_THREAD_ID ?? env.CODEX_THREAD_ID;

Error messages were updated to mention TASKBOARD_THREAD_ID. This is the only behavioral change to the CLI and is fully backward-compatible (Codex keeps working unchanged).

4. skills/manage-taskboard/SKILL.md (modified)

Added:

• "Select the CLI and active service" → note that non-Codex agents pass --thread-id or set TASKBOARD_THREAD_ID.
• "AI integrations" section mapping each platform (Claude, OpenCode, Cursor, Gemini, Devin, WorkBuddy, DeepSeek, CI) to its attribution mechanism.
• "MCP server" and "Non-Codex CLI usage" sections.
• "Bindings" subsection documenting Codex vs TASKBOARD_THREAD_ID priority and cloud companion usage.

5. README.md (modified)

Added "AI integrations", "MCP server", and "Non-Codex CLI usage" sections after the Codex Skill install block.

6. AGENTS.md (modified)

Added "Setup" section documenting agent skill install paths per IDE, MCP client config examples (Claude Desktop / OpenCode / Cursor), and a "Runtime setup" section with local-dev and per-platform AI-agent integration steps.

7. mcp/package.json + mcp/README.md (new)

Isolated package manifest (does not touch root package.json deps) and a full README covering tools, configuration, client examples, git/worktree context, cloud mode, and troubleshooting.

[afonsoft]

✅ Sincronizado com main

O fork foi atualizado com as últimas alterações do upstream/main e o PR está pronto para merge.

[afonsoft]

✅ Sincronizado com main

O fork foi atualizado com as últimas alterações do upstream/main e o PR está pronto para merge.

[jadon7]

Thanks for the contribution and for keeping the MCP server as a relatively thin layer over taskctl.
We are currently evaluating the product value of MCP against the additional implementation and maintenance complexity it introduces.
Today, Taskboard primarily uses the manage-taskboard Skill together with the packaged taskctl CLI and structured JSON output. This already gives an agent access to the full Taskboard workflow. Adding MCP creates a second integration surface whose tool schemas, installation, documentation, runtime discovery, session attribution, compatibility, and error behavior must remain synchronized with the CLI.
Before we decide on the merge direction, could you share some concrete examples where you believe MCP provides unique value that cannot be achieved reasonably through the current Skill + CLI model?
For each relevant case, it would be helpful to know the target client, the user workflow, why Skill + CLI is insufficient, and which MCP-specific behavior solves the problem.
Since the current implementation exposes Taskboard operations as 11 stdio tools backed by taskctl, we are especially interested in whether the main value is universal client compatibility, or whether there are MCP-native capabilities that would justify maintaining both interfaces over time.
We are not rejecting the MCP direction. We want to confirm that it adds a distinct product capability instead of becoming only a second way to invoke the same CLI operations.