{ "markdown": "

\n \n \"ToolCairn\n \n

\n\n

\n \"npm\n \"npm\n \"License:\n \"Node.js\"\n

\n\n

\n \"Official\n \"Smithery\"\n \"Glama\"\n \"MCP.Directory\"\n

\n\n# `@neurynae/toolcairn-mcp`\n\n> Source for [`@neurynae/toolcairn-mcp` on npm](https://www.npmjs.com/package/@neurynae/toolcairn-mcp). Install via the package, not from this repo.\n\nToolCairn 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.\n\n> **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.\n\n

\n \"How\n

\n\nThe 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.\n\n---\n\n## Why ToolCairn?\n\nPlain 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.\n\nToolCairn fixes this with three things you can't get from raw registry APIs:\n\n- **Graph-aware ranking** — recommendations consider how tools relate to each other (dependencies, integrations, replacements, conflicts), not just popularity.\n- **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?\"*\n- **A continuous learning loop** — every accepted, rejected, or replaced recommendation feeds back into the graph, so quality improves with use.\n\n---\n\n## Quick Start\n\n**Step 1.** Create a free account at **[toolcairn.neurynae.com/signup](https://toolcairn.neurynae.com/signup)**.\n\n**Step 2.** Add to your MCP config and restart your agent:\n\n```json\n{\n \"mcpServers\": {\n \"toolcairn\": {\n \"command\": \"npx\",\n \"args\": [\"@neurynae/toolcairn-mcp\"]\n }\n }\n}\n```\n\n**Step 3.** A browser window opens for sign-in on first start. Once you confirm, all tools are available immediately — no further setup.\n\nRequires **Node.js 22+**.\n\n---\n\n## Setup — Claude Code\n\nThe fastest path:\n\n```bash\nclaude mcp add toolcairn -- npx @neurynae/toolcairn-mcp\n```\n\nOr paste the JSON block above into `~/.claude/claude_desktop_config.json` under `mcpServers`.\n\n> 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.\n\n---\n\n## What you can do\n\n### Find a tool\nYour 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.\n\n### Build a stack\nYour 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.\n\n### Compare options\n*\"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.\n\n### Check version compatibility\n*\"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`).\n\n### Track project tools\nOn 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.\n\n---\n\n## Available Tools\n\nThe MCP server exposes 16 tools, grouped by purpose. Most are local (no network) or fire-and-forget; the search, compare, and stack tools call the ToolCairn API.\n\n### Discovery\n\n| Tool | What it does |\n|---|---|\n| `search_tools` | Natural-language search with health signals and alternatives. May ask clarifying questions when intent is ambiguous. |\n| `search_tools_respond` | Submit answers to refine an in-progress search. |\n| `refine_requirement` | Decompose a vague use-case (\"build a SaaS\") into specific, searchable sub-needs. |\n| `verify_suggestion` | Check whether the agent's tool picks are actually indexed in the ToolCairn graph. |\n\n### Stacks & Compatibility\n\n| Tool | What it does |\n|---|---|\n| `get_stack` | Compose a complementary tool stack with a cross-version compatibility matrix. |\n| `compare_tools` | Head-to-head: health metrics, graph relationships, and a recommendation. |\n| `check_compatibility` | Version-aware peer-range check between two tools. |\n\n### Project Configuration\n\n| Tool | What it does |\n|---|---|\n| `toolcairn_init` | Discover project roots, scan manifests, classify tools, write `.toolcairn/`. |\n| `read_project_config` | Load the local `.toolcairn/config.json` snapshot (confirmed tools, pending items, audit log). |\n| `update_project_config` | Atomically add, remove, or update a tool — every mutation is audited. |\n\n### Feedback Loop\n\n| Tool | What it does |\n|---|---|\n| `report_outcome` | Fire-and-forget: did the recommended tool work out? Closes the learning loop. |\n| `feedback` | **Agent feedback on ToolCairn itself.** Call ONLY when a ToolCairn response was wrong, broken, low-quality, or missed something — never for positive feedback. **Free of daily quota.** |\n| `suggest_graph_update` | Submit a new tool, edge, or use-case for admin review (staged, never auto-promoted). |\n| `check_issue` | **Last resort.** Search a tool's GitHub issues for known bugs — only after 4+ retries and a docs review. |\n\n### Session\n\n| Tool | What it does |\n|---|---|\n| `classify_prompt` | Local: decide whether a tool search is needed at all (skips ToolCairn for non-tool prompts). |\n| `toolcairn_auth` | Manage local sign-in: `login` / `status` / `logout`. |\n\n---\n\n## Configuration\n\n| Environment variable | Default | Purpose |\n|---|---|---|\n| `TOOLCAIRN_TRACKING_ENABLED` | `true` | Set `false` to disable usage event logging (see [Privacy](#privacy--telemetry)). |\n| `LOG_LEVEL` | `info` | Set `debug` for verbose stdio diagnostics. |\n| `MCP_TRANSPORT` | `stdio` | Set `http` for HTTP transport (advanced). |\n\n### Where things live\n\n- **Credentials** → `~/.toolcairn/credentials.json` (mode `0600`, 90-day expiry).\n- **Per-project state** → `.toolcairn/{config.json, audit-log.jsonl, tracker.html}` at each detected project root.\n\nThe `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.\n\n---\n\n## Session management\n\nYour sign-in lives at `~/.toolcairn/credentials.json` and lasts 90 days. From inside your agent:\n\n```\ntoolcairn_auth { action: \"status\" } # check current sign-in\ntoolcairn_auth { action: \"logout\" } # clear credentials\n```\n\nTo re-authenticate, simply restart your agent — the sign-in flow opens automatically.\n\n---\n\n## Privacy & telemetry\n\nWe're explicit about what leaves your machine.\n\n**Sent to ToolCairn** (when tracking is enabled):\n- Tool name, duration, and success/error status — for service health and product analytics.\n- **Never** full prompts, response bodies, or project file contents.\n\n**Stays local:**\n- Every audit entry (`.toolcairn/audit-log.jsonl`).\n- Project state and tool snapshots.\n- Your credentials file.\n\n**Opt out at any time:**\n\n```bash\nTOOLCAIRN_TRACKING_ENABLED=false\n```\n\nTools still work normally; only the lightweight usage events are skipped.\n\nFull privacy policy: [toolcairn.neurynae.com/privacy](https://toolcairn.neurynae.com/privacy).\n\n---\n\n## Troubleshooting\n\n**Browser doesn't open for sign-in.** Copy the URL printed to stderr and visit it manually; enter the device code shown.\n\n**`Module not found` or version errors.** Confirm Node 22+ with `node --version`.\n\n**Behind a corporate proxy.** Set `HTTPS_PROXY` — `npx` and the MCP server respect it.\n\n**Self-hosted backend.** Set `TOOLPILOT_API_URL=https://your-host`.\n\n**Sign-in expired.** Restart your agent — the device-code flow re-runs automatically.\n\n**Verbose logs.** Set `LOG_LEVEL=debug`.\n\n**What is the agent doing?** Open `.toolcairn/tracker.html` in your browser for an auto-refreshing dashboard of every tool call.\n\n---\n\n## CLI: `scan`\n\nA standalone health scan that doesn't start the MCP server:\n\n```bash\nnpx @neurynae/toolcairn-mcp scan [dir]\n```\n\nReads 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.\n\nAdd `--json` for machine-readable output.\n\n---\n\n## Links\n\n- **Website:** [toolcairn.neurynae.com](https://toolcairn.neurynae.com)\n- **Docs:** [toolcairn.neurynae.com/docs](https://toolcairn.neurynae.com/docs)\n- **npm:** [@neurynae/toolcairn-mcp](https://www.npmjs.com/package/@neurynae/toolcairn-mcp)\n- **GitHub:** [neurynae/toolcairn-mcp](https://github.com/neurynae/toolcairn-mcp)\n- **Issues:** [github.com/neurynae/toolcairn-mcp/issues](https://github.com/neurynae/toolcairn-mcp/issues)\n- **Security:** responsible disclosure to `security@neurynae.com`\n\n---\n\n## Contributing\n\nIssues and feature requests are welcome at [github.com/neurynae/toolcairn-mcp/issues](https://github.com/neurynae/toolcairn-mcp/issues).\n\nThe 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.\n\n---\n\n## License\n\nMIT — © 2026 NEURYNAE. See [LICENSE](./LICENSE).\n", "bytes": 12016, "sha": "b61b18290ccec5f73979562c9234eba9d40bcc96da99c244bb19e0afaeed5391", "repo_slug": "neurynae/toolcairn-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_neurynae_toolcairn_mcp_bab6ffb6/readme" }