promptgraph-mcp 2.9.8 → 2.9.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +208 -205
  2. package/package.json +1 -1
  3. package/platform.js +6 -3
package/README.md CHANGED
@@ -1,205 +1,208 @@
1
- # PromptGraph
2
-
3
- **Semantic skill router and marketplace for Claude Code.**
4
-
5
- Instead of loading every `.md` skill into your context, Claude calls `pg_search` and loads only the one skill it needs.
6
-
7
- [![npm](https://img.shields.io/npm/v/promptgraph-mcp?color=7C3AED&label=npm)](https://www.npmjs.com/package/promptgraph-mcp)
8
- [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
9
-
10
- ---
11
-
12
- ## How it works
13
-
14
- ```
15
- pg_search("refactor without breaking tests")
16
- → embed query (BGE-Small-EN, 384-dim)
17
- → ANN index (HNSW by default, flat fallback) — topK×4 candidates
18
- → BM25 (FTS5) — topK×4 candidates
19
- → hybrid merge (embedWeight × cosine + bm25Weight × BM25)
20
- → term-overlap reranker (TF frequency + header-position boost)
21
- → return topK skill paths + snippets
22
- → Claude reads only the files it needs
23
- ```
24
-
25
- **Index:** SQLite + Float32 BLOB embeddings + HNSW approximate nearest neighbor (configurable: `PG_VECTOR_STORE=flat` for brute-force cosine). No external vector DB, no API key, no cloud.
26
-
27
- **Reranker:** lightweight term-overlap scorer (binary overlap + TF frequency + header-position boost). Not a cross-encoder — disable via `PG_RERANKER=0`.
28
-
29
- **File watcher:** `chokidar` detects `.md` changes and reindexes automatically (MCP server mode only).
30
-
31
- ---
32
-
33
- ## Benchmarks (measured on real hardware)
34
-
35
- | Operation | Result |
36
- |---|---|
37
- | 88 new skills indexed (first time, cold ONNX) | **49.5 s** |
38
- | 88 skills reindexed (unchanged, hash match) | **< 1 s** |
39
- | `pg reindex --fast` (3000 files, keyword only) | **~30 s** |
40
- | `pg reindex` full embed (3000 files) | **~30 min** |
41
- | Semantic search query (HNSW) | **< 50 ms** |
42
- | Semantic search query (flat, brute-force) | **< 200 ms** |
43
- | Model size (BGE-Small-EN-v1.5, one-time download) | **23 MB** |
44
- | Embedding dimensions | **384** |
45
- | Max chunks per skill | **8** (configurable: `PG_MAX_CHUNKS`) |
46
- | Embedding batch size | **256** |
47
-
48
- > ONNX model initialization (~2–3 min) happens once on first use and is cached in `~/.claude/.promptgraph/model-cache/`.
49
-
50
- ---
51
-
52
- ## Environment Variables
53
-
54
- | Variable | Default | Description |
55
- |---|---|---|
56
- | `PG_VECTOR_STORE` | `hnsw` | Vector index: `hnsw` (ANN, faster at scale) or `flat` (brute-force cosine) |
57
- | `PG_RERANKER` | `1` | Enable term-overlap reranker after hybrid search (set `0` to disable) |
58
- | `PG_MAX_CHUNKS` | `8` | Max semantic chunks per skill (higher = more detail per long file, more embedding cost) |
59
-
60
- ---
61
-
62
- ## Quick Start
63
-
64
- ```bash
65
- npm install -g promptgraph-mcp@latest
66
- pg init
67
- ```
68
-
69
- `pg init` downloads the model (~23 MB, once), indexes your local skills, and prints the config snippet.
70
-
71
- ### Claude Code (`~/.claude/settings.json`)
72
-
73
- ```json
74
- {
75
- "mcpServers": {
76
- "promptgraph": {
77
- "command": "npx",
78
- "args": ["promptgraph-mcp"]
79
- }
80
- }
81
- }
82
- ```
83
-
84
- ### Claude Desktop / Cursor / Windsurf / Cline
85
-
86
- Same config — any MCP-compatible client works.
87
-
88
- ### OpenCode (`~/.config/opencode/opencode.json`)
89
-
90
- ```json
91
- {
92
- "mcp": {
93
- "promptgraph": {
94
- "type": "local",
95
- "command": ["npx", "promptgraph-mcp"],
96
- "enabled": true
97
- }
98
- }
99
- }
100
- ```
101
-
102
- > `pg setup` auto-detects installed clients and writes config automatically.
103
-
104
- ---
105
-
106
- ## CLI
107
-
108
- ```bash
109
- pg init # first-time setup
110
- pg status # show indexed sources, repos, installed bundles
111
- pg reindex # full reindex (semantic search, slow)
112
- pg reindex --fast # keyword-only reindex (~30s, no embeddings)
113
- pg search "deploy" # search from terminal
114
- pg import owner/repo # clone and index any GitHub repo of .md skills
115
- pg marketplace # browse skills by category
116
- pg marketplace bundles # browse curated bundles
117
- pg bundle install <id> # install a bundle
118
- pg validate my-skill.md # validate before publishing
119
- pg doctor # clean orphaned DB rows
120
- pg update # update to latest version
121
- ```
122
-
123
- ---
124
-
125
- ## Marketplace
126
-
127
- ```bash
128
- pg marketplace # 🛠 Engineering 💻 Coding 🤖 AI Tools 🔒 Security 🎨 Creative
129
- pg marketplace Engineering # filter by category
130
- pg marketplace bundles # install whole repos as skill bundles
131
- ```
132
-
133
- **Bundles** install an entire GitHub repo as a skill source — auto-detects `skills/`, `commands/`, `prompts/` subdirectory.
134
-
135
- Example:
136
- ```bash
137
- pg bundle install elementalsouls-claude-bughunter # 88 security skills from GitHub
138
- pg bundle install engineering-essentials # 4 curated workflow skills
139
- ```
140
-
141
- **Publish your skill** (auto-validated, no manual review):
142
-
143
- Open an issue on [promptgraph-registry](https://github.com/NeiP4n/promptgraph-registry) with label `skill-submission`. The bot fetches, validates, commits, and closes the issue automatically.
144
-
145
- Anti-spam checks: min 200 chars, 2+ headers, code/bullets required, prompt injection detection, duplicate URL/description check, 3 submissions per user per 24h.
146
-
147
- ---
148
-
149
- ## MCP Tools
150
-
151
- Claude uses these automatically when the MCP server is running:
152
-
153
- | Tool | What it does |
154
- |---|---|
155
- | `pg_search` | Semantic search by task description |
156
- | `pg_list` | List all indexed skills |
157
- | `pg_context` | Full skill details + callers/callees |
158
- | `pg_callers` | Which skills reference this one |
159
- | `pg_callees` | Which skills this one calls |
160
- | `pg_impact` | What breaks if this skill changes |
161
- | `pg_marketplace_browse` | Browse community registry |
162
- | `pg_marketplace_install` | Install a skill by code or name |
163
- | `pg_bundle_browse` | Browse skill bundles |
164
- | `pg_bundle_install` | Install a bundle |
165
- | `pg_top_rated` | Highest-rated skills |
166
- | `pg_rate` | Rate a skill after use |
167
-
168
- ---
169
-
170
- ## Search modes
171
-
172
- Search runs a multi-stage pipeline:
173
-
174
- 1. **ANN retrieval** — HNSW approximate nearest neighbor (default) or flat brute-force cosine (`PG_VECTOR_STORE=flat`)
175
- 2. **BM25 keyword** — SQLite FTS5
176
- 3. **Hybrid fusion** — weighted sum (embedding × embedWeight + BM25 × bm25Weight, adaptive per query)
177
- 4. **Reranker** — term-overlap rescoring with TF frequency and header-position boost (disable via `PG_RERANKER=0`)
178
- 5. **Rating boost** — success/fail history adjusts final ranking
179
-
180
- Falls back to FTS5 only if no embeddings exist.
181
-
182
- ---
183
-
184
- ## Skill filtering
185
-
186
- When importing a GitHub repo, PromptGraph:
187
- 1. Looks for a dedicated subdir (`skills/`, `commands/`, `prompts/`, `agents/`, `templates/`, etc.) — indexes only that dir if found with 2+ `.md` files
188
- 2. Falls back to repo root with content quality filter: min 150 chars, 2+ headers, must have code blocks or bullet points, skips readme/changelog/license/docs
189
-
190
- ---
191
-
192
- ## Requirements
193
-
194
- - Node.js 18+
195
- - Any MCP-compatible client (Claude Code, Claude Desktop, Cline, OpenCode, Cursor, Windsurf…)
196
-
197
- ---
198
-
199
- ## Related
200
-
201
- - 📋 [promptgraph-registry](https://github.com/NeiP4n/promptgraph-registry) — community skill registry and auto-publish bot
202
-
203
- ---
204
-
205
- *Built with [Claude Code](https://claude.com/claude-code).*
1
+ # PromptGraph
2
+
3
+ **Semantic skill router and marketplace for Claude Code and OpenCode.**
4
+
5
+ Instead of loading every `.md` skill into context, Claude calls `pg_search` and loads only the skill it needs — saving 20k+ tokens per session.
6
+
7
+ [![npm](https://img.shields.io/npm/v/promptgraph-mcp?color=7C3AED&label=npm)](https://www.npmjs.com/package/promptgraph-mcp)
8
+ [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
9
+
10
+ ---
11
+
12
+ ## Quick Start
13
+
14
+ ```bash
15
+ npm install -g promptgraph-mcp@latest
16
+ pg init
17
+ ```
18
+
19
+ `pg init` auto-detects your installed editor, downloads the embedding model (~23 MB, once), indexes your skills, and writes the config automatically.
20
+
21
+ ---
22
+
23
+ ## Setup
24
+
25
+ ### Claude Code
26
+
27
+ **Option 1 — auto (recommended):**
28
+ ```bash
29
+ pg init
30
+ # or
31
+ pg setup claude-code
32
+ ```
33
+
34
+ **Option 2 — manual.** Add to `~/.claude/settings.json`:
35
+ ```json
36
+ {
37
+ "mcpServers": {
38
+ "promptgraph": {
39
+ "command": "npx",
40
+ "args": ["promptgraph-mcp"]
41
+ }
42
+ }
43
+ }
44
+ ```
45
+
46
+ **Option 3 — official plugin:**
47
+ ```
48
+ /plugin install promptgraph@claude-community
49
+ ```
50
+
51
+ ### OpenCode
52
+
53
+ **Option 1 — auto (recommended):**
54
+ ```bash
55
+ pg init
56
+ # or
57
+ pg setup opencode
58
+ ```
59
+
60
+ **Option 2 — manual.** Add to `~/.config/opencode/opencode.json`:
61
+ ```json
62
+ {
63
+ "plugin": ["promptgraph-mcp/plugin"]
64
+ }
65
+ ```
66
+
67
+ ### Other clients
68
+
69
+ | Client | Command |
70
+ |---|---|
71
+ | Claude Desktop | `pg setup claude-desktop` |
72
+ | Cursor | `pg setup cursor` |
73
+ | Windsurf | `pg setup windsurf` |
74
+ | Cline | `pg setup cline` |
75
+ | OpenAI Codex CLI | `pg setup codex` |
76
+
77
+ ---
78
+
79
+ ## Install skill bundles
80
+
81
+ ```bash
82
+ pg install engineering-best-practices
83
+ pg install pg-000001
84
+ pg install "LLM Prompts"
85
+ ```
86
+
87
+ Or browse interactively:
88
+ ```bash
89
+ pg marketplace
90
+ ```
91
+
92
+ ---
93
+
94
+ ## CLI
95
+
96
+ ```bash
97
+ pg init # first-time setup (auto-detects editor)
98
+ pg setup <platform> # register MCP in a specific editor
99
+ pg install <name> # install a bundle by name, code, or id
100
+ pg marketplace # browse + search + install (interactive TUI)
101
+ pg status # show indexed sources, repos, installed bundles
102
+ pg reindex # full reindex (semantic + keyword)
103
+ pg reindex --fast # keyword-only reindex (~30 s)
104
+ pg search "deploy" # search from terminal
105
+ pg import owner/repo # import any GitHub repo of .md skills
106
+ pg bundle update # update all installed bundles
107
+ pg validate my-skill.md # validate before publishing
108
+ pg doctor # clean orphaned DB rows
109
+ pg update # update to latest version
110
+ ```
111
+
112
+ ---
113
+
114
+ ## How it works
115
+
116
+ ```
117
+ pg_search("refactor without breaking tests")
118
+ → embed query (BGE-Small-EN, 384-dim)
119
+ → HNSW ANN index — topK×4 candidates
120
+ → BM25 FTS5 — topK×4 candidates
121
+ → hybrid merge (cosine + BM25, adaptive weights)
122
+ → term-overlap reranker (TF + header-position boost)
123
+ → return topK skill paths + snippets
124
+ → Claude reads only the files it needs
125
+ ```
126
+
127
+ **Index:** SQLite + Float32 BLOB embeddings + HNSW. No external vector DB, no API key, no cloud.
128
+
129
+ ---
130
+
131
+ ## Marketplace
132
+
133
+ ```bash
134
+ pg marketplace # 🛠 Engineering 💻 Coding 🤖 AI 🔒 Security 🎨 Creative
135
+ pg marketplace bundles # curated GitHub repos as skill bundles
136
+ ```
137
+
138
+ **Bundles** clone a GitHub repo and index only the skill files — auto-detects `skills/`, `commands/`, `prompts/` subdirectory.
139
+
140
+ **Publish your skill** — open an issue on [promptgraph-registry](https://github.com/NeiP4n/promptgraph-registry) with label `skill-submission`. The bot validates, commits, and closes automatically.
141
+
142
+ ---
143
+
144
+ ## MCP Tools
145
+
146
+ Claude uses these automatically when the server is running:
147
+
148
+ | Tool | Description |
149
+ |---|---|
150
+ | `pg_search` | Semantic search by task description |
151
+ | `pg_list` | List all indexed skills |
152
+ | `pg_context` | Full skill details + callers/callees |
153
+ | `pg_callers` | Which skills reference this one |
154
+ | `pg_callees` | Which skills this one calls |
155
+ | `pg_impact` | What breaks if this skill changes |
156
+ | `pg_marketplace_browse` | Browse community registry |
157
+ | `pg_marketplace_install` | Install a skill by code or name |
158
+ | `pg_bundle_browse` | Browse skill bundles |
159
+ | `pg_bundle_install` | Install a bundle |
160
+ | `pg_top_rated` | Highest-rated skills |
161
+ | `pg_rate` | Rate a skill after use |
162
+
163
+ ---
164
+
165
+ ## Environment Variables
166
+
167
+ | Variable | Default | Description |
168
+ |---|---|---|
169
+ | `PG_VECTOR_STORE` | `hnsw` | `hnsw` (ANN) or `flat` (brute-force cosine) |
170
+ | `PG_RERANKER` | `1` | Term-overlap reranker — set `0` to disable |
171
+ | `PG_MAX_CHUNKS` | `8` | Max semantic chunks per skill file |
172
+
173
+ ---
174
+
175
+ ## Skill filtering
176
+
177
+ When importing a GitHub repo, PromptGraph:
178
+ 1. Looks for a dedicated subdir (`skills/`, `commands/`, `prompts/`, `agents/`, etc.) — indexes only that if found
179
+ 2. Falls back to repo root with a content quality filter: min 150 chars, 2+ headers, code blocks or bullets required, skips readme/changelog/license
180
+
181
+ ---
182
+
183
+ ## Benchmarks
184
+
185
+ | Operation | Result |
186
+ |---|---|
187
+ | 88 new skills (cold ONNX) | **49.5 s** |
188
+ | 88 skills (unchanged, hash match) | **< 1 s** |
189
+ | `pg reindex --fast` (3000 files) | **~30 s** |
190
+ | Semantic search (HNSW) | **< 50 ms** |
191
+ | Model size (BGE-Small-EN-v1.5, one-time) | **23 MB** |
192
+
193
+ ---
194
+
195
+ ## Requirements
196
+
197
+ - Node.js 18+
198
+ - Claude Code, OpenCode, Cursor, Windsurf, Cline, or any MCP-compatible client
199
+
200
+ ---
201
+
202
+ ## Related
203
+
204
+ - 📋 [promptgraph-registry](https://github.com/NeiP4n/promptgraph-registry) — community skill registry
205
+
206
+ ---
207
+
208
+ *Built with [Claude Code](https://claude.com/claude-code).*
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "promptgraph-mcp",
3
- "version": "2.9.8",
3
+ "version": "2.9.9",
4
4
  "files": [
5
5
  "*.js",
6
6
  "commands/",
package/platform.js CHANGED
@@ -88,12 +88,15 @@ export function detectPlatforms() {
88
88
 
89
89
  function isBinaryInstalled(bin) {
90
90
  try {
91
- const r = spawnSync(bin, ['--version'], { encoding: 'utf8', timeout: 3000, stdio: 'pipe' });
92
- return r.status === 0;
91
+ const cmd = process.platform === 'win32' ? 'where' : 'which';
92
+ const r = spawnSync(cmd, [bin], { encoding: 'utf8', timeout: 3000, stdio: 'pipe' });
93
+ return r.status === 0 && r.stdout.trim().length > 0;
93
94
  } catch { return false; }
94
95
  }
95
96
 
96
- function isOpenCodeInstalled() { return isBinaryInstalled('opencode'); }
97
+ function isOpenCodeInstalled() {
98
+ return isBinaryInstalled('opencode') || isBinaryInstalled('OpenCode');
99
+ }
97
100
  function isClaudeCodeInstalled() { return isBinaryInstalled('claude'); }
98
101
 
99
102
  function getOpenCodeConfig() {