feat(api): add mcp server for ai agent integration

[arielshad]

Summary

Adds an MCP (Model Context Protocol) server to shep, enabling external AI agents (Claude Desktop, Cursor, VS Code Copilot, Windsurf, etc.) to discover and invoke shep capabilities as MCP tools over stdio transport.

• New shep mcp CLI command — launches a foreground MCP server on stdio (stdin/stdout JSON-RPC), with --log-level option and Claude Desktop config example in --help
• 11 MCP tools exposing core use cases: list_features, show_feature, create_feature, start_feature, run_agent, show_agent_run, list_agent_runs, stop_agent_run, list_repositories, get_settings, update_settings
• Thin presentation adapter — each tool handler resolves its use case from the shared DI container, with zod-validated input schemas and structured error responses (isError: true)
• Stdio safety — zero console.log calls in MCP code; all diagnostics go to stderr only
• Graceful shutdown — handles SIGINT/SIGTERM to cleanly close the MCP transport

Architecture

The MCP server follows the existing Clean Architecture pattern as a new presentation adapter:

presentation/cli/commands/mcp.command.ts  →  DI container  →  McpServerService
                                                                  ├── feature tools
                                                                  ├── agent tools
                                                                  ├── repository tools
                                                                  └── settings tools

Uses @modelcontextprotocol/sdk v1.27.1 with native zod v4 support. Server identifies as "shep" with the current CLI version. Long-running operations (agent runs) return immediately with a run ID.

Evidence

• 75 unit tests across 7 test files (server service, DI registration, feature/agent/repo/settings tools, CLI command) — all passing
• 23 integration tests using InMemoryTransport + MCP Client for protocol round-trip verification (initialize, tools/list, tools/call success/error paths, input validation, server resilience) — all passing
• Full test suite: 4824 unit tests (355 files) + 569 integration tests (48 files) = 5393 tests — zero failures
• Build + lint: pnpm build and pnpm lint (eslint --max-warnings 0) both pass with zero errors
• Stdio safety: grep confirms zero console.log calls in MCP server code

Test plan

• pnpm build compiles without errors
• pnpm lint passes with zero warnings
• pnpm test:unit — 4824 tests pass (355 files)
• MCP unit tests cover all 11 tool handlers, DI registration, CLI command
• MCP integration tests verify full protocol round-trip via InMemoryTransport
• No console.log in MCP server code (stdio safety)
• CI pipeline passes all checks

🤖 Generated with Claude Code

[github-actions]

Dev Release Published

Artifact	Version	Install
npm	1.149.1-pr469.a02d90d	npm install -g @shepai/cli@1.149.1-pr469.a02d90d

---

_{Published from commit 1c41c26 | View CI}

[github-actions]

Dev Release Published

Artifact	Version	Install
npm	1.149.1-pr469.2ebd7cc	npm install -g @shepai/cli@1.149.1-pr469.2ebd7cc

---

_{Published from commit 03f6101 | View CI}

[github-actions]

Dev Release Published

Artifact	Version	Install
npm	1.150.1-pr469.f0b1954	npm install -g @shepai/cli@1.150.1-pr469.f0b1954

---

_{Published from commit 88fe332 | View CI}

[github-actions]

Dev Release Published

Artifact	Version	Install
npm	1.150.1-pr469.968809e	npm install -g @shepai/cli@1.150.1-pr469.968809e

---

_{Published from commit 9926128 | View CI}