mcpctl/docs/architecture.md

# mcpctl Architecture

## Overview

mcpctl is a kubectl-like management tool for MCP (Model Context Protocol) servers. It consists of a CLI, a daemon server, a database layer, a local proxy, and shared utilities.

## Package Structure

```
src/
├── cli/          @mcpctl/cli          - Command-line interface
├── mcpd/         @mcpctl/mcpd         - Daemon server (REST API)
├── db/           @mcpctl/db           - Database layer (Prisma + PostgreSQL)
├── local-proxy/  @mcpctl/local-proxy  - MCP protocol proxy
└── shared/       @mcpctl/shared       - Shared constants and utilities
```

## Component Diagram

```
┌─────────────────┐     HTTP      ┌──────────────┐     Prisma     ┌────────────┐
│   mcpctl CLI    │ ──────────────│    mcpd      │ ──────────────│ PostgreSQL │
│  (Commander.js) │               │  (Fastify 5) │               │            │
└─────────────────┘               └──────┬───────┘               └────────────┘
                                         │
                                         │ Docker/Podman API
                                         ▼
                                  ┌──────────────┐
                                  │  Containers  │
                                  │ (MCP servers)│
                                  └──────────────┘

┌─────────────────┐    STDIO     ┌──────────────┐    STDIO/HTTP   ┌────────────┐
│  Claude / LLM   │ ────────────│  local-proxy  │ ──────────────│ MCP Servers│
│                 │              │  (McpRouter)  │               │            │
└─────────────────┘              └──────────────┘               └────────────┘
```

## CLI (`@mcpctl/cli`)

The CLI is built with Commander.js and communicates with mcpd via HTTP REST.

### Commands

| Command | Description |
|---------|-------------|
| `mcpctl get <resource>` | List resources (servers, profiles, projects, instances) |
| `mcpctl describe <resource> <id>` | Show detailed resource info |
| `mcpctl apply <file>` | Apply declarative YAML/JSON configuration |
| `mcpctl setup [name]` | Interactive server setup wizard |
| `mcpctl instance list/start/stop/restart/remove/logs/inspect` | Manage instances |
| `mcpctl claude generate/show/add/remove` | Manage .mcp.json files |
| `mcpctl project list/create/delete/show/profiles/set-profiles` | Manage projects |
| `mcpctl config get/set/path` | Manage CLI configuration |
| `mcpctl status` | Check daemon connectivity |

### Configuration

CLI config is stored at `~/.config/mcpctl/config.json` with:
- `daemonUrl`: mcpd server URL (default: `http://localhost:4444`)

## Daemon (`@mcpctl/mcpd`)

Fastify 5-based REST API server that manages MCP server lifecycle.

### Layers

1. **Routes** - HTTP handlers, parameter extraction
2. **Services** - Business logic, validation (Zod schemas), error handling
3. **Repositories** - Data access via Prisma (interface-based for testability)

### API Endpoints

| Endpoint | Methods | Description |
|----------|---------|-------------|
| `/api/v1/servers` | GET, POST | MCP server definitions |
| `/api/v1/servers/:id` | GET, PUT, DELETE | Single server operations |
| `/api/v1/profiles` | GET, POST | Server configuration profiles |
| `/api/v1/profiles/:id` | GET, PUT, DELETE | Single profile operations |
| `/api/v1/projects` | GET, POST | Project management |
| `/api/v1/projects/:id` | GET, PUT, DELETE | Single project operations |
| `/api/v1/projects/:id/profiles` | GET, PUT | Project profile assignments |
| `/api/v1/projects/:id/mcp-config` | GET | Generate .mcp.json |
| `/api/v1/instances` | GET, POST | Instance lifecycle |
| `/api/v1/instances/:id` | GET, DELETE | Instance operations |
| `/api/v1/instances/:id/stop` | POST | Stop instance |
| `/api/v1/instances/:id/restart` | POST | Restart instance |
| `/api/v1/instances/:id/inspect` | GET | Container inspection |
| `/api/v1/instances/:id/logs` | GET | Container logs |
| `/api/v1/audit-logs` | GET | Query audit logs |
| `/api/v1/audit-logs/:id` | GET | Single audit log |
| `/api/v1/audit-logs/purge` | POST | Purge expired logs |
| `/health` | GET | Health check (detailed) |
| `/healthz` | GET | Liveness probe |

### Container Orchestration

The `McpOrchestrator` interface abstracts container management:
- `DockerContainerManager` - Docker/Podman implementation via dockerode
- Future: `KubernetesOrchestrator` for k8s deployments

## Local Proxy (`@mcpctl/local-proxy`)

Aggregates multiple MCP servers behind a single STDIO endpoint.

### Features

- **Tool namespacing**: `servername/toolname` routing
- **Resource forwarding**: `resources/list` and `resources/read`
- **Prompt forwarding**: `prompts/list` and `prompts/get`
- **Notification pass-through**: Upstream notifications forwarded to client
- **Health monitoring**: Periodic health checks with state tracking
- **Transport support**: STDIO (child process) and HTTP (SSE/Streamable HTTP)

### Usage

```bash
# Via config file
mcpctl-proxy --config proxy.json

# Via CLI flags
mcpctl-proxy --upstream "slack:npx -y @anthropic/slack-mcp" \
             --upstream "github:npx -y @anthropic/github-mcp"
```

## Database (`@mcpctl/db`)

Prisma ORM with PostgreSQL. Key models:

- **User** / **Session** - Authentication
- **McpServer** - Server definitions (name, transport, package, docker image)
- **McpProfile** - Per-server configurations (env overrides, permissions)
- **Project** - Grouping of profiles for a workspace
- **McpInstance** - Running container instances with lifecycle state
- **AuditLog** - Immutable operation audit trail

## Shared (`@mcpctl/shared`)

Constants and utilities shared across packages:
- `APP_NAME`, `APP_VERSION`
- Common type definitions

## Design Principles

1. **Interface-based repositories** - All data access through interfaces for testability
2. **Dependency injection** - Services receive dependencies via constructor
3. **Zod validation** - All user input validated with Zod schemas
4. **Namespaced errors** - Custom error classes with HTTP status codes
5. **TypeScript strict mode** - `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`