server copilot-instructions.md

MCP Ambassador Server — Copilot Instructions

Repo Context

This is the mcpambassador_server repository — a pnpm monorepo containing the Ambassador Server. It is the core of the platform: a Fastify HTTP server with a React SPA, SQLite database, and a plugin-based architecture for auth, authorization, and audit.

Version: 0.8.0-beta.1
Stack: Node.js 20+, TypeScript strict, pnpm workspaces, Fastify, Zod, Drizzle ORM (SQLite), React 19, Tailwind v4, Vite, Docker

Monorepo Package Structure

packages/
  core/          # Database schema (Drizzle), migrations, shared types
  protocol/      # MCP protocol types and wire format
  contracts/     # Shared Zod schemas for API contracts
  authn-ephemeral/ # SPI implementation: authentication (ephemeral sessions)
  authz-local/   # SPI implementation: authorization (local RBAC)
  audit-file/    # SPI implementation: audit logging (append-only file)
  server/        # Main Fastify server, routes, plugin wiring
  spa/           # React 19 SPA (admin + user UI)

Architecture Patterns

SPI (Service Provider Interface)

AuthN, AuthZ, and Audit are injected as SPI plugins — never hardcoded. The server core depends on interfaces (IAuthnProvider, IAuthzProvider, IAuditProvider), not implementations. When adding auth-related code, always work through these interfaces.

Fastify Conventions

• All routes must use schema: { body: ZodSchema, params: ZodSchema } — never skip validation
• Error responses use the canonical format: { error: { code: string, message: string } }
• Never expose stack traces, internal error messages, or Zod validation internals in responses
• Use Fastify's reply.code(n).send(...) pattern consistently

Drizzle ORM

• Schema lives in packages/core/src/schema.ts
• Migrations live in packages/core/drizzle/
• Any schema change requires a migration — do NOT use push in production
• Sensitive columns (credentials, tokens) are encrypted at the application layer before storage