Skip to content

Admin tools through the MCP - #3

Merged
springfall2008 merged 14 commits into
mainfrom
feat/mcp-admin
Nov 7, 2026
Merged

springfall2008 merged 14 commits into
mainfrom
feat/mcp-admin

Conversation

@springfall2008

Copy link
Copy Markdown
Owner

What this does

Admins can manage the memory from any Claude session, using only their own MCP token. The only shell step left is creating the database once. After that, an admin can onboard a new member (create the member, grant scopes, issue a token) or offboard one, just by asking Claude.

Design: docs/superpowers/specs/2026-11-07-mcp-admin-design.md. Plan: docs/superpowers/plans/2026-11-07-mcp-admin.md.

Rules

  • The admin flag. Members carry an admin flag. A bot can never be an admin; the database refuses it.
  • Admin tools. Admins see 12 extra admin_ tools: list, create and delete scopes; list, create and deactivate members; list grants, grant and revoke; issue, list and revoke tokens. Everyone else, including the bot, sees the same 11 tools as before.
  • Never another admin. The admin tools never act on another admin. Promoting and demoting admins, and reactivating members, stay shell-only (admin.ts set-admin, reactivate).
  • Self-protection. No self-deactivation, no revoking your own last live token, and the shell can't remove the last active admin.
  • Deactivate, not delete. Deactivation revokes all of a member's tokens and grants and drops their admin flag, but keeps their name on what they wrote.
  • Admin log. Every admin action, from Claude or the shell, is recorded with who did it. Token values are never recorded. Read it with admin.ts admin-log.
  • Issued tokens come back once, in the tool reply.

How it is enforced

The rules live once, in Postgres.

  • Core functions. Postgres-only adm_* functions do each action and write the log. The shell admin script calls these.
  • Member-callable wrappers. admin_* SECURITY DEFINER wrappers check the caller is an active admin and apply the other-admin and self rules before calling adm_*.
  • Token resolution. It now also requires the member to be active.
  • Edge Function. It registers the admin tools only for admins, and the database refuses non-admins anyway.

Also

  • setup.ts makes its human member the first admin. Existing installs run admin.ts set-admin <member> on once.
  • New shell commands: set-admin, deactivate, reactivate, delete-scope, admin-log, list-members.
  • Backup and restore keep the admin flags and deactivation state. The admin log isn't exported. Older backups still load.
  • smoke.ts accepts admin tokens.
  • The README covers the admin flow, how an onboarded member connects, and a caution against auto-allowing admin_ tools.

Migration

20261107150000_admin.sql adds two columns to members (is_admin default false; deactivated_at null), adds the admin_log table, and creates functions. It drops, truncates and rewrites nothing.

Testing

  • pgTAP: 260 tests, including 51 for the core and 68 for the wrappers. Each security guard was shown to fail when removed.
  • Unit: 70. Integration: 68. End to end over real MCP: an admin sees 23 tools, a non-admin and the bot see 11, and calling an admin tool as a non-admin fails like an unknown tool. Onboarding works end to end, and a deactivated member's token gets 401.
  • Already applied to the maintainer's project (a backup was taken first) and verified there: an admin sees 23 tools, the bot 11, and onboarding then deactivation through the MCP works. The admin log recorded every step.

Left for later (shell-only edge cases; each needs a new migration): refuse set-admin on for a deactivated member, and record was_admin in the deactivation log.

🤖 Generated with Claude Code

springfall2008 and others added 14 commits November 7, 2026 14:58
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s admin

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@springfall2008
springfall2008 merged commit 2f145e8 into main Nov 7, 2026
1 check passed
@springfall2008
springfall2008 deleted the feat/mcp-admin branch November 7, 2026 16:34
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