isaac-levine/forage

**Self-improving tool discovery for AI agents.**
Install one MCP server. Your agent finds the rest.
npm · GitHub · Contributing
---
Forage 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.
Why?
AI 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.
Forage closes that loop:
Quick Start
**Claude Code**
**Cursor**
That's it. Start a new session and Forage is ready.
Tools
| Tool | Description |
|---|---|
| forage_search | Search for MCP servers across the Official MCP Registry, Smithery, and npm |
| forage_evaluate | Get details on a package — downloads, README, install command |
| forage_install | Install and start an MCP server as a proxied subprocess (requires user approval) |
| forage_learn | Write usage instructions to CLAUDE.md / AGENTS.md / .cursor/rules/ |
| forage_status | List all installed and running tools |
| forage_uninstall | Remove a tool and clean up rules |
How It Works
Forage is a **gateway/proxy** MCP server:
1. **You install Forage once** — it's the only MCP server you configure manually
2. **Forage discovers tools** — searches the Official MCP Registry, Smithery, and npm in parallel
3. **Forage installs tools** — starts them as child processes, wraps their capabilities
4. **No restart needed** — emits list_changed notifications so the agent picks up new tools instantly
5. **Knowledge persists** — forage_learn writes to agent rule files, manifest auto-starts tools next session
Architecture
When you install a tool through Forage:
1. Forage runs npx -y as a child process
2. Connects to it via StdioClientTransport (MCP client)
3. Discovers the child server's tools via listTools
4. Re-registers each tool on the Forage server with a namespaced name (foraged__ __ )
5. Sends tools/list_changed notification — the agent sees new tools immediately
6. When the agent calls a proxied tool, Forage forwards the call to the child server
Persistence
Forage stores its state in ~/.forage/:
| File | Purpose |
|---|---|
| manifest.json | Installed tools, command/args, auto-start configuration |
| install-log.json | Audit trail of all installs and uninstalls |
| cache/ | Cached registry search results |
On startup, Forage reads the manifest and auto-starts all previously installed servers. Your agent picks up right where it left off.
CLI
Forage also includes a CLI for humans:
Security
> [!IMPORTANT]
> Forage cannot install tools without explicit user approval. Every forage_install call requires confirm: true.
- **Audit trail** — every install/uninstall is logged with timestamps to ~/.forage/install-log.json