# MCP Server Templates

Production-grade MCP server starter templates with permission boundaries, integration tests, and eval contracts.

## Templates

| Template | Description | Key Features |
|---|---|---|
| [basic](./templates/basic/) | Minimal MCP server | Echo + calculate tools, Zod validation |
| [database](./templates/database/) | Read-only database access | SQL validation, schema introspection, permission boundaries |
| [api-gateway](./templates/api-gateway/) | External API proxy | Rate limiting, credential scoping, endpoint configuration |

## Quick Start

1. Clone this repo or use "Use this template" on GitHub
2. Navigate to the template you want: `cd templates/basic`
3. Install dependencies: `pnpm install`
4. Start the server: `pnpm start`

## Architecture

Each template follows the same patterns:

- **Permission engine** — Declarative rules (allow/deny) evaluated before every tool invocation
- **In-memory test client** — Integration tests via MCP SDK's InMemoryTransport
- **Eval contracts** — YAML eval specs compatible with [@visystems/claude-eval-runner](https://github.com/VISystems/claude-eval-runner)

### Shared Utilities

The `shared/` directory contains reusable utilities:

- `permissions/` — Permission policy types, engine, and PermissionDeniedError
- `testing/` — In-memory MCP test client for integration tests
- `errors/` — Typed error classes

## Development

```bash
pnpm install
pnpm typecheck    # TypeScript type checking
pnpm test         # Run all tests
pnpm test:shared  # Run shared utility tests only
pnpm test:basic   # Run basic template tests only
```

## License

Apache 2.0 — see [LICENSE](./LICENSE).