@misterhuydo/cairn-mcp 1.2.7 → 1.2.8

package/README.md

@@ -1,309 +1,101 @@
-# Cairn MCP
-
-> Persistent polyglot knowledge graph for Claude Code. Index once, query forever.
-
-Claude is stateless — every session starts at zero. On a multi-repo codebase with Java backends, TypeScript frontends, and Vue components, that means 50% of every session is archaeology: finding where things live before any real work can begin.
-
-**Cairn fixes this.** It indexes your project into a local SQLite knowledge graph (stored in `.cairn/`) and exposes 8 MCP tools that give Claude instant, persistent memory across sessions.
-
----
-
-# Setup
-- See how-to-use.md 
-
-```bash
-npm install -g @misterhuydo/cairn-mcp
-```
-
-**Requirements:** Node.js >= 22.15.0
-
----
-
-## Setup
-
-Add to `~/.claude.json`:
-
-```json
-{
-  "mcpServers": {
-    "cairn": {
-      "command": "cairn-mcp"
-    }
-  }
-}
-```
-
-Restart Claude Code. Done.
-
----
-
-## Passive hooks (recommended)
-
-Install once and Cairn works automatically — no need to call `cairn_bundle` or `cairn_checkpoint` manually.
-
-**Global (all projects):**
-
-```bash
-cairn install-hooks --global
-```
-
-**Project-only:**
-
-```bash
-cairn install-hooks
-```
-
-| Hook | Trigger | Effect |
-|---|---|---|
-| `PreToolUse[Read]` | Every file read | Source files compressed ~68% before Claude sees them |
-| `Stop` | Every response | Session auto-saved to `.cairn/session.json` |
-| `UserPromptSubmit` | First message of session | Claude reminded of prior session, prompted to call `cairn_resume` |
-
-## How it works
-
-Cairn works like git — it looks for `.cairn/` in your current working directory. Run Claude Code from your project root and Cairn automatically stores the index at `.cairn/index.db` and bundles at `.cairn/bundles/`.
-
-No root paths needed. No global config. Just `cd` to your project and go.
-
----
-
-## Tools
-
-### `cairn_maintain` — Index your project
-Run once at the start of each session. The index persists in `.cairn/index.db`.
-
-```
-cairn_maintain()
-cairn_maintain({ languages: ["typescript", "vue"] })  // limit to specific languages
-```
-
-```json
-{
-  "repos_indexed": 1,
-  "files_by_language": { "java": 412, "typescript": 287, "vue": 94 },
-  "symbols_total": 6841,
-  "security_findings": 47,
-  "duration_ms": 4200
-}
-```
-
----
-
-### `cairn_search` — Find anything across all languages
-```
-cairn_search({ query: "user authentication", language: "typescript" })
-```
-
-```json
-[
-  { "lang": "typescript", "kind": "function",  "fqn": "src/composables/useAuth.ts::useAuth" },
-  { "lang": "vue",        "kind": "component", "fqn": "src/components/LoginForm.vue::LoginForm" },
-  { "lang": "java",       "kind": "class",     "fqn": "com.example.auth.UserAuthenticator" }
-]
-```
-
----
-
-### `cairn_bundle` — Minified source snapshot for Claude to read
-Strips comments and empty lines, writes a compressed `### File:` bundle. Use after `cairn_search` to give Claude readable source without blowing the context window.
-
-```
-cairn_bundle({ filter_paths: ["src/components/checkout"], bundle_name: "checkout" })
-```
-
-```json
-{
-  "bundle_path": "/your/project/.cairn/bundles/checkout.txt",
-  "original_kb": 284,
-  "compressed_kb": 91,
-  "reduction_pct": 68
-}
-```
-
----
-
-### `cairn_describe` — Summarize a module
-```
-cairn_describe({ path: "src/components/checkout" })
-```
-
-```json
-{
-  "languages": ["vue", "typescript"],
-  "symbols": {
-    "component": ["CheckoutForm", "OrderSummary", "PaymentStep"],
-    "function":  ["useCheckout", "usePayment"]
-  },
-  "imports_from":  ["src/store/cart.ts", "src/api/orders.ts"],
-  "imported_by":   ["src/views/CartView.vue"],
-  "external_deps": ["stripe", "@stripe/stripe-js"]
-}
-```
-
----
-
-### `cairn_code_graph` — Dependency health
-```
-cairn_code_graph({ mode: "instability" })
-```
-
-```json
-{
-  "modules": [
-    { "name": "src/views",       "instability": 1.0, "status": "safe_to_refactor" },
-    { "name": "src/composables", "instability": 0.4, "status": "review_before_change" },
-    { "name": "src/utils",       "instability": 0.1, "status": "load_bearing" }
-  ]
-}
-```
-
-Modes: `instability` · `health` · `cycles`
-
----
-
-### `cairn_security` — Vulnerability scan
-```
-cairn_security({ severity: "HIGH" })
-```
-
-```json
-{
-  "total_findings": 12,
-  "by_language": { "typescript": 7, "java": 5 },
-  "findings": [
-    { "severity": "HIGH", "cwe": "CWE-79",  "file": "src/components/UserProfile.vue", "line": 84, "rule": "XSS via innerHTML" },
-    { "severity": "HIGH", "cwe": "CWE-611", "file": "backend/src/.../XmlParser.java",  "line": 47, "rule": "XXE" }
-  ]
-}
-```
-
-Covers: XSS · XXE · SQL injection · command injection · weak crypto · hardcoded secrets · open redirect · unsafe deserialization
-
----
-
-### `cairn_minify` — Minify a single file
-Minify one source file on demand. Returns compressed content with a `[cairn: N → M lines]` header. Useful when passive hooks are not installed.
-
-```
-cairn_minify({ file_path: "/abs/path/to/Service.java" })
-```
-
----
-
-### `cairn_checkpoint` — Save session state
-Tell Cairn what you were working on so the next session can pick up where you left off.
-
-```
-cairn_checkpoint({
-  message: "Added multi-currency to CheckoutForm, still need PaymentStep",
-  active_files: ["src/components/checkout/CheckoutForm.vue"],
-  notes: ["CurrencyService expects ISO 4217 codes, not symbols"]
-})
-```
-
-```json
-{
-  "saved": true,
-  "checkpoint_at": "2026-02-25T14:30:00Z",
-  "active_files_tracked": 1,
-  "notes_saved": 1
-}
-```
-
----
-
-### `cairn_resume` — Restore session + smart re-index
-Call instead of `cairn_maintain` when resuming work. Detects which files changed and only re-indexes those.
-
-```
-cairn_resume()
-```
-
-```json
-{
-  "last_checkpoint": "2026-02-25T14:30:00Z",
-  "message": "Added multi-currency to CheckoutForm, still need PaymentStep",
-  "index_status": "incremental",
-  "files_reindexed": 2,
-  "files_unchanged": 845,
-  "changed_since_checkpoint": [
-    { "file": "src/components/checkout/PaymentStep.vue", "change": "modified" }
-  ],
-  "active_files": ["src/components/checkout/CheckoutForm.vue"],
-  "notes": ["CurrencyService expects ISO 4217 codes, not symbols"],
-  "resume_summary": "Last session you were adding multi-currency support..."
-}
-```
-
----
-
-## Supported Languages
-
-| Language | What Cairn extracts |
-|---|---|
-| Java | packages, classes, interfaces, enums, records, methods |
-| TypeScript / JavaScript | classes, interfaces, functions, types, enums |
-| Vue | components, composables, script block symbols |
-| Python | classes, functions, decorators |
-| SQL | tables, views, stored procedures |
-| XML / HTML | bean ids, component names |
-| Config (YAML, properties, .env) | top-level keys |
-| Markdown | headings |
-| Build files (pom.xml, package.json, build.gradle) | dependencies |
-
----
-
-## Typical session
-
-**With passive hooks (recommended):**
-```
-1. cairn_maintain     → index project
-2. cairn_search       → find the symbols you need
-3. cairn_describe     → understand a module before modifying it
-4. cairn_security     → check for issues before a PR
-   (reads auto-compressed, session auto-saved — nothing else needed)
-```
-
-**Without hooks:**
-```
-1. cairn_maintain     → index project (persists between sessions)
-2. cairn_search       → find the symbols you need
-3. cairn_bundle       → get a readable snapshot of relevant files
-4. cairn_describe     → understand a module before modifying it
-5. cairn_security     → check for issues before a PR
-6. cairn_checkpoint   → save what you were working on
-```
-
-**Resuming work:**
-```
-1. cairn_resume       → restore session + incremental re-index
-2. cairn_search       → continue where you left off
-```
-
-## Complete session lifecycle
-
-```
-─── START OF SESSION ──────────────────────────────────────────
-You:    "Hey Claude, please resume and continue"
-Claude: cairn_resume
-        → "Last session: adding multi-currency to checkout.
-           PaymentStep.vue was modified since checkpoint (2 files changed, re-indexed).
-           Notes: CurrencyService expects ISO 4217 codes. PaymentStep EUR bug not fixed yet.
-           Ready to continue."
-
-─── DURING SESSION ────────────────────────────────────────────
-Claude uses: cairn_search, cairn_code_graph, cairn_security
-             as needed — all reading from .cairn/index.db in cwd
-             (file reads auto-compressed by PreToolUse hook)
-
-─── END OF SESSION ────────────────────────────────────────────
-You:    "Ok let's stop here for today"
-        (Stop hook fires → .cairn/session.json auto-saved)
-        → Next session: cairn_resume picks up automatically
-```
-
----
-
-## License
-
-MIT
+# Cairn MCP
+
+Persistent polyglot knowledge graph for Claude Code. Index once, query forever.
+
+Claude is stateless — every session starts cold. Cairn fixes this by indexing your project into a local SQLite knowledge graph and wiring into Claude Code via hooks, so file compression, checkpointing, and session restore all happen automatically in the background.
+
+---
+
+## Install
+
+```bash
+npm install -g @misterhuydo/cairn-mcp
+```
+
+**Requirements:** Node.js >= 22.15.0
+
+---
+
+## Setup
+
+**1. Register the MCP server** — add to `~/.claude.json` and restart Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "cairn": {
+      "command": "cairn-mcp"
+    }
+  }
+}
+```
+
+> Already have other MCP servers? Just add `"cairn": { "command": "cairn-mcp" }` inside your existing `"mcpServers"` block.
+
+**2. Install passive hooks:**
+
+```bash
+cairn install-hooks --global   # recommended — applies to all projects
+# or
+cairn install-hooks            # this project only (.claude/settings.json)
+```
+
+That's it. Cairn now runs silently in the background — no manual tool calls needed.
+
+---
+
+## What the hooks do
+
+| Hook | Trigger | Effect |
+|---|---|---|
+| `PreToolUse[Read]` | Every file read | Source files compressed ~68% before Claude sees them |
+| `Stop` | End of every response | Session auto-saved to `.cairn/session.json` |
+| `UserPromptSubmit` | First message of a new session | Fresh project: Claude prompted to run `cairn_maintain`. Returning session: Claude prompted to run `cairn_resume` |
+
+---
+
+## First use
+
+Just open Claude Code from your project root and start working. The `UserPromptSubmit` hook handles everything:
+
+- **Fresh project** — hook tells Claude to run `cairn_maintain`, index is built automatically
+- **Returning session** — hook tells Claude to run `cairn_resume`, prior context is restored
+
+No manual steps. The index lives in `.cairn/index.db` inside your project — like a `.git` folder, just `cd` to the root and everything works.
+
+---
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `cairn_maintain` | Full index of the current project |
+| `cairn_resume` | Restore last session + re-index only changed files |
+| `cairn_search` | Find classes, functions, components by name or concept |
+| `cairn_describe` | Summarize what a folder or module does |
+| `cairn_code_graph` | Dependency health — instability, cycles, load-bearing modules |
+| `cairn_security` | Scan for XSS, SQLi, hardcoded secrets, weak crypto, and more |
+| `cairn_bundle` | Minified source snapshot (auto-handled by hooks) |
+| `cairn_checkpoint` | Save session state (auto-handled by hooks) |
+
+---
+
+## Supported languages
+
+| Language | What Cairn extracts |
+|---|---|
+| Java | packages, classes, interfaces, enums, records, methods |
+| TypeScript / JavaScript | classes, interfaces, functions, types, enums |
+| Vue | components, composables, script block symbols |
+| Python | classes, functions, decorators |
+| SQL | tables, views, stored procedures |
+| XML / HTML | bean ids, component names |
+| Config (YAML, properties, .env) | top-level keys |
+| Markdown | headings |
+| Build files (pom.xml, package.json, build.gradle) | dependencies |
+
+---
+
+## License
+
+MIT

package/bin/cairn-cli.js

@@ -147,9 +147,22 @@ if (subcommand === 'minify') {
 } else if (subcommand === 'resume-hint') {
   const cairnDir = path.join(process.cwd(), '.cairn');
   const sessionPath = path.join(cairnDir, 'session.json');
-  if (!fs.existsSync(sessionPath)) process.exit(0);
+  const dbPath = path.join(cairnDir, 'index.db');
   const lockPath = path.join(cairnDir, '.hint-lock');
   const LOCK_TTL_MS = 30 * 60 * 1000;
+  if (!fs.existsSync(sessionPath)) {
+    // No session yet — prompt to index if DB is also missing (fresh project)
+    if (!fs.existsSync(dbPath)) {
+      if (fs.existsSync(lockPath)) {
+        const age = Date.now() - fs.statSync(lockPath).mtimeMs;
+        if (age < LOCK_TTL_MS) process.exit(0);
+      }
+      fs.mkdirSync(cairnDir, { recursive: true });
+      fs.writeFileSync(lockPath, new Date().toISOString(), 'utf8');
+      process.stdout.write('[cairn] No index found. Run cairn_maintain to index this project.\n');
+    }
+    process.exit(0);
+  }
   if (fs.existsSync(lockPath)) {
     const age = Date.now() - fs.statSync(lockPath).mtimeMs;
     if (age < LOCK_TTL_MS) process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misterhuydo/cairn-mcp",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "MCP server that gives Claude Code persistent memory across sessions. Index your codebase once, search symbols, bundle source, scan for vulnerabilities, and checkpoint/resume work — across Java, TypeScript, Vue, Python, SQL and more.",
   "type": "module",
   "main": "index.js",

package/how-to-use.md

@@ -1,226 +0,0 @@
-# Claude Global Instructions
-
-## MCP Tools — Cairn Session Lifecycle
-
-Always use cairn MCP tools to manage project context across sessions.
-
-### Start of Session
-When starting work on a project, always run:
-1. `cairn_resume` — restores last session context and incrementally re-indexes changed files
-
-If it's a **fresh project** with no prior session:
-1. `cairn_maintain` — index the project (persists between sessions)
-
-### During Session
-Use these tools as needed throughout the session:
-- `cairn_search` — find symbols, functions, or files before reading or modifying code
-- `cairn_bundle` — get a readable snapshot of relevant files before making changes
-- `cairn_describe` — understand a module before modifying it
-- `cairn_security` — check for security issues (always run before a PR)
-
-**Prefer cairn tools over manual file browsing or grep when available.**
-
-### End of Session
-When the user signals they are done (e.g. "let's stop", "that's enough for today", "wrap up"), always run:
-- `cairn_checkpoint` — save session state with:
-  - `message`: summary of what was accomplished
-  - `active_files`: files that were modified or are in progress
-  - `notes`: important context, known bugs, or next steps
-
----
-
-## Example Session
-
-**Resuming:**
-> User: "Hey Claude, please resume and continue"
-> Claude runs `cairn_resume` → reads context → continues work
-
-**Ending:**
-> User: "Ok let's stop here for today"
-> Claude runs `cairn_checkpoint` with a meaningful summary and notes → confirms session saved
-
----
-
-# Cairn — Quick Start
-
-> **Requirements:** Node.js >= 22.15.0
-
-## 1. Install globally
-
-```bash
-npm install -g @misterhuydo/cairn-mcp
-```
-
-Two commands are now available: `cairn-mcp` (MCP server) and `cairn` (CLI for hooks).
-
-## 2. Install passive hooks (recommended)
-
-Cairn hooks into Claude Code so that compression and checkpointing happen automatically — no need to call `cairn_bundle` or `cairn_checkpoint` manually.
-
-**Global — applies to every project on this machine:**
-
-```bash
-cairn install-hooks --global
-```
-
-**Project-level — applies to this project only:**
-
-```bash
-cairn install-hooks
-```
-
-Both write to `~/.claude/settings.json` (global) or `.claude/settings.json` (project). Safe to run multiple times — existing settings are preserved.
-
-What this sets up:
-
-| Hook | Effect |
-|---|---|
-| `PreToolUse[Read]` | Every source file read is silently compressed before Claude sees it (~68% fewer tokens for `.java/.ts/.js/.vue/.py/.sql`) |
-| `Stop` | Session auto-saved to `.cairn/session.json` every time Claude finishes responding |
-| `UserPromptSubmit` | On the first message of a new session, Claude is reminded of the prior session and prompted to call `cairn_resume` |
-
-After this you never need to call `cairn_bundle` or `cairn_checkpoint` — Claude reads files normally and compression + checkpointing happen transparently in the background.
-
-## 3. Register the MCP server with Claude Code
-
-Add to your `~/.claude.json` and restart Claude Code. You should see 8 cairn tools available.
-
-**File location by platform:**
-
-| Platform | Path |
-|---|---|
-| Windows | `C:\\Users\\<you>\\.claude.json` |
-| macOS | `~/.claude.json` |
-| Linux | `~/.claude.json` |
-
-```json
-{
-  "mcpServers": {
-    "cairn": {
-      "command": "cairn-mcp"
-    }
-  }
-}
-```
-
-> If you already have other MCP servers, just add `"cairn": { ... }` inside the existing `"mcpServers"` block.
-
-## 4. (Optional) Configure Claude via CLAUDE.md
-
-If you prefer Claude to manage session lifecycle explicitly rather than via hooks, create a global `CLAUDE.md` file. This is an alternative to passive hooks — you don't need both.
-
-**File location by platform:**
-
-| Platform | Path |
-|---|---|
-| Windows | `C:\\Users\\<you>\\CLAUDE.md` |
-| macOS | `~/CLAUDE.md` |
-| Linux | `~/CLAUDE.md` |
-
-Copy and save the following content into that file:
-
-````markdown
-## MCP Tools — Cairn Session Lifecycle
-
-Always use cairn MCP tools to manage project context across sessions.
-
-### Start of Session
-When starting work on a project, always run:
-1. `cairn_resume` — restores last session context and incrementally re-indexes changed files
-
-If it's a fresh project with no prior session:
-1. `cairn_maintain` — index the project (persists between sessions)
-
-### During Session
-Use these tools as needed throughout the session:
-- `cairn_search` — find symbols, functions, or files before reading or modifying code
-- `cairn_bundle` — get a readable snapshot of relevant files before making changes
-- `cairn_describe` — understand a module before modifying it
-- `cairn_security` — check for security issues (always run before a PR)
-
-Prefer cairn tools over manual file browsing or grep when available.
-
-### End of Session
-When the user signals they are done (e.g. "let's stop", "that's enough for today", "wrap up"), always run:
-- `cairn_checkpoint` — save session state with:
-  - `message`: summary of what was accomplished
-  - `active_files`: files that were modified or are in progress
-  - `notes`: important context, known bugs, or next steps
-````
-
-## 5. Index your project
-
-Run Claude Code from your project root, then:
-
-
-```
-cairn_maintain
-```
-
-No paths needed — Cairn works like git and finds your project from the current directory. The index is stored in `.cairn/index.db` inside your project.
-
-Run this once at the start of each session (or use `cairn_resume` to pick up where you left off).
-
-## 6. Tools at a glance
-
-| Tool | What to use it for |
-|---|---|
-| `cairn_maintain` | Index the current project (run at session start) |
-| `cairn_search` | Find classes, functions, components by name or concept |
-| `cairn_describe` | Summarize what a folder/module does |
-| `cairn_code_graph` | Check instability, health, or cycles before refactoring |
-| `cairn_security` | Scan for vulnerabilities (XSS, SQLi, hardcoded secrets, etc.) |
-| `cairn_bundle` | Package source files into a minified snapshot for Claude to read |
-| `cairn_checkpoint` | Save what you're working on so the next session can resume |
-| `cairn_resume` | Restore the last checkpoint + incremental re-index of changed files |
-
-> `cairn_bundle` and `cairn_checkpoint` are called automatically when passive hooks are installed. They remain available for explicit use when needed.
-
-## 7. Typical session
-
-**With passive hooks (recommended):**
-```
-1. cairn_maintain     → index the project
-2. cairn_search       → find what you need
-3. cairn_describe     → understand a module before modifying it
-4. cairn_security     → check for issues before a PR
-   (file reads auto-compressed, session auto-saved — nothing else needed)
-```
-
-**Without hooks:**
-```
-1. cairn_maintain     → index the project
-2. cairn_search       → find what you need
-3. cairn_bundle       → get a readable snapshot of relevant files
-4. cairn_describe     → understand a module before modifying it
-5. cairn_security     → check for issues before a PR
-6. cairn_checkpoint   → save your progress before ending the session
-```
-
-**Resuming work:**
-```
-1. cairn_resume       → restore last checkpoint + re-index only changed files
-2. cairn_search       → continue where you left off
-```
-
-## 8. Complete session lifecycle
-
-```
-─── START OF SESSION ──────────────────────────────────────────
-You:    "Hey Claude, please resume and continue"
-Claude: cairn_resume
-        → "Last session: adding multi-currency to checkout.
-           PaymentStep.vue was modified since checkpoint (2 files changed, re-indexed).
-           Notes: CurrencyService expects ISO 4217 codes. PaymentStep EUR bug not fixed yet.
-           Ready to continue."
-
-─── DURING SESSION ────────────────────────────────────────────
-Claude uses: cairn_search, cairn_code_graph, cairn_security
-             as needed — all reading from .cairn/index.db in cwd
-             (file reads auto-compressed by PreToolUse hook)
-
-─── END OF SESSION ────────────────────────────────────────────
-You:    "Ok let's stop here for today"
-        (Stop hook fires → .cairn/session.json auto-saved)
-        → Next session: cairn_resume picks up automatically
-```