cairn-mcp 0.1.0__tar.gz

cairn_mcp-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "cairn",
+  "displayName": "Cairn",
+  "version": "0.1.0",
+  "description": "Log Claude Code work sessions, file edits, and tasks to your Cairn account. Bundles the Cairn MCP server (11 tools) and the session + file-edit auto-logging hooks.",
+  "author": {
+    "name": "cybort360",
+    "url": "https://github.com/cybort360"
+  },
+  "homepage": "https://github.com/cybort360/cairn",
+  "repository": "https://github.com/cybort360/cairn",
+  "keywords": ["work-tracking", "productivity", "mcp", "logging", "tasks"]
+}

cairn_mcp-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+
+# Vercel
+.vercel
+.env*.local
+
+# Superseded legacy code — kept on disk, not part of the product repo.
+# webapp.py: pre-serverless SQLite monolith (replaced by lib/ + api/ + dev.py)
+# server.py: old local-SQLite MCP (replaced by the cloud client in agent/)
+/webapp.py
+/server.py
+
+# OS
+.DS_Store
+
+# Playwright test artifacts
+.playwright-mcp/
+*.png
+
+# Subagent-driven dev scratch (ledger, briefs, diffs)
+.superpowers/
+
+# Python build artifacts
+dist/
+*.egg-info/

cairn_mcp-0.1.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "cairn": {
+      "command": "uv",
+      "args": ["run", "--directory", "${CLAUDE_PLUGIN_ROOT}", "cairn-mcp"]
+    }
+  }
+}

cairn_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adedeji Olamide
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cairn_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+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.

cairn_mcp-0.1.0/README.md

@@ -0,0 +1,129 @@
+# 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.

cairn_mcp-0.1.0/cairn_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""Cairn MCP server and Claude Code hooks — a thin client over the Cairn cloud API.
+
+Kept import-light on purpose: the hooks (session_logger, file_logger) run under a
+bare ``python3`` with only the standard library, so importing this package must not
+pull in ``mcp`` or ``pydantic``. The server lives in :mod:`cairn_mcp.server`.
+"""
+
+__version__ = "0.1.0"

cairn_mcp-0.1.0/cairn_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Run the Cairn MCP server with ``python -m cairn_mcp``."""
+
+from .server import main
+
+main()

cairn_mcp-0.1.0/cairn_mcp/client.py

@@ -0,0 +1,88 @@
+"""Tiny stdlib HTTP client for the Cairn cloud API.
+
+The MCP server and the Claude Code hooks use this to talk to the user's Cairn
+account over HTTPS, authenticating with their API token. No third-party deps.
+
+Config:
+  CAIRN_API_URL   base URL (defaults to production)
+  CAIRN_TOKEN     API token, else read from ~/.cairn_token
+"""
+
+import json
+import os
+import urllib.error
+import urllib.request
+from urllib.parse import urlencode
+
+DEFAULT_BASE = "https://cairn-octanes-projects.vercel.app"
+TOKEN_PATH = os.path.expanduser("~/.cairn_token")
+# Older installs saved the token here; read it as a fallback during the rename.
+LEGACY_TOKEN_PATH = os.path.expanduser("~/.work_tracker_token")
+DEFAULT_TIMEOUT = 5.0
+
+
+class CairnError(Exception):
+    """Raised on missing config, network failure, or a non-2xx response."""
+
+
+def base_url() -> str:
+    return os.environ.get("CAIRN_API_URL", DEFAULT_BASE).rstrip("/")
+
+
+def token() -> str:
+    t = os.environ.get("CAIRN_TOKEN")
+    if t:
+        return t.strip()
+    for path in (TOKEN_PATH, LEGACY_TOKEN_PATH):
+        try:
+            with open(path) as f:
+                return f.read().strip()
+        except OSError:
+            continue
+    return ""
+
+
+def _request(method, path, params=None, payload=None, timeout=DEFAULT_TIMEOUT):
+    tok = token()
+    if not tok:
+        raise CairnError("not configured — save your token to ~/.cairn_token "
+                         "or set CAIRN_TOKEN")
+    url = base_url() + path
+    if params:
+        q = urlencode({k: v for k, v in params.items() if v is not None})
+        if q:
+            url += "?" + q
+    body = json.dumps(payload).encode() if payload is not None else None
+    req = urllib.request.Request(url, data=body, method=method)
+    req.add_header("Authorization", f"Bearer {tok}")
+    if body is not None:
+        req.add_header("Content-Type", "application/json")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            text = resp.read().decode()
+            return json.loads(text) if text else {}
+    except urllib.error.HTTPError as e:
+        detail = ""
+        try:
+            detail = json.loads(e.read().decode()).get("error", "")
+        except Exception:
+            pass
+        raise CairnError(f"HTTP {e.code}: {detail or e.reason}")
+    except urllib.error.URLError as e:
+        raise CairnError(f"network error: {e.reason}")
+
+
+def get(path, params=None, timeout=DEFAULT_TIMEOUT):
+    return _request("GET", path, params=params, timeout=timeout)
+
+
+def post(path, payload, timeout=DEFAULT_TIMEOUT):
+    return _request("POST", path, payload=payload, timeout=timeout)
+
+
+def patch(path, payload, timeout=DEFAULT_TIMEOUT):
+    return _request("PATCH", path, payload=payload, timeout=timeout)
+
+
+def delete(path, timeout=DEFAULT_TIMEOUT):
+    return _request("DELETE", path, timeout=timeout)

cairn_mcp-0.1.0/cairn_mcp/file_logger.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""
+PostToolUse(Edit|Write|MultiEdit) hook for Cairn.
+
+After Claude Code writes or edits a file, this records one file-activity event
+in the user's Cairn account over HTTPS. Dedup (collapsing rapid repeats of the
+same file+action) and language detection now happen server-side.
+
+Fail-soft: any network/config error is swallowed so editing never breaks.
+"""
+
+import json
+import os
+import sys
+
+from . import client as cairn_client
+
+POST_TIMEOUT = 3.0
+
+# Paths we never want cluttering the activity log.
+IGNORE_SUBSTRINGS = ("/.git/", "/node_modules/", "/.venv/", "/__pycache__/",
+                     "/dist/", "/build/", "/.next/", ".work_tracker.db")
+
+
+def main() -> None:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return
+
+    tool = payload.get("tool_name", "")
+    fp = (payload.get("tool_input") or {}).get("file_path", "")
+    if not fp or any(s in fp for s in IGNORE_SUBSTRINGS):
+        return
+
+    action = "created" if tool == "Write" else "edited"
+    cwd = payload.get("cwd") or os.getcwd()
+    project = os.path.basename(cwd.rstrip("/")) or None
+    display = os.path.relpath(fp, cwd) if fp.startswith(cwd) else fp
+
+    try:
+        cairn_client.post("/api/files", {
+            "file_path": display, "action": action, "project": project,
+        }, timeout=POST_TIMEOUT)
+    except cairn_client.CairnError:
+        pass  # fail-soft
+
+
+if __name__ == "__main__":
+    main()