# susMCP

Suspicious Antwerp's company-wide conversational data layer: a standalone MCP
server that wraps existing systems (adsAgent, suspiciousAI, Shopify MCP) behind
one OAuth-authenticated connector, so the CEO + ops manager can ask Claude
(web / Desktop / Slack) about company data.

Full design, decisions, and the 11 implementation slices live in the plan:
`~/.claude/plans/twinkling-mapping-coral.md`.

## Status

**Slice 1 (walking skeleton) — in progress.** OAuth resource server (WorkOS
AuthKit) + one CS tool (`cs_get_ticket_messages`, proxying suspiciousAI's already
-exposed endpoint) + central `tool_invocations` tracing, brought up by one
compose command.

## Architecture (v1)

```
Claude (web/Desktop/Slack)  --OAuth 2.1/PKCE (WorkOS)-->  susMCP (this server)
                                                            |  own Postgres:
                                                            |   - tool_invocations
                                                            |   - synced query data (later)
      curated tools (live, HTTPS + per-domain service cred) |
        +--> suspiciousAI  (/api/tickets, /api/lookup*, /api/analytics)
        +--> adsAgent      (/api/metrics, /api/ads, ...)          [slice 5+]
        +--> Shopify MCP   (read-only, mutations gated)           [slice 6]
      escape hatch: susmcp_query = read-only SQL over the synced DB  [slice 8]
```

Curated tools proxy live for freshness; the escape hatch queries susMCP's own
synced copy. All mechanics (httpx call, error taxonomy, tracing) live in ONE
proxy factory (`proxy.py`); tool bodies are one line each.

## Local dev

```bash
cp .env.example .env          # dev defaults work; leave WORKOS_AUTHKIT_DOMAIN empty
docker compose up --build     # brings up susmcp + Postgres (HTTP, no TLS, no auth)
```

Auth is DISABLED when `WORKOS_AUTHKIT_DOMAIN` is empty — dev only, never ship it.

### Tests

```bash
pip install -e ".[dev]"
pytest
```

Tests run without a database (tracing writes are best-effort and patched in tests).

## Production / connecting to Claude — HITL setup

These steps need real accounts/infra and are done by a human (see the plan's
Phase 0 + Issue 1):

1. **WorkOS AuthKit**: create the project, add the exec accounts, enable Google
   sign-in, set `WORKOS_AUTHKIT_DOMAIN` and `BASE_URL` (the server's public https URL).
2. **Host + TLS**: deploy on susMCP's own host; the prod compose overlay
   (`docker-compose.prod.yml`, added with the deploy slice) runs nginx + certbot
   for Let's Encrypt. `docker compose -f docker-compose.yml -f docker-compose.prod.yml up --build`.
3. **suspiciousAI service credential**: set `CS_BASE_URL` +
   `CS_API_KEY` (its `INTERNAL_API_KEY`).
4. **Register the connector** in claude.ai (Enterprise admin) pointing at the
   server's `/mcp` URL; approve the OAuth flow.
5. **Verify**: ask about a ticket → `cs_get_ticket_messages` fires (visible in the
   transcript) → a `tool_invocations` row is written with the exec's identity.

## Accepted risks (v1, deliberate — see plan)

- `tool_invocations` captures full args (incl. customer PII) unbounded/plaintext,
  no retention/redaction. GDPR-relevant; revisit before wider rollout.
- susMCP is a single point of failure; restart+healthcheck only, no external
  uptime monitor yet.