@codemeta/mcp

Model Context Protocol server for Codemeta OS. Lets LLM clients (Claude Code, GitHub Copilot Chat, Cursor, Claude Desktop) read and act on Codemeta data on the user's behalf — safely.

Status

Phase 1 — internal MSP staff. The package is set up to publish to npm (@codemeta/mcp) but waits for the first real OAuth-flow validation against a deployed Codemeta API before the initial npm publish is cut.

Build

The package is bundled with tsup, NOT plain tsc. tsup inlines its only workspace-internal dependency (@codemeta/shared/mcp — a deliberately narrow subset of the shared package) into the published dist/ so the npm tarball is self-contained. keytar is an optionalDependencies entry: installs on machines with prebuilt binaries, the package gracefully falls back to in-memory token storage when the native build is unavailable.

pnpm --filter @codemeta/mcp build      # tsup → dist/
pnpm --filter @codemeta/mcp test       # vitest
pnpm --filter @codemeta/mcp typecheck  # tsc --noEmit

Safety posture

This is the central guarantee:

• No deletion. delete_entity / restore_entity are not exposed.
• No outbound communication. reply_to_email, convert_email_to_ticket, and any "send" verb are not exposed.
• No terminal-state transitions. Closing, archiving, cancelling, winning, losing, resolving an entity is blocked at the MCP layer.
• No external-visible comments. add_internal_comment is the only comment tool and forces visibility: 'internal'.
• No generic create/update. Writes go through narrow, allow-listed tools whose target schemas are timer, time_record, task, and note only.
• Every mutation requires user confirmation via a two-phase dry-run + apply-token cycle.
• Optimistic concurrency. Apply tokens carry the frozen entity version; a concurrent modification produces a 409 and the LLM must re-preview.

The corresponding ADR is docs/adr/0150-mcp-server-refinements.md in the parent repo.

Setup

Claude Code

claude mcp add codemeta -- npx -y @codemeta/mcp

GitHub Copilot Chat (VS Code)

Add to .vscode/mcp.json:

{
  "servers": {
    "codemeta": {
      "command": "npx",
      "args": ["-y", "@codemeta/mcp"]
    }
  }
}

Cursor / Claude Desktop

Add an stdio server entry analogous to the snippets above in the client's MCP config file.

Environment variables

| Variable | Default | Purpose | | --------------------------- | ------------------------ | -------------------------------------------------------------------- | | CODEMETA_API_URL | https://os.codemeta.de | Base URL of the Codemeta API instance. | | CODEMETA_MCP_CLIENT_ID | mcp-cli | OAuth client id; rarely changed. | | CODEMETA_MCP_TOKEN | (none) | Skip OAuth and use this opaque bearer token. Useful in CI. | | CODEMETA_MCP_TENANT_ID | (none) | Required only when CODEMETA_MCP_TOKEN is set; otherwise from OAuth.| | CODEMETA_MCP_EPHEMERAL | 0 | When 1, never store tokens in the OS keychain — in-memory only. |

How auth works

1. On the first tool call, the package looks for tokens in the OS keychain (keytar if available). If none, it spins up an ephemeral HTTP server on 127.0.0.1 between ports 33700–33799 and opens the user's browser to <api>/api/auth/oauth2/authorize?…&code_challenge=<S256>.
2. The user authenticates against Codemeta (email/password + 2FA, M365 SSO, or passkey — the existing better-auth flow). They pick a tenant (Customer-tenants are blocked) and consent to a scope (codemeta:read, codemeta:write, or codemeta:full).
3. The Codemeta API redirects back to the loopback URL with a code; the package exchanges it for an access token (opaque, 1 h TTL) + refresh token (30 d sliding).
4. Tokens land in the OS keychain. Subsequent process starts use them silently. Tenant-Admins can revoke them in Codemeta's normal /settings/sessions page.

Tool inventory

See packages/shared/src/constants/mcp-tool-registry.ts for the authoritative list with per-tool risk level, required module, and required permission. Phase 1 ships 30 tools:

• Generic reads (6): list_schemas, describe_schema, search_entities, get_entity, count_entities, audit_history.
• Entity-specific reads (12): search_tickets, get_ticket, search_parties, get_party, search_time_records, search_tasks, search_kb, get_kb_article, search_quotations, search_emails, list_my_inbox, get_email, list_my_running_timers, list_my_open_quotations.
• Safe writes (10): start_timer, stop_timer, log_time, assign_ticket, transition_status (non-terminal), add_internal_comment, create_task, update_task (non-terminal), link_ticket_to_party, switch_tenant, logout.

License

Apache-2.0. See LICENSE.