# Personal Intelligence MCP

A multi-tenant Personal Context Platform. Phase 1: single connector (Spotify),
exposed to any MCP-compatible AI client, with per-user OAuth.

## Architecture

```
api/              FastAPI backend: user auth, Spotify OAuth flow, DB models
connectors/       One folder per data source. Phase 1 = spotify only.
mcp_server/       The MCP server that exposes tools to AI clients (Claude, etc.)
```

Each layer is independently swappable:
- `api` owns *who the user is* and *how their tokens get stored*.
- `connectors/<source>` owns *how to talk to that provider's API* and returns
  normalized data — it doesn't know about users or MCP.
- `mcp_server` owns *how an AI client asks for this user's context* — it
  resolves a user identity, calls into the connector layer, and returns
  MCP tool results.

## Setup

1. Copy `.env.example` to `.env` and fill in your Spotify Client ID/Secret
   (from https://developer.spotify.com/dashboard) and generate an
   `ENCRYPTION_KEY` (see comment in the file for how).
2. Create a virtualenv and install dependencies:
   ```
   python3 -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt
   ```
3. Initialize the database (SQLite file, local dev only):
   ```
   python -m api.db init
   ```
4. Run the API server (handles login + Spotify OAuth):
   ```
   uvicorn api.main:app --reload --port 8000
   ```
5. In a separate terminal, run the MCP server:
   ```
   python -m mcp_server.server
   ```
6. Visit `http://127.0.0.1:8000/auth/spotify/login?user_id=<your_user_id>`
   to walk through the OAuth grant. (Dev-mode auth stub — see
   `api/auth.py` — issues a user_id without a real login page yet.)
7. Point your MCP client (Claude Desktop / Claude Code config) at the MCP
   server and ask it something like "what have I been listening to lately."

## What's stubbed vs. real in this scaffold

- **Real**: DB schema, Spotify OAuth flow, token refresh, one working
  MCP tool (`get_recent_activity`) backed by real Spotify data.
- **Stubbed**: `api/auth.py` issues a fake user_id instead of integrating
  a real auth provider (Clerk/Auth0/Supabase Auth) — swap this in before
  you have real users. The MCP server's user-identity resolution
  (`mcp_server/identity.py`) currently trusts a passed-in API key looked
  up directly in the DB; harden this before exposing it publicly.

## Next steps (not in this scaffold)

- Real auth provider integration
- Token encryption using a KMS instead of a local Fernet key
- Second connector (Reddit) to prove the normalization layer generalizes
- Deploy to Fly.io / Railway