@misterhuydo/cairn-mcp 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,199 @@
+# 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 repos into a local SQLite knowledge graph and exposes 6 MCP tools that give Claude instant, persistent memory across sessions.
+
+---
+
+## Install
+
+```bash
+npm install -g @misterhuydo/cairn-mcp
+```
+
+**Requirements:** Node.js >= 22.15.0
+
+---
+
+## Setup
+
+Add to `~/.claude/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cairn": {
+      "command": "cairn-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Code. Done.
+
+---
+
+## Tools
+
+### `cairn_maintain` — Index your repos
+Run once at the start of each session. The index persists at `~/.cairn/index.db`.
+
+```
+cairn_maintain({ roots: ["/path/to/repo1", "/path/to/repo2"] })
+```
+
+```json
+{
+  "repos_indexed": 3,
+  "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({ roots: [...], filter_paths: ["src/components/checkout"], bundle_name: "checkout" })
+```
+
+```json
+{
+  "bundle_path": "/Users/you/.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
+
+---
+
+## 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
+
+```
+1. cairn_maintain   → index all repos (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
+```
+
+---
+
+## Custom DB path
+
+By default the index is stored at `~/.cairn/index.db`. Override with an env variable:
+
+```json
+{
+  "mcpServers": {
+    "cairn": {
+      "command": "cairn-mcp",
+      "env": { "CAIRN_DB_PATH": "/your/custom/path/index.db" }
+    }
+  }
+}
+```
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@misterhuydo/cairn-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Persistent polyglot knowledge graph MCP server for Claude Code. Index once, query forever — across Java, TypeScript, Vue, Python, SQL and more.",
   "type": "module",
   "main": "index.js",
   "bin": {
-    "cairn-mcp": "./bin/cairn-mcp.js"
+    "cairn-mcp": "bin/cairn-mcp.js"
   },
   "scripts": {
     "start": "node --experimental-sqlite index.js"