MCP 服务器

nexus-mcp

MCP server for the Plugin Federation Nexus control plane, enabling coding agents and humans to inspect catalogs, plugins, proposals, and run governance actions via GitHub SSO or OIDC.

README

nexus-mcp

TypeScript MCP server for the Plugin Federation Nexus control plane. Coding agents and humans can inspect catalogs, judge opinions, plugins, proposals, and run governance writes — without pasting long-lived Nexus API tokens.

MCP protocol

Item	Value
Spec revision	`2026-07-28` (stateless modern core)
TypeScript SDK	`@modelcontextprotocol/server@^2` (MCP SDK v2)
Schema validation	Zod v4 (`zod/v4`)
Transport	stdio (primary); protocol versions advertised include modern + 2025-era fallbacks

Configured in src/mcp-protocol.ts via supportedProtocolVersions (modern 2026-07-28 first).

Security model

Identity	How it authenticates	Nexus credential
Human (Cursor, Claude Desktop, local agent)	GitHub SSO — device flow (`GITHUB_OAUTH_CLIENT_ID`) or existing `gh auth login` session	Short-lived Nexus JWT via `provider: github_user` (memory only)
GitHub Actions / coding agents in GitHub	GitHub OIDC (`permissions: id-token: write`) + tenant OIDC trust policy	Short-lived Nexus JWT via `provider: github_actions` (memory only)

Not supported (by design):

NEXUS_ACCESS_TOKEN / NEXUS_BEARER_TOKEN (static control-plane secrets)
Gateway enrollment / workload / bootstrap credential tools
Recording tool catalogs or analyses from chat (CI + OIDC Actions own evidence)

Nexus remains the only issuer of API JWTs (ADR 0008).

Tools (v0.1)

Orientation: get_session, get_tenant, list_pipeline_checks

Plugins: list_plugins, create_plugin, get_plugin_draft, replace_plugin_draft, compose_plugin_draft, list_plugin_variants, list_plugin_revisions

Quality: get_tool_catalog, list_tool_analyses, list_tool_judges, get_tool_judge, create_tool_judge, update_tool_judge, get_latest_schema_verification, summarize_source_quality, find_fix_suggestions_for_tool

Governance: get_proposal, create_proposal, create_proposal_from_schema_verification, decide_proposal (confirm), release_plugin_revision (confirm), promote_plugin_revision (confirm)

Exports: get_compatibility_report, create_export, get_export_job

Audit: list_audit_events

Setup

npm install
npm run build

Environment

Variable	Required	Purpose
`NEXUS_URL`	yes	e.g. `https://api.nonprod.plugin-federation.com`
`TENANT_ID`	Actions OIDC	Tenant UUID matching OIDC trust policy; also preferred tenant for multi-membership humans
`NEXUS_OIDC_AUDIENCE`	Actions	Must match Nexus `NEXUS_OIDC_GITHUB_AUDIENCE` (defaults to `NEXUS_URL`)
`GITHUB_OAUTH_CLIENT_ID`	humans (device flow)	Public OAuth App client id for device flow
`NEXUS_MCP_ALLOW_GH_CLI`	no	Default `true` — use `gh auth token` when device flow client id unset
`NEXUS_MCP_GITHUB_USER_TOKEN`	no	Optional GitHub user OAuth token injected by a host (still exchanged; never a Nexus JWT)

Human (local)

# Option A: GitHub CLI already SSO'd
gh auth login
export NEXUS_URL=https://api.nonprod.plugin-federation.com
export TENANT_ID=<optional-preferred-tenant>
npx tsx src/index.ts

# Option B: device flow
export GITHUB_OAUTH_CLIENT_ID=<public-oauth-app-client-id>
npx tsx src/index.ts
# Follow the verification URL + user code on stderr

GitHub Actions / coding agent

permissions:
  id-token: write
  contents: read
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: "22"
  - run: npm ci && npm run build
    working-directory: path/to/nexus-mcp
  - name: Run agent with Nexus MCP
    env:
      NEXUS_URL: ${{ vars.NEXUS_URL }}
      TENANT_ID: ${{ vars.TENANT_ID }}
      NEXUS_OIDC_AUDIENCE: ${{ vars.NEXUS_OIDC_AUDIENCE }}
    run: node path/to/nexus-mcp/dist/index.js

Register owner/repo (immutable ids) on a Nexus OIDC trust policy with the roles the agent needs (contributor / approver / etc.).

MCP client config (stdio example)

{
  "mcpServers": {
    "nexus": {
      "command": "node",
      "args": ["/absolute/path/to/nexus-mcp/dist/index.js"],
      "env": {
        "NEXUS_URL": "https://api.nonprod.plugin-federation.com",
        "TENANT_ID": "11111111-1111-4111-8111-111111111111",
        "GITHUB_OAUTH_CLIENT_ID": "Ov23li…"
      }
    }
  }
}