MCP server for tangled
zzstoatzz.io
1# tangled-mcp notes
2
3## dependencies
4- `uv add` only (NEVER `uv pip`)
5- atproto from PR #605 (service auth)
6- pydantic warning filtered (upstream atproto issue #625)
7
8## deployment
9- **primary**: https://github.com/zzstoatzz/tangled-mcp (FastMCP Cloud)
10- **mirror**: tangled.sh:zzstoatzz.io/tangled-mcp (dogfooding)
11- `git push origin main` → both remotes
12
13## tools
14- all accept `owner/repo` or `@owner/repo` format (e.g., `zzstoatzz/tangled-mcp`)
15- server-side resolution:
16 1. handle → DID (via atproto identity resolution)
17 2. query `sh.tangled.repo` collection on owner's PDS
18 3. extract knot hostname and repo name from record
19 4. call knot's XRPC endpoint (e.g., `https://knot1.tangled.sh/xrpc/...`)
20
21## dev
22- justfile: `setup`, `test`, `check`, `push`
23- versioning: uv-dynamic-versioning (git tags)
24- type checking: ty + ruff (I, UP)
25- remember that `tree` is your friend, better than `ls` and a dream
26- **use `jq` for JSON parsing** (not python pipes)
27 - example: `curl -s https://pypi.org/pypi/tangled-mcp/json | jq -r '.info.version'`
28- **never use `sleep`** - poll/check with actual tools instead
29
30## architecture notes
31- repos stored as atproto records in collection `sh.tangled.repo` (NOT `sh.tangled.repo.repo`)
32- each repo record contains `knot` field indicating hosting server
33- appview (tangled.org) uses web routes, NOT XRPC
34- knots (e.g., knot1.tangled.sh) expose XRPC endpoints for git operations