kje-mcp

Ein mit Claude.ai kompatibler MCP-Server, der Jim Brain (persistenter Speicher + Empire State + Vault) und einen Headless-Claude-Code-Dispatcher auf dem RackNerd-VPS kapselt, sodass jede Claude.ai-Websitzung:

• den aktuellen Status des Imperiums, Projekte und kürzliche Erinnerungen lesen,

• den semantischen Speicher und den Anmeldedaten-Vault durchsuchen,

• schnelle Protokolle und semantische Erinnerungen an Brain zurückschreiben,

• claude -p Build-Sitzungen auf dem VPS starten kann.

Der Server spricht MCP Streamable HTTP (das Transportprotokoll, das die „Custom Connector“-UI von Claude.ai erwartet). Er verwendet den stateless / JSON-Response-Modus, sodass er überall dort laufen kann, wo eine normale HTTP-API funktioniert – in diesem Fall auf Railway.

Verfügbare Tools

Alle Tools authentifizieren sich gegenüber Brain mit dem kleingeschriebenen x-brain-key-Header (der einzige Header, den Brain akzeptiert – fest codiert beim BridgeDeck-Debugging am 27.04.2026). Die MCP-Schicht selbst akzeptiert ein Bearer-Token im Authorization-Header – das ist es, was die Connector-UI von Claude.ai sendet.

Dateistruktur

kje-mcp/
├── main.py                       # FastAPI + FastMCP server (deployed to Railway)
├── requirements.txt
├── railway.toml
├── .env.example
├── README.md
└── vps/
    ├── cc_dispatch_server.py     # Companion dispatcher — runs on the RackNerd VPS
    ├── requirements.txt
    └── kje-cc-dispatch.service   # systemd unit

1. kje-mcp auf Railway bereitstellen

1a. Das Repository auf GitHub pushen

cd C:\Users\Jim\Documents\GitHub\kje-mcp
git add .
git commit -m "feat: kje-mcp v1.0.0 — Claude.ai MCP wrapper for Jim Brain + CC dispatch"
gh repo create jharriGH/kje-mcp --public --source=. --remote=origin --push

1b. Den Railway-Service erstellen

# from inside the kje-mcp dir
railway init                         # name it: kje-mcp
railway link                         # link to the new project
railway up                           # builds + deploys

Oder über das Dashboard: New Project → Deploy from GitHub Repo → jharri → jharriGH/kje-mcp. Railway erkennt automatisch Nixpacks Python und verwendet den startCommand aus der railway.toml.

1c. Umgebungsvariablen festlegen

railway variables --set BRAIN_KEY=jim-brain-kje-2026-kingjames
railway variables --set BRAIN_URL=https://jim-brain-production.up.railway.app
railway variables --set MCP_AUTH_KEY=jim-brain-kje-2026-kingjames

# OPTIONAL — only set these once the VPS dispatcher is up (step 2):
# railway variables --set VPS_DISPATCH_URL=https://cc.kj.empire/dispatch
# railway variables --set VPS_DISPATCH_KEY=<long-random-string>

Gemäß der ENV VAR AUTOMATION RULE steuert Claude Code dies – Jim klickt niemals durch Railway-Dashboards.

1d. Die Bereitstellung überprüfen

# replace <host> with the Railway-assigned URL (railway domain or your custom one)
curl -s https://<host>/health | jq
# expect: {"status":"ok","service":"kje-mcp",...,"vps_dispatch_configured":false,...}

# initialize handshake (Claude.ai will send the same)
curl -s -X POST https://<host>/mcp/ \
  -H "Authorization: Bearer jim-brain-kje-2026-kingjames" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' | jq

# list tools
curl -s -X POST https://<host>/mcp/ \
  -H "Authorization: Bearer jim-brain-kje-2026-kingjames" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | jq '.result.tools[].name'
# expect 7 names: brain_status, brain_search, brain_get_project, brain_vault_search,
#                 brain_log, brain_memory, cc_dispatch

2. Verbindung von Claude.ai Web herstellen

1. Öffnen Sie claude.ai → Settings → Connectors → Add custom connector.

2. Name: KJE MCP.

3. URL: https://<your-railway-host>/mcp/ (beachten Sie den abschließenden Schrägstrich und den Pfad /mcp/).

4. Auth: API key / Bearer token → fügen Sie jim-brain-kje-2026-kingjames ein (oder was auch immer Sie für MCP_AUTH_KEY festgelegt haben).

5. Save. Claude.ai führt den MCP initialize + tools/list Handshake durch; wenn das grüne Häkchen neben „KJE MCP“ erscheint, sind die 7 Tools im Chat verfügbar.

In jeder neuen Claude.ai-Konversation:

• Öffnen Sie das Tool-/Connector-Menü der Konversation und aktivieren Sie KJE MCP.

• Beginnen Sie Ihren Prompt mit dem Äquivalent von brain_session_start:

  "Use KJE MCP. Call brain_status and brain_get_project for kj_codedeck (depth=standard) before answering. Then [task]."

Wenn Sie fertig sind, führt Claude.ai das Abschlussritual über denselben Connector aus – brain_memory für die Zusammenfassung, brain_log für den Fortschritt und cc_dispatch, falls weiterhin auf dem VPS gearbeitet werden muss.

3. (Optional) Den VPS-Dispatcher für cc_dispatch einrichten

Ohne dies gibt cc_dispatch einen sauberen cc_dispatch_not_configured-Fehler zurück und die anderen sechs Tools funktionieren einwandfrei. Richten Sie dies ein, wenn Sie möchten, dass Claude.ai tatsächlich CC-Sitzungen auf dem VPS startet.

3a. Den vps/-Ordner auf 104.223.120.21 synchronisieren

# from your laptop, in the kje-mcp repo
scp -r vps/ jim@104.223.120.21:/home/jim/kje-mcp/

3b. Ein venv erstellen und Abhängigkeiten auf dem VPS installieren

ssh jim@104.223.120.21
cd /home/jim/kje-mcp
python3 -m venv .venv
.venv/bin/pip install -r vps/requirements.txt

3c. .env konfigurieren

cat > /home/jim/kje-mcp/vps/.env <<'EOF'
VPS_DISPATCH_KEY=<long-random-string-paste-same-on-railway>
BRAIN_URL=https://jim-brain-production.up.railway.app
BRAIN_KEY=jim-brain-kje-2026-kingjames
PROJECT_REPOS_BASE=/home/jim/repos
# Optional overrides for slugs whose repo dir name differs from the slug:
# PROJECT_REPOS_OVERRIDES={"kj_autonomous":"/home/jim/n8n-canvas/kj-autonomous"}
CLAUDE_BIN=/usr/local/bin/claude
DISPATCH_LOG_DIR=/var/log/kje-cc-sessions
EOF

sudo mkdir -p /var/log/kje-cc-sessions
sudo chown jim:jim /var/log/kje-cc-sessions

3d. Die systemd-Unit installieren + starten

sudo cp /home/jim/kje-mcp/vps/kje-cc-dispatch.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now kje-cc-dispatch
sudo systemctl status kje-cc-dispatch
curl -s http://127.0.0.1:8088/health

3e. Mit TLS freigeben (nginx + Let's Encrypt)

# /etc/nginx/sites-available/cc.kj.empire
server {
    listen 443 ssl http2;
    server_name cc.kj.empire;

    ssl_certificate     /etc/letsencrypt/live/cc.kj.empire/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/cc.kj.empire/privkey.pem;

    client_max_body_size 4m;
    proxy_read_timeout   65s;

    location /dispatch {
        proxy_pass         http://127.0.0.1:8088/dispatch;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Dispatch-Key $http_x_dispatch_key;
    }

    location /health {
        proxy_pass http://127.0.0.1:8088/health;
    }
}

sudo ln -s /etc/nginx/sites-available/cc.kj.empire /etc/nginx/sites-enabled/
sudo certbot --nginx -d cc.kj.empire
sudo nginx -t && sudo systemctl reload nginx

3f. Den kje-mcp-Service damit verbinden

# from the kje-mcp repo on your laptop
railway variables --set VPS_DISPATCH_URL=https://cc.kj.empire/dispatch
railway variables --set VPS_DISPATCH_KEY=<same-random-string>
railway redeploy

/health auf dem kje-mcp-Service sollte nun "vps_dispatch_configured": true anzeigen.

Wie eine Claude.ai-Sitzung dies durchgängig nutzt

1. Sitzungsstart. Connector aktiviert. Claude.ai ruft brain_status → Empire-Kontext auf, dann brain_get_project("kj_codedeck", "standard") → Injection-Prompt.

2. Arbeiten. Claude.ai antwortet basierend auf dem Reasoning im Chat. Währenddessen ruft es brain_search für frühere Entscheidungen oder brain_vault_search für Anmeldedaten auf, die es besprechen muss.

3. Schwere Arbeit. Wenn die Arbeit eine echte CC-Build-Sitzung erfordert, ruft Claude.ai cc_dispatch(project="kj_codedeck", prompt="<full build prompt>") auf. Der VPS-Dispatcher bestätigt dies sofort mit einer session_id. Die CC-Sitzung läuft im Hintergrund.

4. Übergabe. Wenn die CC-Sitzung endet, postet der VPS-Dispatcher eine Übergabe an Brain /codedeck/handoff (schnelles Protokoll + Update der next_action des Projekts + Build-Karte, falls 3+ Dateien geändert wurden + semantische Erinnerung in der Warteschlange). Die nächste Claude.ai-Sitzung sieht dies über brain_search.

5. Abschlussritual. Claude.ai ruft brain_memory (vollständige Zusammenfassung), brain_log (Fortschrittsereignis) auf, und das Speichern der Build-Karte erfolgt automatisch serverseitig über die Übergabe. Kein Fragen an Jim „welche Option?“ – das ist die Regel.