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.

Related MCP server: Spotify MCP

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