{
"markdown": "\n\n# ๐ฟ Forage\n\n**Self-improving tool discovery for AI agents.**\n\nInstall one MCP server. Your agent finds the rest.\n\n[](https://www.npmjs.com/package/forage-mcp)\n[](https://www.npmjs.com/package/forage-mcp)\n[](LICENSE)\n\n[npm](https://www.npmjs.com/package/forage-mcp) ยท [GitHub](https://github.com/isaac-levine/forage) ยท [Contributing](CONTRIBUTING.md)\n\n
\n\n---\n\nForage is an MCP server that lets AI agents discover, install, and learn to use new tools โ automatically. When an agent hits a wall, it forages for the right tool, installs it, and teaches itself how to use it. No restarts. No manual config. The agent gets permanently smarter.\n\n\n\n\n## Why?\n\nAI coding agents are limited to whatever tools they're configured with at session start. Need to query a database? Deploy to Vercel? Search Slack? The agent apologizes and you manually install the right MCP server.\n\nForage closes that loop:\n\n```\nAgent encounters a task it can't do\n โ forage_search(\"query postgres database\")\n โ forage_install(\"@modelcontextprotocol/server-postgres\")\n โ Tools available IMMEDIATELY (no restart)\n โ forage_learn() saves instructions to CLAUDE.md\n โ Next session: auto-starts, agent already knows how to use it\n```\n\n## Quick Start\n\n**Claude Code**\n\n```bash\nclaude mcp add forage -- npx -y forage-mcp\n```\n\n**Cursor**\n\n```bash\nnpx forage-mcp init --client cursor\n```\n\nThat's it. Start a new session and Forage is ready.\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `forage_search` | Search for MCP servers across the [Official MCP Registry](https://registry.modelcontextprotocol.io), [Smithery](https://smithery.ai), and [npm](https://www.npmjs.com) |\n| `forage_evaluate` | Get details on a package โ downloads, README, install command |\n| `forage_install` | Install and start an MCP server as a proxied subprocess (requires user approval) |\n| `forage_learn` | Write usage instructions to CLAUDE.md / AGENTS.md / .cursor/rules/ |\n| `forage_status` | List all installed and running tools |\n| `forage_uninstall` | Remove a tool and clean up rules |\n\n## How It Works\n\nForage is a **gateway/proxy** MCP server:\n\n1. **You install Forage once** โ it's the only MCP server you configure manually\n2. **Forage discovers tools** โ searches the Official MCP Registry, Smithery, and npm in parallel\n3. **Forage installs tools** โ starts them as child processes, wraps their capabilities\n4. **No restart needed** โ emits `list_changed` notifications so the agent picks up new tools instantly\n5. **Knowledge persists** โ `forage_learn` writes to agent rule files, manifest auto-starts tools next session\n\n\nArchitecture
\n\n```\nโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ\nโ Claude Code / Cursor / Codex โ\nโ โ\nโ \"I need to query a Postgres database\" โ\nโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโ\n โ MCP\n โผ\nโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ\nโ Forage MCP Server โ\nโ โ\nโ forage_search โโโ Official Registry โ\nโ forage_install Smithery โ\nโ forage_learn npm โ\nโ forage_status โ\nโ โ\nโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โ\nโ โ Postgres MCPโ โ GitHub MCP โ ... โ\nโ โ (subprocess)โ โ (subprocess)โ โ\nโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โ\nโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ\n```\n\nWhen you install a tool through Forage:\n\n1. Forage runs `npx -y ` as a child process\n2. Connects to it via `StdioClientTransport` (MCP client)\n3. Discovers the child server's tools via `listTools`\n4. Re-registers each tool on the Forage server with a namespaced name (`foraged____`)\n5. Sends `tools/list_changed` notification โ the agent sees new tools immediately\n6. When the agent calls a proxied tool, Forage forwards the call to the child server\n\n \n\n\nPersistence
\n\nForage stores its state in `~/.forage/`:\n\n| File | Purpose |\n|---|---|\n| `manifest.json` | Installed tools, command/args, auto-start configuration |\n| `install-log.json` | Audit trail of all installs and uninstalls |\n| `cache/` | Cached registry search results |\n\nOn startup, Forage reads the manifest and auto-starts all previously installed servers. Your agent picks up right where it left off.\n\n \n\n## CLI\n\nForage also includes a CLI for humans:\n\n```bash\nforage search \"postgres database\" # Search registries\nforage list # List installed tools\nforage init # Set up for Claude Code\nforage init --client cursor # Set up for Cursor\n```\n\n## Security\n\n> [!IMPORTANT]\n> Forage cannot install tools without explicit user approval. Every `forage_install` call requires `confirm: true`.\n\n- **Audit trail** โ every install/uninstall is logged with timestamps to `~/.forage/install-log.json`\n- **No remote backend** โ everything runs locally. Registry searches are read-only GET requests to public APIs.\n- **No secrets stored** โ environment variables for child servers are passed at install time, not persisted.\n\n## Development\n\n```bash\ngit clone https://github.com/isaac-levine/forage.git\ncd forage\nnpm install\nnpm run build\n```\n\nTest locally with Claude Code:\n\n```bash\nclaude mcp add forage-dev -- node /path/to/forage/dist/server.js\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for more details.\n\n## Roadmap\n\n### Features\n\n- [ ] `forage update` โ check for newer versions of installed tools\n- [ ] Support for pip/cargo/brew packages (not just npm)\n- [ ] Smarter search ranking (weight by downloads, stars, description relevance)\n- [ ] Auto-configure environment variables from `.env` files\n- [ ] `forage doctor` โ diagnose common setup issues\n\n### Distribution\n\n- [x] Publish to npm\n- [ ] Submit to the [Official MCP Registry](https://registry.modelcontextprotocol.io)\n- [ ] Submit to [Smithery](https://smithery.ai)\n- [ ] Submit to [mcp.so](https://mcp.so) and [glama.ai](https://glama.ai/mcp/servers)\n- [ ] Landing page at forage.dev\n\n### Community\n\n- [ ] Demo GIF / video in README\n- [ ] Write launch blog post\n- [ ] Post to r/ClaudeAI, r/LocalLLaMA, Hacker News (Show HN)\n- [ ] Share in MCP Discord / community channels\n- [ ] Write use-case guides (e.g. \"Add Postgres to Claude Code in 30 seconds\")\n- [ ] Add GitHub Discussions for Q&A and feature requests\n\n## License\n\n[MIT](LICENSE)\n",
"bytes": 6840,
"sha": "20f7f356eff641ec50b90c7e9485bad4980945d706ae45fa8cc310317d6042b4",
"repo_slug": "isaac-levine/forage",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_isaac_levine_forage_146f38ce/readme"
}