promptgraph-mcp 1.0.0

package/README.md

@@ -0,0 +1,159 @@
+# PromptGraph
+
+Semantic skill router for Claude Code. Instead of loading all your skills into context on every request, PromptGraph indexes them with vector embeddings and loads only the relevant one on demand.
+
+## The Problem
+
+Claude Code loads all `.md` files from `~/.claude/commands/` into the system prompt on every session. With 40+ skills, that's **20,000–50,000 tokens wasted per conversation** — before you've even said hello.
+
+## The Solution
+
+```
+~/.claude/commands/
+  pg.md          ← one tiny router skill (~150 tokens)
+
+~/.claude/skills-store/
+  game-audit.md
+  chain.md
+  hunt-sqli.md
+  ...            ← 40+ skills, NOT loaded into context
+```
+
+When you ask Claude a question, it calls `pg_search("your task")` → finds the right skill via vector search → reads only that file. **One skill loaded instead of forty.**
+
+## Features
+
+- **Vector search** via `fastembed` (`BGE-Small-EN`, 23MB, runs locally, no API needed)
+- **Semantic matching** — Russian query finds English skill, synonyms work
+- **Auto-reindex** via file watcher when skills change
+- **Graph edges** — tracks which skills call other skills
+- **MCP server** — integrates directly into Claude Code and Claude Desktop
+
+## Installation
+
+### Via npx (recommended)
+
+```bash
+npx promptgraph init
+```
+
+### From source
+
+```bash
+git clone https://github.com/NeiP4n/promptgraph
+cd promptgraph
+npm install
+npm link
+promptgraph init
+```
+
+`init` will:
+1. Ask for extra skill directories (optional)
+2. Download the embedding model (~23MB, one time)
+3. Index all your skills
+4. Print the config snippet to add to `settings.json`
+
+## Setup
+
+### Claude Code (`~/.claude/settings.json`)
+
+```json
+{
+  "mcpServers": {
+    "promptgraph": {
+      "command": "npx",
+      "args": ["promptgraph"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add the same block to `claude_desktop_config.json`.
+
+### Router skill (`~/.claude/commands/pg.md`)
+
+```markdown
+---
+name: pg
+description: PromptGraph router — finds and loads the right skill for any task
+---
+
+# PromptGraph Router
+
+You have access to a semantic skill index via the `promptgraph` MCP server.
+
+## How to handle any task
+
+1. Call `pg_search` with the user's task as query (in English)
+2. Pick the top result with score > 0.6
+3. Read the skill file at the returned `path`
+4. Execute that skill's instructions
+
+## If no good match (score < 0.6)
+
+Handle the task directly without a skill.
+```
+
+Move all your other skills from `commands/` to `skills-store/`:
+
+```bash
+mkdir -p ~/.claude/skills-store
+mv ~/.claude/commands/*.md ~/.claude/skills-store/
+mv ~/.claude/skills-store/pg.md ~/.claude/commands/
+```
+
+## Commands
+
+```bash
+promptgraph init      # First-time setup (interactive)
+promptgraph reindex   # Re-index all skills
+```
+
+## MCP Tools
+
+| Tool | Description |
+|---|---|
+| `pg_search` | Semantic search by task description |
+| `pg_list` | List all indexed skills |
+| `pg_context` | Full details for a skill |
+| `pg_callers` | Which skills reference this one |
+| `pg_callees` | Which skills this one references |
+| `pg_impact` | What breaks if this skill changes |
+
+## Token Savings
+
+| | Before | After |
+|---|---|---|
+| Skills in context | All 40+ | 1 (router) |
+| Tokens per session | ~20,000–50,000 | ~150 + 1 skill |
+| Scales to | ~50 skills | 5,000+ skills |
+
+## File Structure
+
+```
+promptgraph/
+  index.js       ← MCP server + CLI
+  config.js      ← Config management
+  db.js          ← SQLite setup
+  embedder.js    ← fastembed wrapper
+  indexer.js     ← Skill indexer
+  parser.js      ← .md parser
+  search.js      ← Vector search + graph queries
+  watcher.js     ← File watcher (auto-reindex)
+
+~/.claude/.promptgraph/
+  promptgraph.db       ← SQLite index
+  model-cache/         ← Embedding model cache
+  config.json          ← Skill directory config
+```
+
+## Requirements
+
+- Node.js 18+
+- Claude Code or Claude Desktop
+
+---
+
+*Generated with [Claude](https://claude.ai) by Anthropic*

package/config.js

@@ -0,0 +1,51 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import readline from 'readline';
+
+const CONFIG_PATH = path.join(os.homedir(), '.claude', '.promptgraph', 'config.json');
+
+const DEFAULTS = {
+  sources: [
+    { dir: path.join(os.homedir(), '.claude', 'skills-store'), source: 'skills-store' },
+    { dir: path.join(os.homedir(), '.claude', 'skills'), source: 'skills' },
+    { dir: path.join(os.homedir(), '.claude', 'commands'), source: 'commands' },
+  ],
+};
+
+export function loadConfig() {
+  if (fs.existsSync(CONFIG_PATH)) {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+  }
+  return DEFAULTS;
+}
+
+export function saveConfig(config) {
+  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+export async function promptConfig() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise(r => rl.question(q, r));
+
+  console.log('\n=== PromptGraph Setup ===\n');
+  console.log('Default skill directories:');
+  DEFAULTS.sources.forEach((s, i) => console.log(`  ${i + 1}. ${s.dir}`));
+
+  const extra = await ask('\nAdd extra skill directories? (comma-separated paths, or press Enter to skip): ');
+  rl.close();
+
+  const config = { ...DEFAULTS };
+
+  if (extra.trim()) {
+    const extraDirs = extra.split(',').map(d => d.trim()).filter(Boolean);
+    for (const dir of extraDirs) {
+      config.sources.push({ dir, source: 'custom' });
+    }
+  }
+
+  saveConfig(config);
+  console.log(`\nConfig saved to ${CONFIG_PATH}`);
+  return config;
+}

package/db.js

@@ -0,0 +1,32 @@
+import Database from 'better-sqlite3';
+import path from 'path';
+import os from 'os';
+import fs from 'fs';
+
+const DB_PATH = path.join(os.homedir(), '.claude', '.promptgraph', 'promptgraph.db');
+
+export function getDb() {
+  fs.mkdirSync(path.dirname(DB_PATH), { recursive: true });
+  const db = new Database(DB_PATH);
+  db.pragma('journal_mode = WAL');
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS skills (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT UNIQUE NOT NULL,
+      description TEXT,
+      path TEXT NOT NULL,
+      source TEXT NOT NULL,
+      content TEXT NOT NULL,
+      embedding TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS edges (
+      from_skill TEXT NOT NULL,
+      to_skill TEXT NOT NULL,
+      PRIMARY KEY (from_skill, to_skill)
+    );
+  `);
+
+  return db;
+}

package/embedder.js

@@ -0,0 +1,32 @@
+import { EmbeddingModel, FlagEmbedding } from 'fastembed';
+import path from 'path';
+import os from 'os';
+
+const CACHE_DIR = path.join(os.homedir(), '.claude', '.promptgraph', 'model-cache');
+
+let model = null;
+
+async function getModel() {
+  if (!model) {
+    model = await FlagEmbedding.init({
+      model: EmbeddingModel.BGESmallENV15,
+      cacheDir: CACHE_DIR,
+    });
+  }
+  return model;
+}
+
+export async function embed(text) {
+  const m = await getModel();
+  const results = [];
+  for await (const batch of m.embed([text])) {
+    results.push(...batch);
+  }
+  return Array.from(results[0]);
+}
+
+export function cosineSimilarity(a, b) {
+  let dot = 0;
+  for (let i = 0; i < a.length; i++) dot += a[i] * b[i];
+  return dot;
+}

package/index.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { search, getContext, getCallers, getCallees, getImpact, listAll } from './search.js';
+import { indexAll } from './indexer.js';
+import { startWatcher } from './watcher.js';
+import { promptConfig } from './config.js';
+
+const args = process.argv.slice(2);
+
+if (args[0] === 'init') {
+  const config = await promptConfig();
+  console.log('\nIndexing skills...');
+  await indexAll();
+  console.log('\nDone! Add to Claude Code settings.json:');
+  console.log(JSON.stringify({
+    mcpServers: {
+      promptgraph: {
+        command: 'node',
+        args: [process.argv[1]],
+      }
+    }
+  }, null, 2));
+  process.exit(0);
+}
+
+if (args[0] === 'reindex') {
+  console.log('[PromptGraph] Reindexing...');
+  await indexAll();
+  process.exit(0);
+}
+
+const server = new Server(
+  { name: 'promptgraph', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'pg_search',
+      description: 'Search skills by task description. Returns top relevant skills with scores.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'Task or topic to search for' },
+          top_k: { type: 'number', description: 'Number of results (default 5)' },
+        },
+        required: ['query'],
+      },
+    },
+    {
+      name: 'pg_list',
+      description: 'List all indexed skills.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'pg_context',
+      description: 'Get full context for a skill: description, content, callers, callees.',
+      inputSchema: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+    },
+    {
+      name: 'pg_callers',
+      description: 'Get skills that call/reference this skill.',
+      inputSchema: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+    },
+    {
+      name: 'pg_callees',
+      description: 'Get skills that this skill calls/references.',
+      inputSchema: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+    },
+    {
+      name: 'pg_impact',
+      description: 'Get all skills that would be affected if this skill changes.',
+      inputSchema: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    let result;
+    switch (name) {
+      case 'pg_search': result = await search(args.query, args.top_k || 5); break;
+      case 'pg_list': result = listAll(); break;
+      case 'pg_context': result = getContext(args.name); break;
+      case 'pg_callers': result = getCallers(args.name); break;
+      case 'pg_callees': result = getCallees(args.name); break;
+      case 'pg_impact': result = getImpact(args.name); break;
+      default: throw new Error(`Unknown tool: ${name}`);
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  } catch (e) {
+    return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
+  }
+});
+
+startWatcher();
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('[PromptGraph] MCP server running');

package/indexer.js

@@ -0,0 +1,65 @@
+import { globSync } from 'glob';
+import { parseSkillFile } from './parser.js';
+import { embed } from './embedder.js';
+import { getDb } from './db.js';
+import { loadConfig } from './config.js';
+
+export async function indexAll() {
+  const config = loadConfig();
+  const db = getDb();
+
+  const upsert = db.prepare(`
+    INSERT INTO skills (name, description, path, source, content, embedding)
+    VALUES (@name, @description, @path, @source, @content, @embedding)
+    ON CONFLICT(name) DO UPDATE SET
+      description = excluded.description,
+      path = excluded.path,
+      source = excluded.source,
+      content = excluded.content,
+      embedding = excluded.embedding
+  `);
+  const upsertEdge = db.prepare(`INSERT OR IGNORE INTO edges (from_skill, to_skill) VALUES (?, ?)`);
+  db.prepare('DELETE FROM edges').run();
+
+  let count = 0;
+  for (const { dir, source } of config.sources) {
+    const files = globSync(`${dir}/**/*.md`);
+    for (const file of files) {
+      try {
+        const skill = parseSkillFile(file, source);
+        const embedding = await embed(skill.name + ' ' + skill.description + ' ' + skill.content.slice(0, 500));
+        upsert.run({ ...skill, embedding: JSON.stringify(embedding) });
+        for (const called of skill.calls) {
+          upsertEdge.run(skill.name, called);
+        }
+        count++;
+        process.stdout.write(`\r  Indexed: ${count} skills`);
+      } catch (e) {
+        console.error(`\n  Error indexing ${file}: ${e.message}`);
+      }
+    }
+  }
+  console.log(`\n  Done. ${count} skills indexed.`);
+}
+
+export async function indexFile(filePath, source) {
+  const db = getDb();
+  const skill = parseSkillFile(filePath, source);
+  const embedding = await embed(skill.name + ' ' + skill.description + ' ' + skill.content.slice(0, 500));
+  db.prepare(`
+    INSERT INTO skills (name, description, path, source, content, embedding)
+    VALUES (@name, @description, @path, @source, @content, @embedding)
+    ON CONFLICT(name) DO UPDATE SET
+      description = excluded.description,
+      path = excluded.path,
+      source = excluded.source,
+      content = excluded.content,
+      embedding = excluded.embedding
+  `).run({ ...skill, embedding: JSON.stringify(embedding) });
+
+  db.prepare('DELETE FROM edges WHERE from_skill = ?').run(skill.name);
+  const upsertEdge = db.prepare('INSERT OR IGNORE INTO edges (from_skill, to_skill) VALUES (?, ?)');
+  for (const called of skill.calls) {
+    upsertEdge.run(skill.name, called);
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "promptgraph-mcp",
+  "version": "1.0.0",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "promptgraph": "./index.js",
+    "promptgraph-mcp": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "init": "node index.js init",
+    "reindex": "node index.js reindex"
+  },
+  "keywords": ["claude", "claude-code", "mcp", "ai", "skills", "embeddings"],
+  "author": "NeiP4n",
+  "license": "MIT",
+  "description": "Semantic skill router for Claude Code — load only the skills you need, save 20k+ tokens per session",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NeiP4n/promptgraph.git"
+  },
+  "homepage": "https://github.com/NeiP4n/promptgraph#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.10.0",
+    "chokidar": "^5.0.0",
+    "fastembed": "^2.1.0",
+    "glob": "^13.0.6",
+    "gray-matter": "^4.0.3"
+  }
+}

package/parser.js

@@ -0,0 +1,47 @@
+import fs from 'fs';
+import path from 'path';
+
+const SKILL_REF_RE = /\/([a-z0-9][a-z0-9-]+)/g;
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
+
+export function parseSkillFile(filePath, source) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+
+  let name = null;
+  let description = null;
+  let content = raw;
+
+  const fm = raw.match(FRONTMATTER_RE);
+  if (fm) {
+    try {
+      const nameMatch = fm[1].match(/^name:\s*(.+)$/m);
+      const descMatch = fm[1].match(/^description:\s*(.+)$/m);
+      if (nameMatch) name = nameMatch[1].trim().replace(/^["']|["']$/g, '');
+      if (descMatch) description = descMatch[1].trim().replace(/^["']|["']$/g, '');
+    } catch {}
+  }
+
+  name = name || path.basename(filePath, '.md');
+  description = description || extractFirstParagraph(raw);
+
+  const calls = new Set();
+  for (const match of raw.matchAll(SKILL_REF_RE)) {
+    const ref = match[1];
+    if (ref !== name && ref.length > 2) calls.add(ref);
+  }
+
+  return {
+    name,
+    description,
+    path: filePath,
+    source,
+    content: raw,
+    calls: [...calls],
+  };
+}
+
+function extractFirstParagraph(content) {
+  const lines = content.replace(FRONTMATTER_RE, '').split('\n')
+    .filter(l => l.trim() && !l.startsWith('#') && !l.startsWith('---'));
+  return lines[0]?.trim().slice(0, 200) || '';
+}

package/search.js

@@ -0,0 +1,58 @@
+import { embed, cosineSimilarity } from './embedder.js';
+import { getDb } from './db.js';
+
+export async function search(query, topK = 5) {
+  const db = getDb();
+  const queryVec = await embed(query);
+  const skills = db.prepare('SELECT name, description, path, source, embedding FROM skills').all();
+
+  return skills
+    .map(skill => ({
+      name: skill.name,
+      description: skill.description,
+      path: skill.path,
+      source: skill.source,
+      score: cosineSimilarity(queryVec, JSON.parse(skill.embedding)),
+    }))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, topK);
+}
+
+export function getContext(name) {
+  const db = getDb();
+  const skill = db.prepare('SELECT * FROM skills WHERE name = ?').get(name);
+  if (!skill) return null;
+  const callees = db.prepare('SELECT to_skill FROM edges WHERE from_skill = ?').all(name).map(r => r.to_skill);
+  const callers = db.prepare('SELECT from_skill FROM edges WHERE to_skill = ?').all(name).map(r => r.from_skill);
+  return { ...skill, embedding: undefined, callees, callers };
+}
+
+export function getCallers(name) {
+  const db = getDb();
+  return db.prepare('SELECT from_skill FROM edges WHERE to_skill = ?').all(name).map(r => r.from_skill);
+}
+
+export function getCallees(name) {
+  const db = getDb();
+  return db.prepare('SELECT to_skill FROM edges WHERE from_skill = ?').all(name).map(r => r.to_skill);
+}
+
+export function getImpact(name) {
+  const db = getDb();
+  const visited = new Set();
+  const queue = [name];
+  while (queue.length) {
+    const cur = queue.shift();
+    if (visited.has(cur)) continue;
+    visited.add(cur);
+    const callers = db.prepare('SELECT from_skill FROM edges WHERE to_skill = ?').all(cur).map(r => r.from_skill);
+    queue.push(...callers);
+  }
+  visited.delete(name);
+  return [...visited];
+}
+
+export function listAll() {
+  const db = getDb();
+  return db.prepare('SELECT name, description, source FROM skills ORDER BY name').all();
+}

package/watcher.js

@@ -0,0 +1,50 @@
+import chokidar from 'chokidar';
+import path from 'path';
+import os from 'os';
+import { indexFile } from './indexer.js';
+import { getDb } from './db.js';
+
+const SOURCES = [
+  { dir: path.join(os.homedir(), '.claude', 'skills-store'), source: 'skills-store' },
+  { dir: path.join(os.homedir(), '.claude', 'skills'), source: 'skills' },
+];
+
+export function startWatcher() {
+  const paths = SOURCES.map(s => s.dir);
+
+  const watcher = chokidar.watch(paths, {
+    ignored: /[/\\]\./,
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 500 },
+  });
+
+  watcher.on('add', filePath => reindex(filePath));
+  watcher.on('change', filePath => reindex(filePath));
+  watcher.on('unlink', filePath => {
+    const name = path.basename(filePath, '.md');
+    const db = getDb();
+    db.prepare('DELETE FROM skills WHERE name = ?').run(name);
+    db.prepare('DELETE FROM edges WHERE from_skill = ? OR to_skill = ?').run(name, name);
+    console.error(`[PromptGraph] Removed: ${name}`);
+  });
+
+  console.error('[PromptGraph] Watcher started');
+}
+
+function getSource(filePath) {
+  for (const { dir, source } of SOURCES) {
+    if (filePath.startsWith(dir)) return source;
+  }
+  return 'unknown';
+}
+
+async function reindex(filePath) {
+  if (!filePath.endsWith('.md')) return;
+  try {
+    await indexFile(filePath, getSource(filePath));
+    console.error(`[PromptGraph] Reindexed: ${path.basename(filePath)}`);
+  } catch (e) {
+    console.error(`[PromptGraph] Error reindexing ${filePath}: ${e.message}`);
+  }
+}