@neurynae/toolcairn-mcp 0.3.0 → 0.3.1

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 (2) hide show
  1. package/README.md +42 -87
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,18 +1,18 @@
1
1
  # @neurynae/toolcairn-mcp
2
2
 
3
- **Graph-powered tool intelligence for AI agents and developers.**
3
+ **Find the right open source tool, every time.**
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/@neurynae/toolcairn-mcp)](https://www.npmjs.com/package/@neurynae/toolcairn-mcp)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/NEURYNAE/ToolCairn/blob/main/LICENSE)
7
7
  [![npm downloads](https://img.shields.io/npm/dm/@neurynae/toolcairn-mcp)](https://www.npmjs.com/package/@neurynae/toolcairn-mcp)
8
8
 
9
- ToolCairn is an MCP (Model Context Protocol) server that gives your AI agent graph-powered tool intelligence. Search 12,000+ open source tools using a 4-stage pipeline combining BM25 keyword search, vector embeddings, and graph re-ranking — so your agent always recommends the *right* tool.
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.
10
10
 
11
11
  ---
12
12
 
13
13
  ## Quick Start
14
14
 
15
- No installation required. Add this to your MCP configuration and ToolCairn starts on the next session:
15
+ Add to your MCP config and restart your agent:
16
16
 
17
17
  ```json
18
18
  {
@@ -25,13 +25,19 @@ No installation required. Add this to your MCP configuration and ToolCairn start
25
25
  }
26
26
  ```
27
27
 
28
+ No API key required to get started.
29
+
28
30
  ---
29
31
 
30
- ## Installation by Client
32
+ ## Setup by Client
33
+
34
+ ### Claude Code
31
35
 
32
- ### Claude Code (CLI)
36
+ ```bash
37
+ claude mcp add toolcairn -- npx @neurynae/toolcairn-mcp
38
+ ```
33
39
 
34
- Add to `~/.claude/claude_desktop_config.json` (or project `.mcp.json`):
40
+ Or add to `~/.claude/claude_desktop_config.json`:
35
41
 
36
42
  ```json
37
43
  {
@@ -44,11 +50,6 @@ Add to `~/.claude/claude_desktop_config.json` (or project `.mcp.json`):
44
50
  }
45
51
  ```
46
52
 
47
- Or via the CLI:
48
- ```bash
49
- claude mcp add toolcairn -- npx @neurynae/toolcairn-mcp
50
- ```
51
-
52
53
  ### Cursor
53
54
 
54
55
  Open **Settings → MCP** and add:
@@ -66,8 +67,6 @@ Open **Settings → MCP** and add:
66
67
 
67
68
  ### VS Code (Copilot)
68
69
 
69
- Add to `.vscode/settings.json` or user settings:
70
-
71
70
  ```json
72
71
  {
73
72
  "github.copilot.chat.mcp.servers": {
@@ -82,8 +81,6 @@ Add to `.vscode/settings.json` or user settings:
82
81
 
83
82
  ### Windsurf
84
83
 
85
- Add to `~/.codeium/windsurf/mcp_config.json`:
86
-
87
84
  ```json
88
85
  {
89
86
  "mcpServers": {
@@ -95,102 +92,61 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
95
92
  }
96
93
  ```
97
94
 
98
- ### Custom / Other Clients
95
+ ---
99
96
 
100
- Any MCP-compatible client supporting stdio transport works:
97
+ ## Available Tools
101
98
 
102
- ```bash
103
- npx @neurynae/toolcairn-mcp
104
- ```
99
+ | Tool | What it does |
100
+ |------|-------------|
101
+ | `search_tools` | Search for the best tool for a specific need using natural language |
102
+ | `search_tools_respond` | Answer follow-up questions to refine search results |
103
+ | `get_stack` | Get a curated tool stack recommendation for a project |
104
+ | `compare_tools` | Compare two tools side by side |
105
+ | `check_compatibility` | Check if two tools are known to work together |
106
+ | `check_issue` | Look up known issues for a tool before spending time debugging |
107
+ | `report_outcome` | Report whether a recommended tool worked out |
108
+ | `refine_requirement` | Turn a vague requirement into a specific, searchable need |
109
+ | `verify_suggestion` | Validate a tool your agent suggested |
110
+ | `suggest_graph_update` | Suggest a new tool or relationship to add |
111
+ | `toolcairn_init` | Set up ToolCairn for the current project |
112
+ | `init_project_config` | Initialize project tool configuration |
113
+ | `read_project_config` | Read and validate existing project config |
114
+ | `update_project_config` | Add or remove tools from project config |
115
+ | `toolcairn_auth` | Sign in to unlock higher rate limits |
105
116
 
106
117
  ---
107
118
 
108
119
  ## Authentication
109
120
 
110
- ToolCairn works out of the box with no authentication — an anonymous API key is generated on first run and stored in `~/.toolpilot/credentials.json`.
111
-
112
- **Authenticated users** get higher rate limits (300 req/min vs 60 req/min for anonymous).
121
+ ToolCairn works out of the box with no sign-in — an anonymous session is created automatically on first run.
113
122
 
114
- To authenticate, ask your agent to run:
123
+ **Authenticated users** get higher rate limits. To sign in, ask your agent:
115
124
 
116
125
  ```
117
126
  toolcairn_auth login
118
127
  ```
119
128
 
120
- This opens your browser to `https://toolcairn.neurynae.com/device`, where you sign in with Google, GitHub, or email/password. Once confirmed, your agent is authenticated — no per-tool login needed.
121
-
122
- Check auth status:
123
- ```
124
- toolcairn_auth status
125
- ```
129
+ This opens a browser where you can sign in with Google, GitHub, or email. Once confirmed, all tools are authorized — no per-tool login needed.
126
130
 
127
- Log out:
128
131
  ```
129
- toolcairn_auth logout
132
+ toolcairn_auth status # check current auth state
133
+ toolcairn_auth logout # revert to anonymous
130
134
  ```
131
135
 
132
136
  ---
133
137
 
134
- ## Available Tools
135
-
136
- | Tool | Description |
137
- |------|-------------|
138
- | `search_tools` | Natural-language tool search with guided clarification |
139
- | `search_tools_respond` | Submit clarification answers to refine search results |
140
- | `get_stack` | Full stack recommendation for a project description |
141
- | `compare_tools` | Head-to-head comparison of two tools with health metrics |
142
- | `check_compatibility` | Check if two tools are known to work together |
143
- | `check_issue` | Look up known GitHub issues for a tool before debugging |
144
- | `report_outcome` | Report whether a recommended tool worked (improves future results) |
145
- | `refine_requirement` | Decompose a vague need into searchable tool requirements |
146
- | `verify_suggestion` | Validate agent-suggested tools against the ToolCairn graph |
147
- | `suggest_graph_update` | Contribute new tool relationships to the knowledge graph |
148
- | `toolcairn_init` | Set up ToolCairn integration for the current project |
149
- | `init_project_config` | Initialize `.toolcairn/config.json` for the project |
150
- | `read_project_config` | Read and validate the project's tool configuration |
151
- | `update_project_config` | Add or remove tools from the project config |
152
- | `toolcairn_auth` | Authenticate with ToolCairn (login / status / logout) |
153
-
154
- ---
155
-
156
- ## How It Works
157
-
158
- ToolCairn uses a **4-stage search pipeline**:
138
+ ## Rate Limits
159
139
 
160
- 1. **Hybrid Search** — BM25 keyword matching + vector embeddings search 12,000+ indexed tools in parallel
161
- 2. **Graph Re-ranking** — A knowledge graph (Memgraph) re-ranks candidates using ecosystem relationships: integrations, alternatives, co-occurrence signals
162
- 3. **Clarification** — When queries are ambiguous, targeted follow-up questions narrow the results
163
- 4. **Final Selection** — Returns the top 1–2 tools with confidence scores, reasons, and documentation links
140
+ | | Requests / minute |
141
+ |---|---|
142
+ | Anonymous | 60 |
143
+ | Authenticated | 300 |
164
144
 
165
145
  ---
166
146
 
167
147
  ## Project Configuration
168
148
 
169
- On first run, ToolCairn creates `.toolcairn/config.json` in your project root. Your agent reads this file to understand which tools are already confirmed for the project and avoids redundant searches.
170
-
171
- ```json
172
- {
173
- "project": {
174
- "name": "my-project",
175
- "language": "TypeScript",
176
- "framework": "Next.js"
177
- },
178
- "confirmed_tools": ["next", "prisma", "tailwindcss"],
179
- "pending_evaluation": [],
180
- "stale_tools": []
181
- }
182
- ```
183
-
184
- ---
185
-
186
- ## Rate Limits
187
-
188
- | Tier | Rate Limit |
189
- |------|-----------|
190
- | Anonymous (default) | 60 requests / minute |
191
- | Authenticated | 300 requests / minute |
192
-
193
- Rate limits are per API key, enforced at the Cloudflare edge.
149
+ 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.
194
150
 
195
151
  ---
196
152
 
@@ -199,7 +155,6 @@ Rate limits are per API key, enforced at the Cloudflare edge.
199
155
  - **Website**: https://toolcairn.neurynae.com
200
156
  - **Docs**: https://toolcairn.neurynae.com/docs
201
157
  - **GitHub**: https://github.com/NEURYNAE/ToolCairn
202
- - **npm**: https://www.npmjs.com/package/@neurynae/toolcairn-mcp
203
158
  - **Issues**: https://github.com/NEURYNAE/ToolCairn/issues
204
159
 
205
160
  ---
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@neurynae/toolcairn-mcp",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "private": false,
5
5
  "license": "MIT",
6
6
  "type": "module",