# Cairn > A local-first, open-source harness for organizing your files with an AI agent, an MCP server for Claude Code, Codex, Cursor. BYO-key, no cloud. - **Type:** MCP server - **Install:** `agentstack add mcp-luckyjackluo-cairn` - **Verified:** Pending review - **Seller:** [luckyjackluo](https://agentstack.voostack.com/s/luckyjackluo) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [luckyjackluo](https://github.com/luckyjackluo) - **Source:** https://github.com/luckyjackluo/cairn ## Install ```sh agentstack add mcp-luckyjackluo-cairn ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Cairn **A local-first, open-source harness for organizing your files with an AI agent.** Point Claude Code, Codex, Cursor — any MCP client — at a folder, and your agent gains a full file-organization toolset: list, read, search, grep, edit, move, tag, import documents, and semantically retrieve. No account, no cloud, no UI required. Your files never leave your machine. ```bash claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes ``` Then ask your agent to *"organize this folder and tag everything"* — it will, using tools that run locally over your own files. > A cairn is a stack of stones that marks a trail. This one keeps your files in > order and shows the way through them. --- ## Quickstart (2 minutes) If you use **Claude Code**, setup is one command — the only prerequisite is [`uv`](https://docs.astral.sh/uv/), which provides `uvx`: ```bash # 1. Install uv if you don't have it (provides uvx) curl -LsSf https://astral.sh/uv/install.sh | sh # 2. Add Cairn to Claude Code, pointed at a folder you want organized claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes ``` Reopen Claude Code and ask: > *"Organize this folder and tag everything."* Cairn's tools run locally over your files — reads happen freely, and any move/rename/edit asks for confirmation first. The first run auto-downloads the package (~5s); no clone, no build, no account. > [!TIP] > Point `--workspace` at a **copy** of some notes for your first run — Cairn can > move, rename, and edit files. **Using Codex?** Same one-command flow (then run `/mcp` in a session to confirm): ```bash codex mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes ``` **Using Cursor or another MCP client?** Same package, JSON config: ```json { "mcpServers": { "cairn": { "command": "uvx", "args": ["cairn-mcp-server", "--workspace", "~/Documents/notes"] } } } ``` `~` is expanded by Cairn, so `~/Documents/notes` works in the CLI and in config files alike. **Just want to poke at it, no agent?** ```bash uvx cairn-cli --workspace ~/Documents/notes tree ``` ## Why a harness The agent-harness ecosystem converged on a clear pattern: the model and the agent loop are commodities supplied by the client (Claude Code, Codex, OpenCode). The durable value is **the tools and the local data**. So Cairn ships *tools, not an agent* — the client provides the loop, the approval prompts (driven by our tool annotations), and the chat. Cairn is just the local file-organization toolset that snaps into whatever harness you already use. ## Architecture Everything is a thin adapter over one standard-library core, so the faces can never drift. ``` core/ cairn-core — the engine (stdlib only): the .uni document format, file operations, tags, retrieval; optional document ingestion (docx/pdf/pptx/xlsx/md) and embeddings-based search. mcp-server/ cairn-mcp-server — MCP server: 21 tools with read-only/destructive annotations, resources, and prompts. ← the flagship cli/ cairn-cli — scriptable CLI, a local HTTP API (`serve`), and an `mcp` launcher. web/ cairn-web — optional zero-build local web UI (browse / edit / view / tag / search). ``` ## Use it **In Claude Code / Codex / Cursor (primary):** ```bash claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes # with real-document import: uvx --with "cairn-core[convert]" cairn-mcp-server ... ``` The server exposes read-only tools (list, read, search, grep, retrieve) that the client runs freely, and destructive tools (move, delete, edit) that it confirms first — driven by MCP tool annotations, so you get approval prompts with no UI of ours. **As a CLI:** ```bash uvx cairn-cli --workspace ~/Documents/notes tree uvx cairn-cli --workspace ~/Documents/notes retrieve "budget planning" ``` **With the optional web UI:** ```bash pip install cairn-cli cairn-web cairn --workspace ~/Documents/notes serve # → http://127.0.0.1:4177/ ``` ## The `.uni` format A `.uni` file is a small JSON document — `{ uuid, content: "", metadata, tags }` — with tags stored *in the file*. A workspace is just a directory: fully portable, no external database. Source documents (docx/pdf/pptx/…) import into editable `.uni` docs; the originals are kept by default. ## Local-first & bring-your-own-key - No account, no login, no cloud sync. The filesystem is the source of truth. - The default retriever is lexical and needs nothing. Embeddings are opt-in and bring-your-own-key (any OpenAI-compatible endpoint, including local servers like Ollama or LM Studio); vectors live in a local SQLite index under `/.cairn/` and never leave your machine. ## Roadmap Cairn is young. Rough direction, and where help is most welcome: - **More document faces** — richer frontmatter support (nested metadata, dates), and round-tripping edits back into imported source formats. - **Smarter digests** — summaries that use an embedding model when one is configured, and saved views (`.cairn/views/*.md`). - **More retrieval backends** — pluggable rerankers; first-class local-model presets (Ollama, LM Studio) beyond the generic OpenAI-compatible path. - **Editor/agent integrations** — thin recipes for wiring Cairn into common MCP clients and note-taking setups. - **Packaging** — signed releases and a Homebrew formula. Have a use case that doesn't fit? [Open an issue](https://github.com/luckyjackluo/cairn/issues) or start a [discussion](https://github.com/luckyjackluo/cairn/discussions). ## Contributing Contributions of every size are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the project layout, dev setup, and how to add a tool. Good first issues are labeled [`good first issue`](https://github.com/luckyjackluo/cairn/labels/good%20first%20issue). ## Develop ```bash make setup # uv venv (3.11) + editable install of all packages + extras make test # run the suite make serve WORKSPACE=~/Documents/notes # web UI ``` ## License MIT — see [LICENSE](LICENSE). ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [luckyjackluo](https://github.com/luckyjackluo) - **Source:** [luckyjackluo/cairn](https://github.com/luckyjackluo/cairn) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-luckyjackluo-cairn - Seller: https://agentstack.voostack.com/s/luckyjackluo - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.