promptgraph-mcp 1.7.0 → 1.8.1

package/README.md

@@ -1,186 +1,186 @@
-# PromptGraph
-
-**Stop burning 50,000 tokens on skills you won't use.**
-
-PromptGraph is an MCP server that gives Claude Code a semantic skill index — vector search, skill graph, and a community marketplace. Instead of cramming every `.md` into your system prompt, Claude finds and loads only the one skill it needs.
-
-[![npm](https://img.shields.io/npm/v/promptgraph-mcp?color=7C3AED&label=npm)](https://www.npmjs.com/package/promptgraph-mcp)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-
----
-
-## Why
-
-Claude Code loads skill metadata from `~/.claude/commands/` each session. With 40+ skills that's thousands of tokens in routing overhead before you say a word. More importantly, when Claude loads and executes a full skill file (typically 1,000–5,000 tokens each), the cost multiplies fast.
-
-PromptGraph replaces that with one tiny router skill (`~150 tokens`) and a local vector index. Claude calls `pg_search` → gets the right skill path + a content snippet → reads only that file when needed.
-
-```
-Before:  route across all 40 skills  →  40 × read overhead
-After:   1 pg_search call + snippet  →  read only what you need
-```
-
----
-
-## Features
-
-- 🔍 **Semantic search** — finds skills by meaning, not just keywords (HNSW, O(log N))
-- 📦 **Marketplace** — browse and install community skills with one command
-- 🧩 **Skill bundles** — install curated packs (e.g. `engineering-essentials`)
-- 🔗 **Dependency graph** — tracks which skills call other skills (`pg_callers`, `pg_impact`)
-- ⚡ **Local embeddings** — `fastembed` BGE-Small-EN, 23 MB, no API key needed
-- 👁️ **File watcher** — auto-reindexes when you add or edit skills
-- 🛡️ **Validator** — blocks malicious/junk skills before they reach your machine
-- 🌐 **MCP-native** — works with Claude Code, Claude Desktop, Cline, OpenCode, Cursor, Windsurf, and any MCP client
-
----
-
-## Quick Start
-
-```bash
-# one-time global install (recommended — faster than npx every time)
-npm install -g promptgraph-mcp@latest
-pg init
-
-# or without installing
-npx promptgraph-mcp init
-```
-
-`init` downloads the embedding model (~23 MB, once), indexes your skills, and prints the config to paste into `settings.json`.
-
-### Add to Claude Code (`~/.claude/settings.json`)
-
-```json
-{
-  "mcpServers": {
-    "promptgraph": {
-      "command": "npx",
-      "args": ["promptgraph-mcp"]
-    }
-  }
-}
-```
-
-### Add to OpenCode (`~/.config/opencode/opencode.json`)
-
-```json
-{
-  "mcp": {
-    "promptgraph": {
-      "type": "local",
-      "command": ["npx", "promptgraph-mcp"],
-      "enabled": true
-    }
-  }
-}
-```
-
-> `pg setup` auto-detects OpenCode and writes this config for you.
-
-### Move your skills out of `commands/`
-
-```bash
-mkdir -p ~/.claude/skills-store
-mv ~/.claude/commands/*.md ~/.claude/skills-store/
-mv ~/.claude/skills-store/pg.md ~/.claude/commands/   # keep only the router
-```
-
----
-
-## Marketplace
-
-Browse and install community skills without leaving your terminal:
-
-```bash
-pg marketplace        # browse skills
-pg marketplace bundles  # browse bundles
-```
-
-Or ask Claude directly:
-
-```
-install pg-a1b2c3          # by code
-install systematic-debugging  # by name
-```
-
-**Publish your own skill:**
-
-```bash
-pg publish ~/.claude/skills-store/my-skill.md
-```
-
-> Skills are validated automatically — dangerous patterns, prompt injection, and junk are rejected by CI before they enter the registry.
-
----
-
-## CLI
-
-```bash
-pg init             # first-time setup
-pg reindex          # re-index all skills
-pg search "deploy"  # search from terminal
-pg list             # list all indexed skills
-pg marketplace      # browse registry
-pg import owner/repo   # import any GitHub repo full of .md skills
-pg validate my-skill.md
-pg doctor           # clean up orphaned data
-```
-
----
-
-## MCP Tools (used by Claude automatically)
-
-| Tool | What it does |
-|---|---|
-| `pg_search` | Semantic skill search by task description |
-| `pg_list` | List all indexed skills |
-| `pg_context` | Full skill details + callers/callees |
-| `pg_callers` | Which skills reference this one |
-| `pg_callees` | Which skills this one calls |
-| `pg_impact` | What breaks if this skill changes |
-| `pg_marketplace_browse` | Browse community registry |
-| `pg_marketplace_install` | Install a skill by code, id, or name |
-| `pg_bundle_browse` | Browse skill bundles |
-| `pg_bundle_install` | Install a bundle |
-| `pg_top_rated` | Highest-rated local skills |
-| `pg_rate` | Rate a skill (success/fail) |
-
----
-
-## Token Savings
-
-| | Before PromptGraph | After PromptGraph |
-|---|---|---|
-| Skills in system prompt | All 40+ every session | 1 router (~150 tokens) |
-| Tokens per session | 20,000 – 50,000 | ~300 + 1 skill on demand |
-| Skills you can have | ~30 before it gets painful | Unlimited |
-
----
-
-## How It Works
-
-```
-pg_search("refactor without breaking tests")
-  → embed query  →  HNSW ANN search  →  rank by cosine + rating boost
-  → return top skill path
-  → Claude reads only that file
-```
-
-Embeddings are stored in SQLite. The HNSW index ([vectra](https://github.com/Stevenic/vectra)) keeps search sub-millisecond even at thousands of skills. Skills are re-indexed automatically via `chokidar` file watcher.
-
----
-
-## Requirements
-
-- Node.js 18+
-- Claude Code or Claude Desktop (any MCP-compatible client)
-
----
-
-## Related
-
-- 📋 [promptgraph-registry](https://github.com/NeiP4n/promptgraph-registry) — community skill registry
-
----
-
-*Built with [Claude](https://claude.com/claude-code) by Anthropic.*
+# PromptGraph
+
+**Stop burning 50,000 tokens on skills you won't use.**
+
+PromptGraph is an MCP server that gives Claude Code a semantic skill index — vector search, skill graph, and a community marketplace. Instead of cramming every `.md` into your system prompt, Claude finds and loads only the one skill it needs.
+
+[![npm](https://img.shields.io/npm/v/promptgraph-mcp?color=7C3AED&label=npm)](https://www.npmjs.com/package/promptgraph-mcp)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+---
+
+## Why
+
+Claude Code loads skill metadata from `~/.claude/commands/` each session. With 40+ skills that's thousands of tokens in routing overhead before you say a word. More importantly, when Claude loads and executes a full skill file (typically 1,000–5,000 tokens each), the cost multiplies fast.
+
+PromptGraph replaces that with one tiny router skill (`~150 tokens`) and a local vector index. Claude calls `pg_search` → gets the right skill path + a content snippet → reads only that file when needed.
+
+```
+Before:  route across all 40 skills  →  40 × read overhead
+After:   1 pg_search call + snippet  →  read only what you need
+```
+
+---
+
+## Features
+
+- 🔍 **Semantic search** — finds skills by meaning, not just keywords (HNSW, O(log N))
+- 📦 **Marketplace** — browse and install community skills with one command
+- 🧩 **Skill bundles** — install curated packs (e.g. `engineering-essentials`)
+- 🔗 **Dependency graph** — tracks which skills call other skills (`pg_callers`, `pg_impact`)
+- ⚡ **Local embeddings** — `fastembed` BGE-Small-EN, 23 MB, no API key needed
+- 👁️ **File watcher** — auto-reindexes when you add or edit skills
+- 🛡️ **Validator** — blocks malicious/junk skills before they reach your machine
+- 🌐 **MCP-native** — works with Claude Code, Claude Desktop, Cline, OpenCode, Cursor, Windsurf, and any MCP client
+
+---
+
+## Quick Start
+
+```bash
+# one-time global install (recommended — faster than npx every time)
+npm install -g promptgraph-mcp@latest
+pg init
+
+# or without installing
+npx promptgraph-mcp init
+```
+
+`init` downloads the embedding model (~23 MB, once), indexes your skills, and prints the config to paste into `settings.json`.
+
+### Add to Claude Code (`~/.claude/settings.json`)
+
+```json
+{
+  "mcpServers": {
+    "promptgraph": {
+      "command": "npx",
+      "args": ["promptgraph-mcp"]
+    }
+  }
+}
+```
+
+### Add to OpenCode (`~/.config/opencode/opencode.json`)
+
+```json
+{
+  "mcp": {
+    "promptgraph": {
+      "type": "local",
+      "command": ["npx", "promptgraph-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+> `pg setup` auto-detects OpenCode and writes this config for you.
+
+### Move your skills out of `commands/`
+
+```bash
+mkdir -p ~/.claude/skills-store
+mv ~/.claude/commands/*.md ~/.claude/skills-store/
+mv ~/.claude/skills-store/pg.md ~/.claude/commands/   # keep only the router
+```
+
+---
+
+## Marketplace
+
+Browse and install community skills without leaving your terminal:
+
+```bash
+pg marketplace        # browse skills
+pg marketplace bundles  # browse bundles
+```
+
+Or ask Claude directly:
+
+```
+install pg-a1b2c3          # by code
+install systematic-debugging  # by name
+```
+
+**Publish your own skill:**
+
+```bash
+pg publish ~/.claude/skills-store/my-skill.md
+```
+
+> Skills are validated automatically — dangerous patterns, prompt injection, and junk are rejected by CI before they enter the registry.
+
+---
+
+## CLI
+
+```bash
+pg init             # first-time setup
+pg reindex          # re-index all skills
+pg search "deploy"  # search from terminal
+pg list             # list all indexed skills
+pg marketplace      # browse registry
+pg import owner/repo   # import any GitHub repo full of .md skills
+pg validate my-skill.md
+pg doctor           # clean up orphaned data
+```
+
+---
+
+## MCP Tools (used by Claude automatically)
+
+| Tool | What it does |
+|---|---|
+| `pg_search` | Semantic skill search by task description |
+| `pg_list` | List all indexed skills |
+| `pg_context` | Full skill details + callers/callees |
+| `pg_callers` | Which skills reference this one |
+| `pg_callees` | Which skills this one calls |
+| `pg_impact` | What breaks if this skill changes |
+| `pg_marketplace_browse` | Browse community registry |
+| `pg_marketplace_install` | Install a skill by code, id, or name |
+| `pg_bundle_browse` | Browse skill bundles |
+| `pg_bundle_install` | Install a bundle |
+| `pg_top_rated` | Highest-rated local skills |
+| `pg_rate` | Rate a skill (success/fail) |
+
+---
+
+## Token Savings
+
+| | Before PromptGraph | After PromptGraph |
+|---|---|---|
+| Skills in system prompt | All 40+ every session | 1 router (~150 tokens) |
+| Tokens per session | 20,000 – 50,000 | ~300 + 1 skill on demand |
+| Skills you can have | ~30 before it gets painful | Unlimited |
+
+---
+
+## How It Works
+
+```
+pg_search("refactor without breaking tests")
+  → embed query  →  HNSW ANN search  →  rank by cosine + rating boost
+  → return top skill path
+  → Claude reads only that file
+```
+
+Embeddings are stored in SQLite. The HNSW index ([vectra](https://github.com/Stevenic/vectra)) keeps search sub-millisecond even at thousands of skills. Skills are re-indexed automatically via `chokidar` file watcher.
+
+---
+
+## Requirements
+
+- Node.js 18+
+- Claude Code or Claude Desktop (any MCP-compatible client)
+
+---
+
+## Related
+
+- 📋 [promptgraph-registry](https://github.com/NeiP4n/promptgraph-registry) — community skill registry
+
+---
+
+*Built with [Claude](https://claude.com/claude-code) by Anthropic.*

package/ann.js

@@ -1,61 +1,61 @@
-import { getDb, blobToVec } from './db.js';
-
-// In-memory flat index — no external dependency.
-// For typical skill counts (<5000) this is faster than vectra's disk-based HNSW
-// because all data fits in RAM and no I/O is needed per query.
-let _cache = null;
-let _cacheChunkCount = -1;
-
-function loadCache(db) {
-  const count = db.prepare('SELECT COUNT(*) as n FROM chunks').get().n;
-  if (_cache && count === _cacheChunkCount) return _cache;
-  const rows = db.prepare('SELECT skill_id, embedding FROM chunks').all();
-  _cache = rows.map(r => ({
-    skill_id: r.skill_id,
-    vec: new Float32Array(blobToVec(r.embedding)),
-  }));
-  _cacheChunkCount = count;
-  return _cache;
-}
-
-function cosineSim(a, b) {
-  let dot = 0, na = 0, nb = 0;
-  for (let i = 0; i < a.length; i++) {
-    dot += a[i] * b[i];
-    na += a[i] * a[i];
-    nb += b[i] * b[i];
-  }
-  return dot / (Math.sqrt(na) * Math.sqrt(nb) + 1e-8);
-}
-
-// Called after reindex — invalidate cache so next search reloads
-export async function buildAnnIndex() {
-  _cache = null;
-  _cacheChunkCount = -1;
-  const db = getDb();
-  const count = db.prepare('SELECT COUNT(*) as n FROM chunks').get().n;
-  console.error(`[PromptGraph] In-memory index ready: ${count} chunks`);
-}
-
-export async function annSearch(queryVec, topK = 20) {
-  try {
-    const db = getDb();
-    const cache = loadCache(db);
-    if (!cache.length) return null;
-
-    const qArr = new Float32Array(queryVec);
-    const bestBySkill = new Map();
-    for (const entry of cache) {
-      const score = cosineSim(qArr, entry.vec);
-      const prev = bestBySkill.get(entry.skill_id);
-      if (!prev || score > prev) bestBySkill.set(entry.skill_id, score);
-    }
-
-    return [...bestBySkill.entries()]
-      .sort((a, b) => b[1] - a[1])
-      .slice(0, topK)
-      .map(([skill_id, score]) => ({ skill_id, score }));
-  } catch {
-    return null;
-  }
-}
+import { getDb, blobToVec } from './db.js';
+
+// In-memory flat index — no external dependency.
+// For typical skill counts (<5000) this is faster than vectra's disk-based HNSW
+// because all data fits in RAM and no I/O is needed per query.
+let _cache = null;
+let _cacheChunkCount = -1;
+
+function loadCache(db) {
+  const count = db.prepare('SELECT COUNT(*) as n FROM chunks').get().n;
+  if (_cache && count === _cacheChunkCount) return _cache;
+  const rows = db.prepare('SELECT skill_id, embedding FROM chunks').all();
+  _cache = rows.map(r => ({
+    skill_id: r.skill_id,
+    vec: new Float32Array(blobToVec(r.embedding)),
+  }));
+  _cacheChunkCount = count;
+  return _cache;
+}
+
+function cosineSim(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  return dot / (Math.sqrt(na) * Math.sqrt(nb) + 1e-8);
+}
+
+// Called after reindex — invalidate cache so next search reloads
+export async function buildAnnIndex() {
+  _cache = null;
+  _cacheChunkCount = -1;
+  const db = getDb();
+  const count = db.prepare('SELECT COUNT(*) as n FROM chunks').get().n;
+  console.error(`[PromptGraph] In-memory index ready: ${count} chunks`);
+}
+
+export async function annSearch(queryVec, topK = 20) {
+  try {
+    const db = getDb();
+    const cache = loadCache(db);
+    if (!cache.length) return null;
+
+    const qArr = new Float32Array(queryVec);
+    const bestBySkill = new Map();
+    for (const entry of cache) {
+      const score = cosineSim(qArr, entry.vec);
+      const prev = bestBySkill.get(entry.skill_id);
+      if (!prev || score > prev) bestBySkill.set(entry.skill_id, score);
+    }
+
+    return [...bestBySkill.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, topK)
+      .map(([skill_id, score]) => ({ skill_id, score }));
+  } catch {
+    return null;
+  }
+}

package/chunker.js

@@ -1,26 +1,26 @@
-const CHUNK_SIZE = 800;
-const CHUNK_OVERLAP = 100;
-
-export function chunkText(text) {
-  // Split on markdown h1/h2/h3 headers to preserve semantic boundaries
-  const sections = text.split(/(?=\n#{1,3} )/);
-  const chunks = [];
-
-  for (const section of sections) {
-    const words = section.split(/\s+/).filter(Boolean);
-    if (words.length === 0) continue;
-
-    if (words.length <= CHUNK_SIZE) {
-      chunks.push(section.trim());
-    } else {
-      let i = 0;
-      while (i < words.length) {
-        chunks.push(words.slice(i, i + CHUNK_SIZE).join(' '));
-        if (i + CHUNK_SIZE >= words.length) break;
-        i += CHUNK_SIZE - CHUNK_OVERLAP;
-      }
-    }
-  }
-
-  return chunks.length > 0 ? chunks : [text];
-}
+const CHUNK_SIZE = 800;
+const CHUNK_OVERLAP = 100;
+
+export function chunkText(text) {
+  // Split on markdown h1/h2/h3 headers to preserve semantic boundaries
+  const sections = text.split(/(?=\n#{1,3} )/);
+  const chunks = [];
+
+  for (const section of sections) {
+    const words = section.split(/\s+/).filter(Boolean);
+    if (words.length === 0) continue;
+
+    if (words.length <= CHUNK_SIZE) {
+      chunks.push(section.trim());
+    } else {
+      let i = 0;
+      while (i < words.length) {
+        chunks.push(words.slice(i, i + CHUNK_SIZE).join(' '));
+        if (i + CHUNK_SIZE >= words.length) break;
+        i += CHUNK_SIZE - CHUNK_OVERLAP;
+      }
+    }
+  }
+
+  return chunks.length > 0 ? chunks : [text];
+}