Studio Catharsis Universal Project Coordinator

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)

Category	Tools
Project State	get_project, list_projects, update_project_status
Tasks	create_task, update_task, get_tasks, mark_task_complete
Blockers	log_blocker, resolve_blocker, get_active_blockers
Decisions	log_decision, get_decision_log
Context	get_context (full project snapshot)
Environments	register_environment, audit_environments
Work Sessions	start_work_session, end_work_session
SOPs	create_org_sop, create_project_sop, get_sop, list_sops, update_sop, link_sop_to_project
Audit	run_morning_audit, auto_discover

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