@neurynae/toolcairn-mcp 0.10.21 → 0.10.24

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 +185 -85
  2. package/dist/index.js +115 -118
  3. package/package.json +7 -2
package/README.md CHANGED
@@ -1,20 +1,47 @@
1
- # @neurynae/toolcairn-mcp
1
+ <p align="center">
2
+ <a href="https://toolcairn.neurynae.com">
3
+ <img src="https://raw.githubusercontent.com/neurynae/toolcairn-mcp/main/assets/hero.png" alt="ToolCairn — Tool intelligence for AI coding agents" width="100%">
4
+ </a>
5
+ </p>
2
6
 
3
- **Find the right open source tool, every time.**
7
+ <p align="center">
8
+ <a href="https://www.npmjs.com/package/@neurynae/toolcairn-mcp"><img src="https://img.shields.io/npm/v/@neurynae/toolcairn-mcp" alt="npm version"></a>
9
+ <a href="https://www.npmjs.com/package/@neurynae/toolcairn-mcp"><img src="https://img.shields.io/npm/dm/@neurynae/toolcairn-mcp" alt="npm downloads"></a>
10
+ <a href="https://github.com/neurynae/toolcairn-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
11
+ <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen" alt="Node.js"></a>
12
+ </p>
4
13
 
5
- [![npm version](https://img.shields.io/npm/v/@neurynae/toolcairn-mcp)](https://www.npmjs.com/package/@neurynae/toolcairn-mcp)
6
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/NEURYNAE/ToolCairn/blob/main/LICENSE)
7
- [![npm downloads](https://img.shields.io/npm/dm/@neurynae/toolcairn-mcp)](https://www.npmjs.com/package/@neurynae/toolcairn-mcp)
14
+ # `@neurynae/toolcairn-mcp`
8
15
 
9
- ToolCairn is an MCP server that helps AI agents and developers discover, compare, and evaluate open source tools. Search across 12,000+ indexed tools with natural language, get stack recommendations, check compatibility, and more — all directly from your AI agent.
16
+ ToolCairn is an MCP server that connects your AI coding agent to a continuously-updated graph of **30,000+ open-source tools** across npm, PyPI, Cargo, Maven, Go, Composer, RubyGems, NuGet, Homebrew, and **35+ more registries**. Search, compare, build stacks, and check version compatibility — all from inside Claude Code, Cursor, or any MCP-compatible client.
17
+
18
+ > **Concrete example.** Your agent receives *"I need a fast HTTP client for Node"* → it calls `search_tools` → ToolCairn returns ranked candidates with maintenance and community signals, alternatives, and a warning if the top pick has questionable activity. No more guessing from blog posts and stale tutorials.
19
+
20
+ <p align="center">
21
+ <img src="https://raw.githubusercontent.com/neurynae/toolcairn-mcp/main/assets/architecture.png" alt="How it connects: Your AI Agent ↔ toolcairn-mcp ↔ ToolCairn Cloud" width="100%">
22
+ </p>
23
+
24
+ The MCP server runs locally as a stdio child of your agent. Tool calls travel over MCP to this package, which proxies the network-bound ones to the ToolCairn Cloud API and handles the local-only ones (project scan, config, audit log) on disk.
25
+
26
+ ---
27
+
28
+ ## Why ToolCairn?
29
+
30
+ Plain web search and LLM training data are insufficient for tool selection — knowledge cutoffs miss latest releases, search engines surface tutorials over authoritative ranking, and version-compatibility answers live in scattered issue threads.
31
+
32
+ ToolCairn fixes this with three things you can't get from raw registry APIs:
33
+
34
+ - **Graph-aware ranking** — recommendations consider how tools relate to each other (dependencies, integrations, replacements, conflicts), not just popularity.
35
+ - **Version-aware compatibility** — declared peer ranges and cross-registry version metadata give you *"Next.js 14 needs React 18.x"* instead of *"they're both popular, probably fine?"*
36
+ - **A continuous learning loop** — every accepted, rejected, or replaced recommendation feeds back into the graph, so quality improves with use.
10
37
 
11
38
  ---
12
39
 
13
40
  ## Quick Start
14
41
 
15
- **Step 1** — Create a free account at **https://toolcairn.neurynae.com/signup**
42
+ **Step 1.** Create a free account at **[toolcairn.neurynae.com/signup](https://toolcairn.neurynae.com/signup)**.
16
43
 
17
- **Step 2** — Add to your MCP config and restart your agent:
44
+ **Step 2.** Add to your MCP config and restart your agent:
18
45
 
19
46
  ```json
20
47
  {
@@ -27,125 +54,198 @@ ToolCairn is an MCP server that helps AI agents and developers discover, compare
27
54
  }
28
55
  ```
29
56
 
30
- On first start, a browser window opens automatically for sign-in. Once you confirm, your agent is ready to use all tools — no further setup needed.
57
+ **Step 3.** A browser window opens for sign-in on first start. Once you confirm, all tools are available immediately — no further setup.
58
+
59
+ Requires **Node.js 22+**.
31
60
 
32
61
  ---
33
62
 
34
- ## Setup by Client
63
+ ## Setup — Claude Code
35
64
 
36
- ### Claude Code
65
+ The fastest path:
37
66
 
38
67
  ```bash
39
68
  claude mcp add toolcairn -- npx @neurynae/toolcairn-mcp
40
69
  ```
41
70
 
42
- Or add to `~/.claude/claude_desktop_config.json`:
71
+ Or paste the JSON block above into `~/.claude/claude_desktop_config.json` under `mcpServers`.
43
72
 
44
- ```json
45
- {
46
- "mcpServers": {
47
- "toolcairn": {
48
- "command": "npx",
49
- "args": ["@neurynae/toolcairn-mcp"]
50
- }
51
- }
52
- }
53
- ```
73
+ > Other MCP-compatible clients (Cursor, Claude Desktop, VS Code Copilot, Windsurf, Zed, …) work with the same `npx @neurynae/toolcairn-mcp` command — see the [docs](https://toolcairn.neurynae.com/docs) for client-specific config locations.
54
74
 
55
- ### Cursor
75
+ ---
56
76
 
57
- Open **Settings → MCP** and add:
77
+ ## What you can do
58
78
 
59
- ```json
60
- {
61
- "mcpServers": {
62
- "toolcairn": {
63
- "command": "npx",
64
- "args": ["@neurynae/toolcairn-mcp"]
65
- }
66
- }
67
- }
68
- ```
79
+ ### Find a tool
80
+ Your agent receives *"I need a real-time analytics database for event tracking"* → calls `search_tools` → gets ranked candidates (ClickHouse, TimescaleDB, InfluxDB, …) with maintenance signals. If the intent is ambiguous, the response carries clarification questions; the agent answers via `search_tools_respond` and gets refined results.
69
81
 
70
- ### VS Code (Copilot)
82
+ ### Build a stack
83
+ Your agent receives *"Help me architect a full-stack TypeScript SaaS"* → calls `refine_requirement` to decompose, then `get_stack` with the per-layer needs → gets a 3–5 tool stack (web framework + database + auth + payments) with a **version-compatibility matrix** showing which versions work together across the stack.
71
84
 
72
- ```json
73
- {
74
- "github.copilot.chat.mcp.servers": {
75
- "toolcairn": {
76
- "command": "npx",
77
- "args": ["@neurynae/toolcairn-mcp"],
78
- "type": "stdio"
79
- }
80
- }
81
- }
82
- ```
85
+ ### Compare options
86
+ *"Express vs Fastify for a REST API?"* → `compare_tools` returns side-by-side health (stars, maintenance score, last commit, open issues, contributor trends), graph relationships (what each integrates with, what they replace), and a recommendation grounded in your stated use case.
83
87
 
84
- ### Windsurf
88
+ ### Check version compatibility
89
+ *"I want to upgrade Next.js to 14 but keep React 17."* → `check_compatibility` evaluates declared peer ranges and returns satisfied/unsatisfied checks with the source (`declared_dependency` / `graph_edges` / `shared_neighbors`).
85
90
 
86
- ```json
87
- {
88
- "mcpServers": {
89
- "toolcairn": {
90
- "command": "npx",
91
- "args": ["@neurynae/toolcairn-mcp"]
92
- }
93
- }
94
- }
95
- ```
91
+ ### Track project tools
92
+ On first session, `toolcairn_init` walks your repo, parses every manifest (`package.json`, `requirements.txt`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `Gemfile`, `composer.json`, …), classifies each tool against the ToolCairn graph, and writes a local `.toolcairn/` snapshot. Subsequent sessions read this snapshot first — your agent stops re-searching for things it already knows about.
96
93
 
97
94
  ---
98
95
 
99
96
  ## Available Tools
100
97
 
98
+ The MCP server exposes 15 tools, grouped by purpose. Most are local (no network) or fire-and-forget; the search, compare, and stack tools call the ToolCairn API.
99
+
100
+ ### Discovery
101
+
101
102
  | Tool | What it does |
102
- |------|-------------|
103
- | `search_tools` | Search for the best tool for a specific need using natural language |
104
- | `search_tools_respond` | Answer follow-up questions to refine search results |
105
- | `get_stack` | Get a curated tool stack recommendation for a project |
106
- | `compare_tools` | Compare two tools side by side |
107
- | `check_compatibility` | Check if two tools are known to work together |
108
- | `check_issue` | Look up known issues for a tool before spending time debugging |
109
- | `report_outcome` | Report whether a recommended tool worked out |
110
- | `refine_requirement` | Turn a vague requirement into a specific, searchable need |
111
- | `verify_suggestion` | Validate a tool your agent suggested |
112
- | `suggest_graph_update` | Suggest a new tool or relationship to add |
113
- | `toolcairn_init` | Set up ToolCairn for the current project |
114
- | `init_project_config` | Initialize project tool configuration |
115
- | `read_project_config` | Read and validate existing project config |
116
- | `update_project_config` | Add or remove tools from project config |
117
- | `toolcairn_auth` | Check sign-in status or sign out |
103
+ |---|---|
104
+ | `search_tools` | Natural-language search with health signals and alternatives. May ask clarifying questions when intent is ambiguous. |
105
+ | `search_tools_respond` | Submit answers to refine an in-progress search. |
106
+ | `refine_requirement` | Decompose a vague use-case ("build a SaaS") into specific, searchable sub-needs. |
107
+ | `verify_suggestion` | Check whether the agent's tool picks are actually indexed in the ToolCairn graph. |
108
+
109
+ ### Stacks & Compatibility
110
+
111
+ | Tool | What it does |
112
+ |---|---|
113
+ | `get_stack` | Compose a complementary tool stack with a cross-version compatibility matrix. |
114
+ | `compare_tools` | Head-to-head: health metrics, graph relationships, and a recommendation. |
115
+ | `check_compatibility` | Version-aware peer-range check between two tools. |
116
+
117
+ ### Project Configuration
118
+
119
+ | Tool | What it does |
120
+ |---|---|
121
+ | `toolcairn_init` | Discover project roots, scan manifests, classify tools, write `.toolcairn/`. |
122
+ | `read_project_config` | Load the local `.toolcairn/config.json` snapshot (confirmed tools, pending items, audit log). |
123
+ | `update_project_config` | Atomically add, remove, or update a tool — every mutation is audited. |
124
+
125
+ ### Feedback Loop
126
+
127
+ | Tool | What it does |
128
+ |---|---|
129
+ | `report_outcome` | Fire-and-forget: did the recommended tool work out? Closes the learning loop. |
130
+ | `suggest_graph_update` | Submit a new tool, edge, or use-case for admin review (staged, never auto-promoted). |
131
+ | `check_issue` | **Last resort.** Search a tool's GitHub issues for known bugs — only after 4+ retries and a docs review. |
132
+
133
+ ### Session
134
+
135
+ | Tool | What it does |
136
+ |---|---|
137
+ | `classify_prompt` | Local: decide whether a tool search is needed at all (skips ToolCairn for non-tool prompts). |
138
+ | `toolcairn_auth` | Manage local sign-in: `login` / `status` / `logout`. |
139
+
140
+ ---
141
+
142
+ ## Configuration
143
+
144
+ | Environment variable | Default | Purpose |
145
+ |---|---|---|
146
+ | `TOOLPILOT_API_URL` | `https://api.neurynae.com` | Backend endpoint. Override for self-hosted or staging. |
147
+ | `TOOLCAIRN_TRACKING_ENABLED` | `true` | Set `false` to disable usage event logging (see [Privacy](#privacy--telemetry)). |
148
+ | `LOG_LEVEL` | `info` | Set `debug` for verbose stdio diagnostics. |
149
+ | `MCP_TRANSPORT` | `stdio` | Set `http` for HTTP transport (advanced). |
150
+
151
+ ### Where things live
152
+
153
+ - **Credentials** → `~/.toolcairn/credentials.json` (mode `0600`, 90-day expiry).
154
+ - **Per-project state** → `.toolcairn/{config.json, audit-log.jsonl, tracker.html}` at each detected project root.
155
+
156
+ The `tracker.html` file is a self-contained dashboard — open it in any browser to see every tool call, pending evaluation, and audit entry in real time.
118
157
 
119
158
  ---
120
159
 
121
- ## Session Management
160
+ ## Session management
122
161
 
123
- Your sign-in is stored locally in `~/.toolcairn/credentials.json` and lasts 90 days.
162
+ Your sign-in lives at `~/.toolcairn/credentials.json` and lasts 90 days. From inside your agent:
124
163
 
125
164
  ```
126
- toolcairn_auth status # check if you're signed in
127
- toolcairn_auth logout # sign out (next agent restart will prompt sign-in again)
165
+ toolcairn_auth { action: "status" } # check current sign-in
166
+ toolcairn_auth { action: "logout" } # clear credentials
128
167
  ```
129
168
 
130
- To sign in on a new machine or after signing out, simply restart your agent — the browser sign-in opens automatically.
169
+ To re-authenticate, simply restart your agent — the sign-in flow opens automatically.
131
170
 
132
171
  ---
133
172
 
134
- ## Project Configuration
173
+ ## Privacy & telemetry
174
+
175
+ We're explicit about what leaves your machine.
176
+
177
+ **Sent to ToolCairn** (when tracking is enabled):
178
+ - Tool name, duration, and success/error status — for service health and product analytics.
179
+ - **Never** full prompts, response bodies, or project file contents.
180
+
181
+ **Stays local:**
182
+ - Every audit entry (`.toolcairn/audit-log.jsonl`).
183
+ - Project state and tool snapshots.
184
+ - Your credentials file.
185
+
186
+ **Opt out at any time:**
187
+
188
+ ```bash
189
+ TOOLCAIRN_TRACKING_ENABLED=false
190
+ ```
135
191
 
136
- On first use, ToolCairn creates a `.toolcairn/config.json` file in your project. Your agent reads this to track which tools are confirmed for the project and avoids redundant searches on future sessions.
192
+ Tools still work normally; only the lightweight usage events are skipped.
193
+
194
+ Full privacy policy: [toolcairn.neurynae.com/privacy](https://toolcairn.neurynae.com/privacy).
195
+
196
+ ---
197
+
198
+ ## Troubleshooting
199
+
200
+ **Browser doesn't open for sign-in.** Copy the URL printed to stderr and visit it manually; enter the device code shown.
201
+
202
+ **`Module not found` or version errors.** Confirm Node 22+ with `node --version`.
203
+
204
+ **Behind a corporate proxy.** Set `HTTPS_PROXY` — `npx` and the MCP server respect it.
205
+
206
+ **Self-hosted backend.** Set `TOOLPILOT_API_URL=https://your-host`.
207
+
208
+ **Sign-in expired.** Restart your agent — the device-code flow re-runs automatically.
209
+
210
+ **Verbose logs.** Set `LOG_LEVEL=debug`.
211
+
212
+ **What is the agent doing?** Open `.toolcairn/tracker.html` in your browser for an auto-refreshing dashboard of every tool call.
213
+
214
+ ---
215
+
216
+ ## CLI: `scan`
217
+
218
+ A standalone health scan that doesn't start the MCP server:
219
+
220
+ ```bash
221
+ npx @neurynae/toolcairn-mcp scan [dir]
222
+ ```
223
+
224
+ Reads dependency manifests in `[dir]` (default: current directory) — `package.json`, `requirements.txt`, `pyproject.toml`, `Cargo.toml` — and reports health, alternatives, and warnings for each declared dependency.
225
+
226
+ Add `--json` for machine-readable output.
137
227
 
138
228
  ---
139
229
 
140
230
  ## Links
141
231
 
142
- - **Website**: https://toolcairn.neurynae.com
143
- - **Docs**: https://toolcairn.neurynae.com/docs
144
- - **GitHub**: https://github.com/NEURYNAE/ToolCairn
145
- - **Issues**: https://github.com/NEURYNAE/ToolCairn/issues
232
+ - **Website:** [toolcairn.neurynae.com](https://toolcairn.neurynae.com)
233
+ - **Docs:** [toolcairn.neurynae.com/docs](https://toolcairn.neurynae.com/docs)
234
+ - **npm:** [@neurynae/toolcairn-mcp](https://www.npmjs.com/package/@neurynae/toolcairn-mcp)
235
+ - **GitHub:** [neurynae/toolcairn-mcp](https://github.com/neurynae/toolcairn-mcp)
236
+ - **Issues:** [github.com/neurynae/toolcairn-mcp/issues](https://github.com/neurynae/toolcairn-mcp/issues)
237
+ - **Security:** responsible disclosure to `security@neurynae.com`
238
+
239
+ ---
240
+
241
+ ## Contributing
242
+
243
+ Issues and feature requests are welcome at [github.com/neurynae/toolcairn-mcp/issues](https://github.com/neurynae/toolcairn-mcp/issues).
244
+
245
+ The graph engine, search pipeline, and indexer are closed-source. This repository contains the public MCP client and project-config layer that runs on user machines.
146
246
 
147
247
  ---
148
248
 
149
249
  ## License
150
250
 
151
- MIT — © NEURYNAE
251
+ MIT — © 2026 NEURYNAE. See [LICENSE](https://github.com/neurynae/toolcairn-mcp/blob/main/LICENSE).