portfolio-drift-mcp

MCP server that wraps portfolio-drift-agent — lets LLM clients (Claude Desktop, Claude Code, custom agents) audit a portfolio of projects against GitHub conversationally instead of round-tripping through a terminal.

Why this exists

If you maintain a portfolio of projects (a resume, a profile site, an internal project tracker) the source records drift the moment the underlying repos evolve. portfolio-drift-agent audits that drift via CLI. This server exposes the same audit as MCP tools so an LLM agent can call it mid-conversation:

"Before I push this PR, audit Beacon's own record on my portfolio. If the tech stack is missing anything that just shipped, propose patches and dry-run them."

The model can call audit_single_project, read the response, then call apply_drift_patches with dry_run=true — all without a human typing a command.

Related MCP server: GitHub MCP Agent Server

Tools

Every tool returns a structured envelope:

{ "ok": true, ...payload }
// or
{ "ok": false, "error_kind": "config|network|not_found|upstream", "error": "..." }

error_kind lets the calling LLM branch deterministically (re-prompt for missing config vs. retry on network vs. give up on not-found) without parsing tracebacks.

Install

pip install git+https://github.com/odanree/portfolio-drift-mcp

Then register in your MCP client (Claude Code example):

claude mcp add portfolio-drift python -m drift_mcp.server \
  --env ANTHROPIC_API_KEY=sk-ant-... \
  --env BEACON_JWT=... \
  --env BEACON_API_URL=https://beacon.danhle.net \
  --env GITHUB_TOKEN=ghp_...

Claude Desktop config (in ~/Library/Application Support/Claude/claude_desktop_config.json or the Windows equivalent):

{
  "mcpServers": {
    "portfolio-drift": {
      "command": "python",
      "args": ["-m", "drift_mcp.server"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "BEACON_JWT": "...",
        "BEACON_API_URL": "https://beacon.danhle.net",
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Environment

Env is read on tool invocation, not at server start — missing config returns a structured config error rather than crashing the server.

Tests

pip install -e .[dev]
pytest

13 tests cover: missing env → structured config error, unknown adapter rejection, full audit happy path with mocked Anthropic + Beacon + GitHub via respx, drift counting, single-project not_found path, dry-run vs apply branching, and patch validation. No network calls in CI.

License

MIT — see LICENSE.