# 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

```bash
# 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:

```yaml
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

```yaml
# 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

```yaml
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`:

```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:
```env
# 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