{
  "markdown": "# Cairn\n\n[![PyPI](https://img.shields.io/pypi/v/cairn-mcp?label=cairn-mcp)](https://pypi.org/project/cairn-mcp/)\n[![MCP Registry](https://img.shields.io/badge/MCP%20registry-cairn--mcp-2a55d8)](https://registry.modelcontextprotocol.io/?search=cairn-mcp)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n\nA work tracker that remembers what you did. It captures your coding sessions, the files you touch, tasks moving from pending to done, and project notes, then keeps them in one place with daily and weekly rollups. The name is the pile of stones that marks a trail.\n\nCairn runs as a multi-tenant web app on Vercel with a Neon Postgres database. Each account signs up, logs in, and only ever sees its own data.\n\n## How it's built\n\nThe whole server is the Python standard library plus one dependency (`psycopg`). No framework.\n\n- `api/index.py` — the Vercel serverless entrypoint. Vercel's Python runtime treats it as a catch-all, so every request lands here.\n- `lib/handler.py` — routing. The same `BaseHTTPRequestHandler` runs three ways: the Vercel function, the local dev server, and the tests.\n- `lib/data.py` — every SQL statement, each one scoped by `user_id`.\n- `lib/db.py` — Neon connection (pooled endpoint) plus small query helpers.\n- `lib/auth.py` — PBKDF2 password hashing, sessions, and token resolution.\n- `lib/limits.py` — signup/login rate limiting and per-account quota caps, both backed by Postgres.\n- `lib/assets.py` — the single-page app and favicon, embedded as base64 so they ship inside the function bundle. Generated by `build_assets.py`; re-run it after editing `static/`.\n\n## Local development\n\nYou need a Postgres to point at. A throwaway one in Docker works:\n\n```bash\ndocker run -d --name cairn_pg -e POSTGRES_PASSWORD=pw -e POSTGRES_DB=cairn -p 5432:5432 postgres:16-alpine\npython3 -m venv .venv && .venv/bin/pip install 'psycopg[binary]'\nexport DATABASE_URL=\"postgres://postgres:pw@127.0.0.1:5432/cairn\"\n.venv/bin/python dev.py --init    # create the schema, then serve on :8765\n```\n\nTests run against that same database:\n\n```bash\n.venv/bin/python tests/smoke.py        # core CRUD + isolation\n.venv/bin/python tests/test_limits.py  # rate limiting + quotas\n.venv/bin/python tests/test_sp3.py     # file activity + filtered lists\n```\n\n## Deployment\n\nPushing to `main` deploys to production through the Vercel GitHub integration. `DATABASE_URL` and the other Neon variables come from the Vercel ↔ Neon integration; the app reads the pooled connection string. Schema changes go on with `initdb.py` against the direct (unpooled) URL.\n\n## The agent side\n\nThe `agent/` folder is the MCP server and two Claude Code hooks that run on your machine. They talk to this API over HTTPS using your account's token, so anything Claude Code does flows into your Cairn account. The server gives Claude a set of `cairn` tools; the hooks log sessions and file edits on their own.\n\nOn Claude Code the quickest install is the plugin — this repo doubles as a plugin marketplace (`.claude-plugin/marketplace.json`):\n\n```\n/plugin marketplace add https://github.com/cybort360/cairn\n/plugin install cairn@cairn\n```\n\nThat wires up the MCP server and both hooks; you just save your token to `~/.cairn_token` (it needs [`uv`](https://docs.astral.sh/uv/) on your PATH). The manual route — clone, venv, `claude mcp add` — is in `agent/README.md`. The web app deploy ignores `agent/`; it's client-side only.\n\n## Design notes\n\nEach sub-project that built Cairn has a spec under `docs/superpowers/specs/`: the cloud core, the auth hardening, and the local agent cutover. Read those if you want the reasoning behind a decision rather than just the code.\n",
  "bytes": 3676,
  "sha": "6a57b1a3a48465aba7da0bed2d048710e1da9a3c2330d2b0d4f73a241d82f8da",
  "repo_slug": "cybort360/cairn",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cybort360_cairn_mcp_3f345867/readme"
}