Skip to content

feat(mcp): add admin Plexus management server#565

Merged
mcowger merged 11 commits into
mainfrom
feat/mcp-admin-server
Jun 6, 2026
Merged

feat(mcp): add admin Plexus management server#565
mcowger merged 11 commits into
mainfrom
feat/mcp-admin-server

Conversation

@mcowger
Copy link
Copy Markdown
Owner

@mcowger mcowger commented Jun 6, 2026

Summary

  • add an admin-only /mcp/plexus MCP server using the official MCP SDK
  • register compact Plexus management tools plus a management guide prompt/resource
  • reserve plexus as an upstream MCP gateway name and redact secrets in tool responses
  • serialize singleton SDK transport usage and clamp x-forwarded-proto to http/https

Verification

  • bun run test
  • bun run typecheck (packages/backend)
  • bun run format:check
  • pre-commit hooks passed on commit

@greptile-apps
Copy link
Copy Markdown
Contributor

greptile-apps Bot commented Jun 6, 2026

Greptile Summary

This PR introduces an admin-only /mcp/plexus MCP server backed by the official SDK, wires up twelve compact management tools for read-only Plexus inspection, and reserves plexus as a blocked upstream gateway name. Several related fixes land alongside it: quota-enforcement routes now flush ConfigService before reading config so freshly saved keys are visible immediately, and the frontend getStats helper is simplified to use the pre-computed usage summary endpoint.

  • plexus.ts: per-request McpServer + WebStandardStreamableHTTPServerTransport creation with authenticate/requireAdmin pre-handler hooks; x-forwarded-proto is clamped to http/https in URL construction; secrets are redacted before every tool response.
  • mcp-proxy-service.ts / config.ts: a RESERVED_SERVER_NAMES set blocks plexus from both the proxy lookup and the server-name validation API, preventing an upstream config entry from shadowing the admin endpoint.
  • quota-enforcement.ts: replaces the stale module-level getConfig() call with configService.flush() + configService.getConfig() on both the clear and status endpoints.

Confidence Score: 5/5

Safe to merge — all changes are additive with no schema migrations or breaking API changes

The core logic is straightforward: a new per-request MCP server wired behind existing admin auth hooks, a reserved-name guard in the proxy service, and a config-flush fix in quota enforcement. The only findings are correctness nits in three in-operator existence checks that affect only admin-facing tool responses.

packages/backend/src/routes/mcp/plexus.ts — three in-operator existence checks should use Object.hasOwn

Important Files Changed

Filename Overview
packages/backend/src/routes/mcp/plexus.ts New admin-only MCP server wiring all Plexus management tools; per-request server creation correctly addresses the previous singleton concern; in operator used for existence checks admits inherited prototype properties
packages/backend/src/routes/mcp/index.ts Registers plexus MCP routes before the generic /mcp/:name gateway block; ordering is correct — static /mcp/plexus route wins over the dynamic param route
packages/backend/src/services/mcp-proxy/mcp-proxy-service.ts Adds RESERVED_SERVER_NAMES set and gates both getMcpServerConfig and validateServerName on it; straightforward and correct
packages/backend/src/routes/management/quota-enforcement.ts Switches from module-level getConfig() to ConfigService with an explicit flush() before reads; ensures quota status reflects freshly saved keys
packages/backend/src/routes/management/config.ts Delegates server-name validation to the shared validateServerName helper, which now blocks the reserved plexus name; safe mechanical change
packages/frontend/src/lib/api.ts getStats switched from fetching up to 1000 raw records and computing totals client-side to using the pre-computed summary endpoint; cleaner and faster
packages/backend/src/routes/mcp/tests/plexus-mcp-routes.test.ts Good coverage of auth enforcement, tool listing, secret redaction, destructive-op ack, and the reserved-name guard
packages/backend/src/routes/management/tests/quota-enforcement.test.ts Verifies flush-before-read ordering for the quota status endpoint with a targeted integration test

Reviews (2): Last reviewed commit: "fix(frontend): use usage summary for wee..." | Re-trigger Greptile

Comment thread packages/backend/src/routes/mcp/plexus.ts Outdated
Comment thread packages/backend/src/routes/mcp/plexus.ts
Comment thread packages/backend/src/routes/mcp/plexus.ts Outdated
mcowger and others added 9 commits June 6, 2026 03:06
## Summary
- Update quota enforcement management routes to use ConfigService
directly instead of legacy getConfig
- Flush ConfigService before quota status and quota clear operations so
newly saved keys/quotas are immediately visible
- Add a regression test covering immediate quota status lookup after
config refresh

## Validation
- bun run test src/routes/management/__tests__/quota-enforcement.test.ts
- bun run typecheck
- bun run format:check
- pre-commit hooks passed, including backend changed tests and workspace
typecheck
## Summary
- Add a plexus-management agent skill for administering Plexus through
the management API
- Include curl/jq workflows, endpoint reference, safety guidance, and
eval prompts
- Document admin authentication via PLEXUS_BASE_URL and PLEXUS_ADMIN_KEY

## Validation
- pre-commit hooks passed during commit
- no dev admin key or password is included in the skill files

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Removed bash script for loading endpoint map and clarified fallback method.
@mcowger mcowger merged commit 54788be into main Jun 6, 2026
2 checks passed
@mcowger mcowger deleted the feat/mcp-admin-server branch June 6, 2026 03:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant