Studio Catharsis Universal Project Coordinator MCP

A cross-platform coordination layer for all Studio Catharsis tools and agents. Connects Claude Chat, Claude Code, Cursor, Codex, Grok, Antigravity, Hermes, Telegram, Discord — any MCP-compatible tool — to a shared project state.

Architecture

┌─────────────┐     ┌────────────────────┐     ┌──────────────┐
│  Any MCP    │ ←→  │  studiocatharsis   │ ←→  │  SQLite DB   │
│  Client     │     │  MCP Server (:8002)│     │  (all detail)│
│  (Hermes,   │     │  FastMCP + Python  │ ──  │              │
│   Claude,   │     │                    │ ──→ │  Obsidian    │
│   Codex,    │     │                    │     │  (seeds)     │
│   Cursor…)  │     └────────────────────┘     └──────────────┘
└─────────────┘
           │
           └──→ Hermes Gateway (Telegram, Discord, Slack, etc.)

Data hierarchy:

• Obsidian — seeds. Small markdown notes saying something happened.

• Honcho — trunk & roots. Long-term connective memory between conversations.

• MCP DB — whole plant. Every detail. Tasks, blockers, decisions, SOPs.

Quick Start

# Install dependencies
pip install "mcp>=1.0.0" pyyaml pydantic uvicorn

# Clone
git clone https://github.com/Studio-Catharsis-Creative-Lab/project_com_mcp.git
cd project_com_mcp

# Run
python3 server.py

Server starts on http://0.0.0.0:8002, streamable-http transport. MCP endpoint: http://127.0.0.1:8002/mcp

Configuration

All config lives in projects.yaml. Overridable via SCMCP_* env vars.

Projects

Edit projects.yaml to add/remove projects. Each entry:

projects:
  - id: my-project
    name: My Project
    description: "What it does"
    repo_path: ~/GitHub-Sync/my-project   # optional
    default_phase: build                   # ideation | build | production | maintenance

Run auto_discover to scan a directory for git repos as suggestions.

Auth

# Option 1: Open access (default, good for LAN/Tailscale)
auth: none

# Option 2: Bearer token
auth: header
api_key: "<your-key>"

Env vars: SCMCP_AUTH, SCMCP_API_KEY. Generate a key with openssl rand -hex 32

Obsidian Seeds

obsidian_vault: ~/Documents/SCCL-Obsidian   # path to vault
# or via env: SCMCP_OBSIDIAN_VAULT

Every MCP write (task created, decision logged, blocker logged, etc.) drops a small markdown seed into the vault.

Hermes Gateway Integration

Register in ~/.hermes/config.yaml:

mcp_servers:
  studiocatharsis:
    url: "http://127.0.0.1:8002/mcp"
    headers:
      Authorization: "Bearer <your-api-key>"
    timeout: 30
    connect_timeout: 10

Tools appear as mcp_studiocatharsis_* in every Hermes conversation.

Tools (25 total)

SOP Phase Reminders

Every get_project or update_project_status call checks if any SOPs are triggered by the project's current phase. If so, it returns _sop_reminder in the response — a list of SOP titles with a message to "refresh SOP context if not loaded." This makes SOPs self-activating rather than dead documents.

Known Config Gotchas

Discord: DISCORD_ALLOWED_USERS vs DISCORD_ALLOW_ALL_USERS

Setting DISCORD_ALLOWED_USERS=user1,user2 overrides DISCORD_ALLOW_ALL_USERS=true. If a specific user list is set, the allow-all flag is ignored — only those users are authorized.

Fix: Use one or the other, not both. Remove the DISCORD_ALLOWED_USERS line if you want to allow everyone in the server.

Discord: Message Content Intent

The bot must have Message Content Intent enabled in Discord Developer Portal → Bot → Privileged Gateway Intents. Without it, the bot connects but cannot read any messages.

MCP Server Port Conflict

Default FastMCP port is 8000, which conflicts with Honcho. The server defaults to 8002 to avoid this. Set via SCMCP_PORT or port in projects.yaml.

Gateway and MCP Server Startup Order

If the Hermes gateway starts before the MCP server, it logs connection failures. The MCP retry logic handles this — the gateway will reconnect after about 10 seconds once the MCP server is up. Or just restart the gateway.

Token Format in .env

Do not quote the token value in .env files:

# CORRECT
DISCORD_BOT_TOKEN=MTUxMTc5NTcz...NREemnzd1c

# WRONG — quotes are included in the value
DISCORD_BOT_TOKEN="MTUxMTc5NTcz...NREemnzd1c"

Discord Slash Commands Take Time

After restart, Discord slash commands are reconciled asynchronously. The bot works for @mentions immediately, but /slash commands may take 30-60 seconds to appear in Discord's UI.

API Reference

MCP Session Handshake (for custom clients)

1. GET  /mcp  →  mcp-session-id header returned
2. POST /mcp  →  initialize (protocolVersion, capabilities)
3. POST /mcp  →  tools/list, tools/call, etc.

All POST requests require headers:

• Content-Type: application/json

• Accept: application/json, text/event-stream

• mcp-session-id: <from step 1>

• Authorization: Bearer <api-key> (if auth enabled)

License

MIT