# Geektastic MCP Server

A self-hosted **MCP (Model Context Protocol) server** with a **Web management UI** that
exposes the **Geektastic Realms** and **Geektastic Family Tree** applications to MCP
clients (Claude Desktop/Code and others). Deploys as a Docker stack via **Portainer**,
and is architected so additional applications can be plugged in over time.

- **Integrations:** Geektastic Realms REST/HTTP API, Geektastic Family Tree JSON API
- **Stack:** TypeScript full-stack (Node + `@modelcontextprotocol/sdk` backend, React UI)
- **MCP transport:** Streamable HTTP (remote clients, bearer-token auth)
- **Storage:** PostgreSQL (Prisma ORM)
- **Access:** multi-user Web login with roles (admin + member), admin-managed accounts
- **Web UI:** connections & secrets, per-tool enable/disable, logs & monitoring, tool
  testing playground, user management

See **[ROADMAP.md](ROADMAP.md)** for the full architecture, data model, and phased
delivery plan.

## Documentation

- **[Docs/](Docs/README.md)** — the end-user & administrator manual: getting started,
  the admin guide (connections, tools, tokens, OAuth clients, users), the user guide,
  connecting an MCP client, the Geektastic Realms tools reference, and troubleshooting.
- **[Tech_Docs/](Tech_Docs/README.md)** — engineering reference: architecture, data
  model, API reference, the MCP protocol implementation, OAuth 2.1, security, the
  connector SDK, deployment, and local development.

## Status

Deployed and running (see [CHANGELOG.md](CHANGELOG.md) for the release history: the
initial scaffold, OAuth 2.1 support for Claude Desktop/Claude.ai, and a CSRF/session
fix). Two connectors are implemented:
- **Geektastic Realms**, against the real `/api/v1/*` API (see
  `geektastic-realms/Docs/API.md`) — 46 tools covering statblocks, campaigns
  (read + write), generic lore entries (any category, with custom fields),
  adventure modules (Acts/Chapters/Scenes/Appendices, Encounters, Handouts,
  Roll Tables), session logs, world history (eras/events, gated by a separate
  `history` token scope), and deletes for entries/sections/encounters/handouts.
  See [Docs/05-GR-Tools-Reference.md](Docs/05-GR-Tools-Reference.md).
- **Geektastic Family Tree**, against the real `/api/v1/*` API (see
  `geektastic-family-tree/docs/API.md`) — trees, people, families, events, places,
  sources/repositories, citations, notes, media metadata, research log, DNA matches,
  and the search/relationship/gap/duplicate research tools. Media upload/replace
  (multipart file upload) isn't exposed as a tool.

See **[ROADMAP.md](ROADMAP.md)** for the full architecture and tool lists.

## Repository layout

```
apps/server/       Node + Express backend: /api (management) and /mcp (Streamable HTTP)
apps/web/           React + Vite admin UI (built into apps/server/public)
packages/shared/    Types shared between server and web
packages/connectors/ AppConnector abstraction + the Geektastic Realms and Family Tree connectors
```

## Getting started

1. Copy the env template and fill in real values:
   ```
   cp .env.example .env
   ```
   Generate `APP_ENCRYPTION_KEY` with `openssl rand -hex 32`, and a long random
   `SESSION_SECRET`. Set a real `ADMIN_PASSWORD` — it's only used to seed the first
   admin account on first run. Set `PUBLIC_BASE_URL` to this server's own
   externally-reachable origin (e.g. `https://mcp.example.com`) — required for OAuth
   discovery metadata (see "Connecting an MCP client" below).

2. Install dependencies (requires Node 22+ and pnpm; `corepack enable` will provide pnpm):
   ```
   pnpm install
   ```

3. Generate the Prisma client and sync the schema to your Postgres instance:
   ```
   pnpm prisma:generate
   pnpm prisma:push
   ```
   > No Prisma migrations are checked in yet — see **Known gaps** below.

4. Run the server and web UI in dev mode (two terminals):
   ```
   pnpm dev:server
   pnpm dev:web
   ```
   The web dev server proxies `/api` and `/health` to `localhost:8080` (see
   `apps/web/vite.config.ts`).

5. Or build and run everything as it will run in Docker:
   ```
   pnpm build
   pnpm --filter @geektastic/server start
   ```

## Docker / Portainer deployment

```
docker compose up -d --build
```

This builds the multi-stage `Dockerfile` (`node:22-alpine`) and starts it alongside the
official `postgres:16-alpine` image, per `docker-compose.yml`. Import the same
`docker-compose.yml` into Portainer as a Stack, and set the env vars from `.env.example`
in the stack's environment section. `pgdata` is a named volume, so config/secrets/users
persist across redeploys.

## Connecting an MCP client

First, log in to the Web UI with the bootstrap admin and add a Geektastic Realms
connection under **Connections**.

**Claude Code CLI** — uses a static Bearer token. Create one under **Tokens** (shown
once, copy it), then:
```
claude mcp add --transport http geektastic https://<host>/mcp \
  --header "Authorization: Bearer <token>"
```

**Claude Desktop / Claude.ai (Custom Connector)** — these only support OAuth 2.1, not a
raw header. Add a Custom Connector pointed at `https://<host>/mcp`; the server supports
Dynamic Client Registration, so Claude should register itself automatically and prompt
you to log in and approve access — no manual "OAuth Client ID" needed in the common
case. If a connector's setup screen doesn't attempt DCR and asks you to fill in a Client
ID manually, create one under **OAuth Clients** (name + Claude's redirect URI,
`https://claude.ai/api/mcp/auth_callback`) and paste the generated Client ID in.

`scripts/verify-oauth.sh <host> <admin-username> <admin-password>` simulates the full
OAuth flow via curl if you want to sanity-check the server side without a Claude.ai
account.

## Known gaps / next steps

- **No Prisma migration history yet.** The container currently runs `prisma db push` on
  startup instead of `prisma migrate deploy` (see the note in `Dockerfile`). Once the
  schema is validated against a real database, run `prisma migrate dev --name init`
  locally and commit the generated `apps/server/prisma/migrations/` folder, then switch
  the Dockerfile back to `migrate deploy` for safer, trackable schema changes.
- **No automated tests yet.** Planned alongside the migration work — see Phase 9 in
  [ROADMAP.md](ROADMAP.md).

Forward plans (new tools tracking the Geektastic Realms API, MCP prompts/resources,
hardening, per-token scoping) are in **[ROADMAP.md](ROADMAP.md)** under
"Delivery Phases — what's next".