promptgraph-mcp 1.5.21 → 1.5.23

package/README.md

@@ -1,160 +1,170 @@
-# 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 → returns the path. Claude then reads only that file instead of having all skills preloaded in context.
-
-## 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-mcp init
-```
-
-### From source
-
-```bash
-git clone https://github.com/NeiP4n/promptgraph
-cd promptgraph
-npm install
-npm link
-promptgraph-mcp 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-mcp"]
-    }
-  }
-}
-```
-
-### 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-mcp init      # First-time setup (interactive)
-promptgraph-mcp 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 |
-
-> **Search:** Uses HNSW index (via [vectra](https://github.com/Stevenic/vectra)) for O(log N) approximate nearest neighbor search. Falls back to brute-force on first run before index is built.
-
-## 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*
+# 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 dumps every file in `~/.claude/commands/` into the system prompt — every session, every message. At 40+ skills that's **20,000–50,000 wasted tokens before you say a word.**
+
+PromptGraph replaces that with one tiny router skill (`~150 tokens`) and a local vector index. When you ask something, Claude calls `pg_search` → gets the right skill path → reads only that file.
+
+```
+Before:  all 40 skills loaded  →  ~40,000 tokens wasted
+After:   1 router + 1 match    →  ~300 tokens total
+```
+
+---
+
+## 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, 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"]
+    }
+  }
+}
+```
+
+### 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/config.js

@@ -42,7 +42,12 @@ export async function promptConfig() {
   if (extra.trim()) {
     const extraDirs = extra.split(',').map(d => d.trim()).filter(Boolean);
     for (const dir of extraDirs) {
-      config.sources.push({ dir, source: 'custom' });
+      // Use basename so two different dirs named the same still get distinct ids
+      // if basename truly collides, append a short discriminator from the full path
+      const base = path.basename(path.resolve(dir));
+      const existing = config.sources.filter(s => s.source === `custom:${base}`);
+      const tag = existing.length === 0 ? `custom:${base}` : `custom:${base}-${existing.length}`;
+      config.sources.push({ dir, source: tag });
     }
   }
 

package/github-import.js

@@ -1,4 +1,4 @@
-import { execSync } from 'child_process';
+import { spawnSync } from 'child_process';
 import path from 'path';
 import os from 'os';
 import fs from 'fs';
@@ -22,13 +22,12 @@ export async function importFromGitHub(repoUrl) {
 
   if (fs.existsSync(dest)) {
     console.log(`Updating ${repoName}...`);
-    execSync('git', { stdio: 'inherit', args: ['-C', dest, 'pull', '--depth=1'] });
+    const pullResult = spawnSync('git', ['-C', dest, 'pull', '--depth=1'], { stdio: 'inherit' });
+    if (pullResult.status !== 0) throw new Error(`git pull failed for ${repoName}`);
   } else {
     console.log(`Cloning ${url}...`);
-    // use spawnSync to avoid shell injection
-    const { spawnSync } = await import('child_process');
-    const result = spawnSync('git', ['clone', '--depth=1', url, dest], { stdio: 'inherit' });
-    if (result.status !== 0) throw new Error(`git clone failed for ${url}`);
+    const cloneResult = spawnSync('git', ['clone', '--depth=1', url, dest], { stdio: 'inherit' });
+    if (cloneResult.status !== 0) throw new Error(`git clone failed for ${url}`);
   }
 
   const mdFiles = globSync(`${dest}/**/*.md`);
@@ -39,11 +38,12 @@ export async function importFromGitHub(repoUrl) {
   }
 
   const config = loadConfig();
-  const githubDir = path.join(SKILLS_DIR, 'github');
-  if (!config.sources.find(s => s.dir === githubDir)) {
-    config.sources.push({ dir: githubDir, source: 'github' });
+  // Per-repo source so two repos with the same skill name don't overwrite each other
+  const repoSource = `github:${repoName}`;
+  if (!config.sources.find(s => s.dir === dest)) {
+    config.sources.push({ dir: dest, source: repoSource });
     saveConfig(config);
-    console.log('Added github dir to config');
+    console.log(`Added ${repoSource} to config`);
   }
 
   console.log('\nReindexing...');

package/indexer.js

@@ -77,11 +77,24 @@ export async function indexAll() {
   const config = loadConfig();
   const db = getDb();
 
-  // collect all files on disk
+  // collect all files on disk — use longest-matching source for files in subdirs
+  // (e.g. skills-store/marketplace/*.md → 'marketplace', not 'skills-store')
+  const normalizedSources = config.sources.map(s => ({
+    ...s,
+    normDir: path.resolve(s.dir),
+  })).sort((a, b) => b.normDir.length - a.normDir.length); // longest first
+
+  const seenFiles = new Set();
   const allFiles = [];
-  for (const { dir, source } of config.sources) {
+  for (const { dir, source } of normalizedSources) {
     const files = globSync(`${dir}/**/*.md`);
-    files.forEach(f => allFiles.push({ file: f, source }));
+    for (const f of files) {
+      const norm = path.resolve(f);
+      if (!seenFiles.has(norm)) {
+        seenFiles.add(norm);
+        allFiles.push({ file: f, source });
+      }
+    }
   }
   const total = allFiles.length;
   info(`Found ${chalk.white.bold(total)} files`);
@@ -149,6 +162,16 @@ export async function indexAll() {
       }
     } catch {
       errors++;
+      // Remove stale record if the file was previously indexed but now fails to parse
+      try {
+        const stale = db.prepare('SELECT id FROM skills WHERE path = ?').get(file);
+        if (stale) {
+          db.prepare('DELETE FROM skills WHERE id = ?').run(stale.id);
+          db.prepare('DELETE FROM chunks WHERE skill_id = ?').run(stale.id);
+          db.prepare('DELETE FROM edges WHERE from_skill = ? OR to_skill = ?').run(stale.id, stale.id);
+          db.prepare('DELETE FROM ratings WHERE skill_id = ?').run(stale.id);
+        }
+      } catch {}
     }
   }
 

package/marketplace.js

@@ -6,6 +6,7 @@ import { createHash } from 'crypto';
 import { spawnSync } from 'child_process';
 import { getDb } from './db.js';
 import { validateSkill } from './validator.js';
+import { loadConfig, saveConfig } from './config.js';
 
 const REGISTRY_URL = 'https://raw.githubusercontent.com/NeiP4n/promptgraph-registry/main/registry.json';
 const SKILLS_DIR = path.join(os.homedir(), '.claude', 'skills-store', 'marketplace');
@@ -112,10 +113,20 @@ export async function installSkill(query) {
     const skillId = skill.id;
 
     fs.mkdirSync(SKILLS_DIR, { recursive: true });
+    ensureMarketplaceSource();
     const dest = path.join(SKILLS_DIR, `${skillId}.md`);
 
     const content = await fetchText(skill.raw_url);
-    fs.writeFileSync(dest, content);
+
+    // Validate before writing — reject malicious or junk downloads
+    const tmpPath = dest + '.tmp';
+    fs.writeFileSync(tmpPath, content);
+    const validation = validateSkill(tmpPath);
+    if (!validation.ok) {
+      fs.unlinkSync(tmpPath);
+      return { error: 'Downloaded skill failed validation', issues: validation.errors };
+    }
+    fs.renameSync(tmpPath, dest);
 
     return { success: true, path: dest, name: skill.name };
   } catch (e) {
@@ -137,6 +148,16 @@ export async function browseBundles(topK = 20) {
   }
 }
 
+// Ensure marketplace has its own source entry (separate from skills-store)
+// so marketplace skills never collide with local skills of the same name.
+function ensureMarketplaceSource() {
+  const config = loadConfig();
+  if (!config.sources.find(s => s.source === 'marketplace')) {
+    config.sources.push({ dir: SKILLS_DIR, source: 'marketplace' });
+    saveConfig(config);
+  }
+}
+
 export async function installBundle(bundleId) {
   try {
     const text = await fetchText(REGISTRY_URL);
@@ -148,6 +169,7 @@ export async function installBundle(bundleId) {
     if (!bundle) return { error: `No bundle matching "${bundleId}"` };
 
     fs.mkdirSync(SKILLS_DIR, { recursive: true });
+    ensureMarketplaceSource();
     const installed = [];
     const failed = [];
 
@@ -156,7 +178,12 @@ export async function installBundle(bundleId) {
       if (!skill?.raw_url) { failed.push(skillId); continue; }
       try {
         const content = await fetchText(skill.raw_url);
-        fs.writeFileSync(path.join(SKILLS_DIR, `${skillId}.md`), content);
+        const dest = path.join(SKILLS_DIR, `${skillId}.md`);
+        const tmpPath = dest + '.tmp';
+        fs.writeFileSync(tmpPath, content);
+        const validation = validateSkill(tmpPath);
+        if (!validation.ok) { fs.unlinkSync(tmpPath); failed.push(skillId); continue; }
+        fs.renameSync(tmpPath, dest);
         installed.push(skillId);
       } catch {
         failed.push(skillId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptgraph-mcp",
-  "version": "1.5.21",
+  "version": "1.5.23",
   "main": "index.js",
   "type": "module",
   "bin": {

package/search.js

@@ -54,44 +54,53 @@ export async function search(query, topK = 5) {
     .filter(Boolean);
 }
 
-export function getContext(id) {
+export function getContext(nameOrId) {
   const db = getDb();
-  const skill = db.prepare('SELECT * FROM skills WHERE id = ?').get(id)
-    || db.prepare('SELECT * FROM skills WHERE name = ? ORDER BY id LIMIT 1').get(id);
+  let skill = db.prepare('SELECT * FROM skills WHERE id = ?').get(nameOrId);
+  if (!skill) {
+    const res = resolveId(db, nameOrId);
+    if (res.error) return res;
+    skill = db.prepare('SELECT * FROM skills WHERE id = ?').get(res.id);
+  }
   if (!skill) return null;
   const callees = db.prepare('SELECT to_skill FROM edges WHERE from_skill = ?').all(skill.id).map(r => r.to_skill);
   const callers = db.prepare('SELECT from_skill FROM edges WHERE to_skill = ?').all(skill.id).map(r => r.from_skill);
+
   return { ...skill, callees, callers };
 }
 
 function resolveId(db, nameOrId) {
   const byId = db.prepare('SELECT id FROM skills WHERE id = ?').get(nameOrId);
-  if (byId) return byId.id;
-  const byName = db.prepare('SELECT id FROM skills WHERE name = ? ORDER BY id LIMIT 1').get(nameOrId);
-  if (byName) return byName.id;
-  return null;
+  if (byId) return { id: byId.id };
+  const byName = db.prepare('SELECT id FROM skills WHERE name = ?').all(nameOrId);
+  if (byName.length === 1) return { id: byName[0].id };
+  if (byName.length > 1) {
+    const candidates = byName.map(r => r.id).join(', ');
+    return { error: `Ambiguous name "${nameOrId}" — multiple skills match. Use a full id: ${candidates}` };
+  }
+  return { error: `Skill not found: ${nameOrId}` };
 }
 
 export function getCallers(nameOrId) {
   const db = getDb();
-  const id = resolveId(db, nameOrId);
-  if (!id) return { error: `Skill not found: ${nameOrId}` };
-  return db.prepare('SELECT from_skill FROM edges WHERE to_skill = ?').all(id).map(r => r.from_skill);
+  const res = resolveId(db, nameOrId);
+  if (res.error) return res;
+  return db.prepare('SELECT from_skill FROM edges WHERE to_skill = ?').all(res.id).map(r => r.from_skill);
 }
 
 export function getCallees(nameOrId) {
   const db = getDb();
-  const id = resolveId(db, nameOrId);
-  if (!id) return { error: `Skill not found: ${nameOrId}` };
-  return db.prepare('SELECT to_skill FROM edges WHERE from_skill = ?').all(id).map(r => r.to_skill);
+  const res = resolveId(db, nameOrId);
+  if (res.error) return res;
+  return db.prepare('SELECT to_skill FROM edges WHERE from_skill = ?').all(res.id).map(r => r.to_skill);
 }
 
 export function getImpact(nameOrId) {
   const db = getDb();
-  const id = resolveId(db, nameOrId);
-  if (!id) return { error: `Skill not found: ${nameOrId}` };
+  const res = resolveId(db, nameOrId);
+  if (res.error) return res;
   const visited = new Set();
-  const queue = [id];
+  const queue = [res.id];
   while (queue.length) {
     const cur = queue.shift();
     if (visited.has(cur)) continue;