# Cairn [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/cybort360/cairn  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cairn-2

## Description
Log Claude Code work sessions, file edits, and tasks to your Cairn account.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "cairn": {
    "command": "npx",
    "args": ["-y","cairn-2"]
  }
}
```

## Documentation & README

# Cairn

[![PyPI](https://img.shields.io/pypi/v/cairn-mcp?label=cairn-mcp)](https://pypi.org/project/cairn-mcp/)
[![MCP Registry](https://img.shields.io/badge/MCP%20registry-cairn--mcp-2a55d8)](https://registry.modelcontextprotocol.io/?search=cairn-mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

A 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.

Cairn 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.

## How it's built

The whole server is the Python standard library plus one dependency (`psycopg`). No framework.

- `api/index.py` — the Vercel serverless entrypoint. Vercel's Python runtime treats it as a catch-all, so every request lands here.
- `lib/handler.py` — routing. The same `BaseHTTPRequestHandler` runs three ways: the Vercel function, the local dev server, and the tests.
- `lib/data.py` — every SQL statement, each one scoped by `user_id`.
- `lib/db.py` — Neon connection (pooled endpoint) plus small query helpers.
- `lib/auth.py` — PBKDF2 password hashing, sessions, and token resolution.
- `lib/limits.py` — signup/login rate limiting and per-account quota caps, both backed by Postgres.
- `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/`.

## Local development

You need a Postgres to point at. A throwaway one in Docker works:

```bash
docker run -d --name cairn_pg -e POSTGRES_PASSWORD=pw -e POSTGRES_DB=cairn -p 5432:5432 postgres:16-alpine
python3 -m venv .venv && .venv/bin/pip install 'psycopg[binary]'
export DATABASE_URL="postgres://postgres:pw@127.0.0.1:5432/cairn"
.venv/bin/python dev.py --init    # create the schema, then serve on :8765
```

Tests run against that same database:

```bash
.venv/bin/python tests/smoke.py        # core CRUD + isolation
.venv/bin/python tests/test_limits.py  # rate limiting + quotas
.venv/bin/python tests/test_sp3.py     # file activity + filtered lists
```

## Deployment

Pushing 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.

## The agent side

The `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.

On Claude Code the quickest install is the plugin — this repo doubles as a plugin marketplace (`.claude-plugin/marketplace.json`):

```
/plugin marketplace add https://github.com/cybort360/cairn
/plugin install cairn@cairn
```

That 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.

## Design notes

Each 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.