mcp-shell

A reusable governed MCP server shell: you supply one GovernedAdapter; the shell adds Streamable-HTTP transport, Auth0/JWT auth, scope-gated capability visibility, and audit logging.

The adapter swap point is src/adapter.ts; src/core/types.ts defines the contract, and src/adapters/example is the worked example.

What this is

src/core/ is the reusable shell that owns transport, auth, capability filtering, and audit flow. src/adapters/ is where concrete adapters declare scopes and capabilities; src/adapter.ts selects the one that ships. Consumers clone this source repo, provide or select an adapter, build an image, and deploy that image in their own account. Deployment profiles consume only the built image digest and profile inputs.

Run it locally (30 seconds)

npm ci
npm run dev:local
curl -fsS localhost:8000/health && curl -fsS localhost:8000/ready
npm run verify:adapter   # proves scoped MCP calls (example + a custom demo adapter) without Auth0

With auth off, scoped capabilities are hidden until a token is presented — use verify:adapter (a local signed-token harness) to exercise tools/resources/prompts. /health and /ready are the bare liveness signal.

Stand it up in your own account

Full step-by-step: SETUP.md.

1. Clone and verify locally: npm ci && npm run build && npm test.
2. Set up Auth0 in your tenant: deploy/AUTH0.md.
3. Build the image from source and push to your own registry, usually ECR on AWS: deploy/IMAGE.md.
4. Pick a deploy profile and fill its inputs: deploy/README.md.
5. Deploy, fastest with ECS Fargate: deploy/ecs-fargate/README.md.
6. Verify /health, /ready, an unauthenticated /mcp bearer challenge, then scoped tools/list: deploy/AUTH0.md step 7.

Deploy profiles

Profile	Use when	Doc
ECS Fargate	You have an AWS account and want the fastest managed profile.	deploy/ecs-fargate/README.md
Kubernetes	You already have a cluster and ingress stack.	deploy/k8s/README.md
Compose	You want a VPS, local host, or smallest footprint.	deploy/compose/README.md
Lambda	Roadmap only; the app needs stateless transport or external session storage first.	deploy/lambda/README.md

For the shared logical input contract, start at deploy/README.md.

Documentation map

• Setup / onboarding: SETUP.md
• Architecture diagram: docs/architecture.drawio
• Adapter authoring guide: docs/ADAPTERS.md
• Hardening roadmap: docs/HARDENING.md
• Auth sequence diagram: docs/auth.html
• Hosted MCP client connection: docs/CONNECT-CLIENT.md
• Deploy profile router: deploy/README.md
• Image build and registry path: deploy/IMAGE.md
• Auth0 tenant setup: deploy/AUTH0.md
• Environment model: deploy/ENVIRONMENTS.md
• AWS bootstrap: deploy/aws-bootstrap.md
• Maintainer release flow: RELEASING.md

Local development

Command	Script
npm run dev:local	MCP_SHELL_REQUIRE_AUTH=false tsx watch src/server.ts
npm run serve:local	MCP_SHELL_REQUIRE_AUTH=false node --import tsx src/server.ts
npm run dev	tsx watch src/server.ts; requires Auth0 env, or use npm run dev:local
npm run build	tsc -p tsconfig.json
npm run verify:adapter	node --import tsx scripts/smoke-localverify.mjs
npm test	vitest run
npm run lint	eslint .
npm run format	prettier --write package.json tsconfig.json "*.{js,ts}" "src/**/*.ts" "test/**/*.ts"

Releasing / maintainers

See RELEASING.md.