diffcontext-service/README.md

DiffContext Web Service — Complete Setup Guide

What you just built

diffcontext-service/
├── backend/
│   └── main.py          ← FastAPI REST API server
├── frontend/
│   └── index.html       ← Web UI (open in browser, no server needed)
├── mcp/
│   └── mcp_server.py    ← MCP server for Claude Desktop / Cursor
└── README.md            ← This file

---

Option A — Web UI (easiest, for beginners)

Step 1: Install dependencies

pip install fastapi uvicorn python-multipart aiofiles

Step 2: Start the API server

cd /path/to/Diffcontext
uvicorn diffcontext-service.backend.main:app --reload --port 8000

Step 3: Open the web UI

Just open diffcontext-service/frontend/index.html in your browser. (Double-click it, or drag it into Chrome/Firefox.)

Step 4: Use it

1. Zip your Python project folder
2. Upload the zip on the "Upload Project" tab
3. Pick a function from the list
4. Click "Analyse Blast Radius"
5. See what breaks!

---

Option B — REST API (for developers)

Once the server is running at http://localhost:8000:

import requests

# 1. Upload your project
with open("myproject.zip", "rb") as f:
    r = requests.post("http://localhost:8000/upload", files={"file": f})
repo_id = r.json()["repo_id"]

# 2. List all functions
r = requests.get(f"http://localhost:8000/symbols?repo_id={repo_id}")
print(r.json()["symbols"][:5])

# 3. Get blast radius
r = requests.post("http://localhost:8000/blast", json={
    "repo_id": repo_id,
    "symbol": "./src/auth.py:validate_jwt"
})
print(r.json())

# 4. Get LLM context to paste into Claude
r = requests.post("http://localhost:8000/compile", json={
    "repo_id": repo_id,
    "symbol": "./src/auth.py:validate_jwt",
    "max_tokens": 8000
})
print(r.json()["context_text"])

Or use curl:

# Upload
curl -X POST http://localhost:8000/upload -F "file=@myproject.zip"

# Blast radius
curl -X POST http://localhost:8000/blast \
  -H "Content-Type: application/json" \
  -d '{"repo_id": "abc123", "symbol": "./main.py:my_function"}'

# Paste code directly (no upload)
curl -X POST http://localhost:8000/inline \
  -H "Content-Type: application/json" \
  -d '{
    "files": {"main.py": "def greet(name):\n  msg = build_message(name)\n  print(msg)\n\ndef build_message(name):\n  return f\"Hello {name}\""},
    "symbol": "./main.py:greet"
  }'

Interactive docs: http://localhost:8000/docs

---

Option C — MCP Server (Claude Desktop / Cursor)

This lets Claude Desktop call DiffContext automatically — no copy-paste needed.

Step 1: Install MCP

pip install mcp

Step 2: Find the full path to mcp_server.py

# Mac/Linux
realpath diffcontext-service/mcp/mcp_server.py

# Windows
cd diffcontext-service\mcp && echo %CD%\mcp_server.py

Step 3: Add to Claude Desktop config

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "diffcontext": {
      "command": "python",
      "args": ["/FULL/PATH/TO/diffcontext-service/mcp/mcp_server.py"]
    }
  }
}

Step 4: Restart Claude Desktop

Step 5: Use it in Claude Desktop

"List all functions in /Users/me/myproject"

"What is the blast radius of ./src/auth.py:validate_jwt 
 in /Users/me/myproject?"

"I'm about to change create_user in /Users/me/myproject.
 Compile context so I can understand the impact."

Claude will call DiffContext automatically and show you the results.

---

Troubleshooting

Problem	Fix
Connection refused on localhost:8000	Run the uvicorn command first
No Python files found	Make sure your zip contains .py files
Symbol not found	Use format ./filename.py:function_name (no parentheses)
MCP not working	Check the full path in claude_desktop_config.json
ModuleNotFoundError: mcp	Run pip install mcp

---

API response format

{
  "symbol": "./service.py:onboard_user",
  "direct_callers": ["./api.py:handle_signup"],
  "direct_callees": ["./service.py:create_user", "./service.py:create_order"],
  "blast_radius_count": 5,
  "blast_radius_by_file": {
    "./api.py": ["handle_signup", "process_request"],
    "./tests/test_service.py": ["test_onboard"]
  },
  "all_affected": ["./api.py:handle_signup", ...],
  "total_symbols_in_repo": 47
}