feat: embedded MCP server exposing the admin API as tools#44
Open
dfradehubs wants to merge 1 commit into
Open
Conversation
Add an opt-in MCP server (server.mcp.enabled, default port 8082) that exposes the entire admin API as ~61 MCP tools over Streamable HTTP. Authentication reuses server.adminPassword as a bearer token via a new middleware.BearerAuth that mirrors AdminAuth's constant-time compare and per-IP rate limiter. Tools call *store.Store directly. There is no HTTP roundtrip back to the admin port, following the spirit of decision achetronic#6 ("Admin UI never accesses the User API"). Skills upload/download and backup/restore remain on admin REST because binary archives do not map cleanly to MCP tool inputs. Implementation lives in server/api/mcp/, one tools_<resource>.go per admin resource group. Existing admin validators (ValidateFlowStep, ValidateClientConfig, SecretToResponse) are exported and reused so both surfaces enforce the same rules. Secret values are never returned by GET tools (magec_get_secret, magec_list_secrets), matching the admin REST redaction policy. Adds 'omitempty' to id and client.token tags in store.types so the SDK's JSON schema reflection does not mark server-assigned fields as required on the inputs of create_* tools. Docs: website/content/docs/admin-mcp-server.md plus sidebar entry. Decision record: .agents/DECISIONS.md achetronic#30.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #43.
Summary
magec-server(server.mcp.enabled, default port8082).server.adminPasswordas bearer via a newmiddleware.BearerAuththat mirrorsAdminAuth(constant-time compare + per-IP rate limit, 5 failures/min).*store.Storedirectly. No HTTP roundtrip back to admin port.Design notes
admin.ValidateFlowStep,admin.ValidateClientConfig,admin.SecretToResponseare exported and reused.*jsonschema.Schema{Type:"object"}becausestore.FlowStepis self-referential and the SDK's reflection-based schema generator does not support cycles. Runtime behaviour is unchanged.omitemptyadded toidtags andclient.tokeninstore/types.goso the MCP SDK does not mark server-assigned fields as required oncreate_*inputs. Wire shape on responses is unchanged because those fields are always populated at write time.server.adminPasswordkeeps both admin REST and MCP open with a clear startup WARN per surface (admin and MCP independently).Docs
website/content/docs/admin-mcp-server.mdwith enablement, auth, Claude Code / mcp-cli connection examples, full tool catalogue and troubleshooting.website/hugo.toml)..agents/AGENTS.md,.agents/MULTI_AGENT_ADMIN_API.mdupdated with pointers..agents/DECISIONS.mdadds decision Chore/complete code audit #30 covering motivation, trade-offs and the explicit do not list..agents/TODO.md"Recently Completed" entry.Test plan
go test -race ./api/mcp/... ./api/admin/... ./middleware/... ./store/...— green.server/api/mcp/tools_*_test.go.server_test.go): server connects, lists ≥50 tools, all representative tool names present.server_http_test.go): 401 without/with wrong bearer, anything-but-401 with correct bearer, open mode bypasses auth when password is empty.server.mcp.enabled: true. Verifiedinitialize→notifications/initialized→tools/list(61 tools) →tools/callfor create/update/delete across every resource group. Cross-surface verification: writes via MCP appear in admin REST immediately and vice versa.Out of scope
AdminAuthto callBearerAuthinternally. The two middlewares share the rate limiter and bearer extractor but differ in their/api/carve-out; consolidating is a follow-up.