80 lines
5.6 KiB
Markdown
80 lines
5.6 KiB
Markdown
# External MCP Endpoint — Implementation Plan
|
|
|
|
**Spec:** `./spec.md`
|
|
|
|
## Architecture
|
|
|
|
The existing MCP machinery already separates cleanly along a thin seam:
|
|
|
|
- `internal/agentctl/server/mcp/` — `Server` wraps `mark3labs/mcp-go`, registers tools, exposes routes.
|
|
- The tools talk to the backend through one interface:
|
|
```go
|
|
type BackendClient interface {
|
|
RequestPayload(ctx context.Context, action string, payload, result interface{}) error
|
|
}
|
|
```
|
|
In `agentctl` this is `ChannelBackendClient`, which tunnels over the agent-stream WebSocket and lands on handlers registered against `internal/mcp/handlers.Handlers` on the backend's `ws.Dispatcher`.
|
|
|
|
Reuse path: register a second `mcp.Server` instance **inside the backend**, pointed at a `BackendClient` that calls the same `ws.Dispatcher` directly — no WS round-trip, no tunneling. The dispatcher is just a `map[string]Handler`, so direct dispatch is a one-line call.
|
|
|
|
## File map
|
|
|
|
**Move**
|
|
- `internal/agentctl/server/mcp/` → `internal/mcp/server/` (package renamed `mcpserver`).
|
|
- Two import sites to update: `cmd/agentctl/main.go`, `internal/agentctl/server/api/server.go`.
|
|
- Test files come along.
|
|
|
|
**Modify** (`internal/mcp/server/server.go`)
|
|
- `New(...)` keeps current signature — sessionID/taskID stay (used in log fields), pass empty strings for the backend instance.
|
|
- Add `RegisterRoutesAt(router gin.IRouter, basePath string)` that registers `<basePath>`, `<basePath>/sse`, `<basePath>/message`. Existing `RegisterRoutes` keeps registering at root for agentctl.
|
|
- Pass `basePath` through to `WithBaseURL` so the SSE event embeds the right `messageEndpoint` URL.
|
|
|
|
**New** (`internal/mcp/external/`)
|
|
- `direct_backend.go` — `DirectBackendClient` wraps a `*ws.Dispatcher`, implements `BackendClient.RequestPayload` by building a `*ws.Message`, calling `Dispatch`, returning the unmarshalled payload.
|
|
- `provider.go` — `Provide(dispatcher *ws.Dispatcher, baseURL string, log *logger.Logger) (*mcpserver.Server, error)` constructs the MCP server in `ModeConfig` with `disableAskQuestion=true`.
|
|
- `direct_backend_test.go`, `provider_test.go` — unit + integration tests.
|
|
|
|
**Modify** (`cmd/kandev/helpers.go`)
|
|
- After `mcpHandlers.RegisterHandlers(p.gateway.Dispatcher)` in `registerMCPAndDebugRoutes`, build the external MCP server with `external.Provide(p.gateway.Dispatcher, "http://localhost:<port>", p.log)` and call `srv.RegisterRoutesAt(p.router, "/mcp")`.
|
|
- Wire its `Close()` into the existing cleanup chain.
|
|
|
|
**Modify** (frontend)
|
|
- New "External MCP" panel in Settings. Static — shows the URL, copy button, and ready-to-paste snippets for Claude Code, Cursor, Codex. No backend calls.
|
|
- File: `apps/web/components/settings/external-mcp/external-mcp-panel.tsx` + add to settings index.
|
|
|
|
**Cleanup** (deferred to its own commit)
|
|
- Remove `ports.MCP = 40429` (`internal/common/ports/ports.go`).
|
|
- Remove `McpServerEnabled`, `McpServerPort` from `internal/agentctl/server/config/config.go`.
|
|
- Remove the unused `40429` constant in `apps/cli/src/constants.ts`.
|
|
|
|
## Tool surface (v1)
|
|
|
|
Config-mode tools as currently registered in `(*Server).registerConfigWorkflowTools / Agent / Mcp / Executor / Task` plus `create_task_kandev` from kanban tools. Excluded:
|
|
|
|
- `ask_user_question_kandev` (no UI loop for external invocations).
|
|
- `create_task_plan_kandev`, `get/update/delete_task_plan_kandev` (require a live session).
|
|
- Internal-only: `clarification_timeout`.
|
|
|
|
Implementation: add a `ModeExternal` constant or a `WithoutAskQuestion + WithoutPlanTools` option. Simplest: introduce `ModeExternal` that registers exactly the tools above. Reuses every existing handler.
|
|
|
|
## Phases
|
|
|
|
1. **Refactor (no behavior change).** Move the package, rename imports, add `RegisterRoutesAt`. Add `ModeExternal` constant + branch in `registerTools()`. All existing tests pass.
|
|
2. **Backend wiring.** New `internal/mcp/external/` package with `DirectBackendClient` and `Provide`. Wire into `helpers.go`.
|
|
3. **Frontend Settings panel.** Static React panel with copy-to-clipboard for the three snippets.
|
|
4. **Tests.** Unit tests for `DirectBackendClient` (round-trips through dispatcher). Integration test that boots a Gin router with the provider and runs `tools/list` + a representative `tools/call` (`list_workspaces_kandev`) over real HTTP using `mcp-go` client.
|
|
5. **Cleanup.** Delete dead `40429`-related code.
|
|
6. **Verify.** `make fmt` then `make typecheck test lint` (backend); `pnpm typecheck test lint` (web).
|
|
|
|
## Risks / open points
|
|
|
|
- **mcp-go path prefix support.** Need to confirm `WithBaseURL("http://localhost:38429/mcp")` correctly emits the `/mcp/message?sessionId=…` URL in the SSE handshake. If not, register at root with a Gin `Group("/mcp")` and have the SSE handler be unaware of the prefix — Gin strips it before the wrapped handler sees it. Will validate during Phase 1.
|
|
- **Route conflicts.** Backend Gin router currently has `/ws`, `/health`, `/api/v1/*`, plus debug & pprof routes. `/mcp` is unused. Verified.
|
|
- **Direct dispatch concurrency.** `ws.Dispatcher` is read-only after registration; safe to call from many goroutines. No locking needed in `DirectBackendClient`.
|
|
- **Session-scoped tool handlers expecting non-empty session/task IDs.** Config-mode handlers don't inspect `sessionID`/`taskID` (they take params from the payload). Confirmed in `internal/mcp/handlers/config_*_handlers.go`. The `create_task_kandev` handler also takes everything from payload. Safe.
|
|
- **Logging noise.** The MCP server logs every tool call with `session_id`. With backend-mode it'll be empty — acceptable, but worth filtering or noting.
|
|
|
|
## Out of scope (per spec)
|
|
|
|
Auth, remote binding, session-scoped tools, per-workspace scoping. Token-based auth is the most likely follow-up.
|