Metadata-Version: 2.4
Name: cairn-mcp
Version: 0.1.0
Summary: MCP server that logs Claude Code work sessions, file edits, and tasks to your Cairn account.
Project-URL: Homepage, https://github.com/cybort360/cairn
Project-URL: Repository, https://github.com/cybort360/cairn
Author: Adedeji Olamide
License-Expression: MIT
License-File: LICENSE
Keywords: claude-code,mcp,model-context-protocol,productivity,work-tracking
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.0.0
Description-Content-Type: text/markdown

# The Cairn agent (MCP server + hooks)

This folder is the piece that runs on *your* machine, not on Vercel. It gives Claude Code a set of Cairn tools (log work, list tasks, weekly summaries, and so on) and, if you want, quietly records what you did after every session. Everything here is a thin HTTPS client over your Cairn cloud account — no local database, no second copy of your data.

What's in here:

- `cairn_mcp/` — the Python package, published to PyPI as [`cairn-mcp`](https://pypi.org/project/cairn-mcp/):
  - `server.py` — the MCP server. Eleven tools (`work_log_add`, `task_create`, `daily_summary`, …).
  - `client.py` — the tiny stdlib HTTP client the server and hooks share. Reads your token, talks to the API.
  - `session_logger.py` — a SessionEnd hook. Turns a finished Claude Code session into one work-log entry.
  - `file_logger.py` — a PostToolUse hook. Records a file-activity event whenever Claude writes or edits a file.
- `pyproject.toml` — packaging metadata. One dependency, `mcp[cli]`; one console script, `cairn-mcp`.
- `.mcp.json`, `hooks/hooks.json`, `.claude-plugin/` — the Claude Code plugin wiring.

## Easiest: install as a plugin

If you're on Claude Code, skip the manual steps below — this repo is also a plugin marketplace. Two commands from inside Claude Code:

```
/plugin marketplace add cybort360/cairn
/plugin install cairn@cairn
```

That registers the `cairn` MCP server and both auto-logging hooks for you; there's no clone, no venv, and no `claude mcp add`. One prerequisite: the plugin runs the server through [`uv`](https://docs.astral.sh/uv/), so you need `uv` on your PATH (`curl -LsSf https://astral.sh/uv/install.sh | sh`). `uv` pulls `mcp[cli]` on its own, so you never manage a Python env.

You still need to drop your token in once — see step 2 of the manual install for where to get it:

```bash
printf '%s' 'PASTE_YOUR_TOKEN' > ~/.cairn_token && chmod 600 ~/.cairn_token
```

## From PyPI (any MCP client)

Not on Claude Code, or want the server without the plugin? The package is on PyPI, so [`uv`](https://docs.astral.sh/uv/) can run it with nothing to clone or install:

```bash
claude mcp add cairn --scope user -- uvx cairn-mcp
```

`uvx cairn-mcp` is the command any MCP client can point at; `uvx` fetches the package and its deps on first run. Save your token first (see step 2 below). For a different client, use its own config — the command is the same.

## Manual, from source

For when you'd rather not use `uv` at all. You need Python 3.10+ and the Claude Code CLI.

**1. Clone and install the package into a venv.**

```bash
git clone https://github.com/cybort360/cairn.git
cd cairn/agent
python3 -m venv .venv
.venv/bin/pip install .
```

That puts a `cairn-mcp` console script in `.venv/bin/`.

**2. Get your API token.** Sign in at the Cairn web app, open the account menu, and copy your API token. Save it where the client looks for it:

```bash
printf '%s' 'PASTE_YOUR_TOKEN_HERE' > ~/.cairn_token
chmod 600 ~/.cairn_token
```

(You can set `CAIRN_TOKEN` in the environment instead if you'd rather not write a file. The client checks `CAIRN_TOKEN` first, then `~/.cairn_token`.)

**3. Register the server with Claude Code.** Point it at the console script. `--scope user` makes the `cairn` tools available in every project, not just this one:

```bash
claude mcp add cairn --scope user -- "$(pwd)/.venv/bin/cairn-mcp"
```

**4. Check it connected.**

```bash
claude mcp list
```

You want to see `cairn: … ✔ Connected`. Inside a session the tools show up as `mcp__cairn__work_log_add`, `mcp__cairn__task_list`, and the rest.

That's the whole install. The hooks below are optional.

## Optional: auto-logging hooks

The plugin install already wires these up. Set them by hand only if you went the manual route. The two hooks make Cairn fill itself in without you calling a tool: `session_logger` writes one entry summarizing each session when it ends; `file_logger` notes every file Claude touches. Both fail silently — a dropped network call or a missing token never interrupts your work. They use only the standard library, so plain `python3` runs them; no `mcp` needed.

Wire them into Claude Code's settings (`~/.claude/settings.json` for all projects). The commands run the package modules, so they need `cairn_mcp` on the path — `cd` into wherever you cloned (`$HOME/cairn/agent` assumes `~/cairn`; adjust it):

```json
{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$HOME/cairn/agent\" && python3 -m cairn_mcp.session_logger 2>/dev/null || true",
            "timeout": 15,
            "statusMessage": "Logging session to Cairn"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$HOME/cairn/agent\" && python3 -m cairn_mcp.file_logger 2>/dev/null || true",
            "timeout": 10
          }
        ]
      }
    ]
  }
}
```

A hard kill (crash, power loss, `kill -9`) skips the SessionEnd hook, so that one session won't be logged. Everything else — the normal exit, `/clear`, `/logout`, Ctrl-D — fires it.

## Pointing at a different backend

By default the client talks to production. Override it with `CAIRN_API_URL` if you're running the web app locally or against a staging deploy:

```bash
export CAIRN_API_URL="http://127.0.0.1:8765"
```

The MCP server reads it the same way, so set it in the `claude mcp add` environment (`-e CAIRN_API_URL=…`) if you want the tools pointed somewhere other than prod.
