mcp-conductor CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project summary

conductor is a tool gateway for AI agents. It speaks MCP to clients and aggregates tools from multiple backends (ToolProvider implementations) behind bearer-token auth, group-based access control, and full audit. Packaged as a pnpm workspace.

Commands

Run from the repo root — all scripts fan out across packages via pnpm workspace filters.

• pnpm install — install + link workspaces
• pnpm build — tsc -p tsconfig.build.json in each package (packages/*)
• pnpm typecheck — tsc --noEmit per package (checks both src/ and tests/)
• pnpm test — run the full vitest suite (workspace config at vitest.workspace.ts)
• pnpm test:watch — vitest in watch mode
• pnpm clean — wipe dist/ and .tsbuildinfo everywhere
• pnpm dev — run the server via tsx packages/server/src/cli.ts (honours CONDUCTOR_CONFIG)
• pnpm hash-key <plaintext> — prints sha256:<hex> for an API key (what the config expects)

Running a single test

Vitest's workspace picks up each package's vitest.config.ts. Target a specific file by path, and narrow inside a file with -t:

pnpm test -- packages/gateway/tests/auth.test.ts
pnpm test -- packages/gateway/tests/auth.test.ts -t "rejects invalid bearer"
# or scope by project name (packages self-name: "core", "gateway", etc.)
pnpm test -- --project gateway

Running the gateway locally

The repo ships a working config at examples/conductor.json (user alice, key changeme, one provider everything via npx @modelcontextprotocol/server-everything):

CONDUCTOR_CONFIG=examples/conductor.json pnpm dev
# → http://127.0.0.1:18080/mcp  (Authorization: Bearer changeme)
# → GET /health returns { ok, sessions, providers }

Architecture

Five packages in packages/*, strict layering — core has no sibling deps; gateway/provider-mcp/provider-openshell depend on core; server wires everything.