# MCPist

MCP (Model Context Protocol) gateway service — Connect AI assistants to external tools through a single endpoint.

## Usage

Add to your MCP client configuration (Claude Code, Cursor, etc.):

```json
{
  "mcpServers": {
    "mcpist": {
      "url": "https://mcp.mcpist.app/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
```

Get your API key at [mcpist.app](https://mcpist.app).

## Supported Modules

Notion, GitHub, Jira, Confluence, Google Workspace (Sheets, Docs, Drive, Calendar, Tasks), Todoist, TickTick, Microsoft Todo, Asana, Trello, Airtable, Dropbox, PostgreSQL, Grafana, and more.

## Architecture

```
Console (Next.js / Vercel)
    ↓
Worker (Cloudflare Workers) — Auth + Routing
    ↓
Server (Go / Render) — MCP Handler + REST API
    ↓
PostgreSQL
```

### Authentication

1. **User auth**: Clerk (JWT) via Console
2. **API keys**: Ed25519 JWT issued by Server
3. **Gateway auth**: Worker signs short-lived JWT for Server-to-Server trust

## Tech Stack

| Layer | Technology |
|-------|------------|
| Frontend | Next.js 16, React 19, Tailwind CSS, Radix UI |
| API Gateway | Cloudflare Workers, Hono, TypeScript |
| Backend | Go 1.24, GORM |
| Database | PostgreSQL |
| Auth | Clerk, Ed25519 JWT |
| Billing | Stripe |
| Observability | Grafana Loki |
| Monorepo | pnpm workspaces, Turborepo |

---

## Development

### Prerequisites

- Node.js 20+
- pnpm 9
- Go 1.24+
- Docker Desktop

### Setup

```bash
pnpm install
cp .env.example .env.local   # Edit with your values
pnpm env:sync
```

### Run

```bash
pnpm dev
```

Starts PostgreSQL (Docker), Console, Server, and Worker concurrently.

| Service | URL | Description |
|---------|-----|-------------|
| PostgreSQL | localhost:57432 | Database (Docker) |
| Console | http://localhost:3000 | Web UI |
| Server | http://localhost:8089 | MCP Server |
| Worker | http://localhost:8787 | API Gateway |

```bash
pnpm db:down    # Stop PostgreSQL container
```

### Scripts

| Command | Description |
|---------|-------------|
| `pnpm dev` | Start DB + all apps |
| `pnpm db:up` | Start PostgreSQL only |
| `pnpm db:down` | Stop PostgreSQL |
| `pnpm dev:console` | Console only |
| `pnpm dev:server` | Go Server only (Air hot reload) |
| `pnpm dev:worker` | Worker only (Wrangler) |
| `pnpm build` | Build all apps (Turbo) |
| `pnpm lint` | Lint all apps |
| `pnpm test` | Run tests |
| `pnpm env:sync` | Distribute .env.local to each app |
| `pnpm erd:build` | Generate ER diagram from schema |

### Project Structure

```
mcpist/
├── apps/
│   ├── console/        # Web UI
│   ├── server/         # MCP Server + REST API
│   └── worker/         # API Gateway
├── database/
│   └── migrations/     # PostgreSQL schema
├── docs/               # Specifications & design docs
├── scripts/            # Dev utilities
└── .github/workflows/  # CI
```

### Deployment

| App | Platform | Domain |
|-----|----------|--------|
| Console | Vercel | mcpist.app |
| Worker | Cloudflare Workers | mcp.mcpist.app |
| Server | Render | mcpist.onrender.com |
| Database | Neon | — |

### API Specification

OpenAPI 3.1 spec: `GET /openapi.json`
Source: `apps/worker/src/openapi.yaml`