Forage

1<div align="center">
2 
3# 🌿 Forage
4 
5**Self-improving tool discovery for AI agents.**
6 
7Install one MCP server. Your agent finds the rest.
8 
9[![npm version](https://img.shields.io/npm/v/forage-mcp.svg)](https://www.npmjs.com/package/forage-mcp)
10[![npm downloads](https://img.shields.io/npm/dm/forage-mcp.svg)](https://www.npmjs.com/package/forage-mcp)
11[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
12 
13[npm](https://www.npmjs.com/package/forage-mcp) · [GitHub](https://github.com/isaac-levine/forage) · [Contributing](CONTRIBUTING.md)
14 
15</div>
16 
17---
18 
19Forage 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.
20 
21<!-- TODO: Add demo GIF here -->
22<!-- ![Forage demo](assets/demo.gif) -->
23 
24## Why?
25 
26AI 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.
27 
28Forage closes that loop:
29 
30```
31Agent encounters a task it can't do
32  → forage_search("query postgres database")
33  → forage_install("@modelcontextprotocol/server-postgres")
34  → Tools available IMMEDIATELY (no restart)
35  → forage_learn() saves instructions to CLAUDE.md
36  → Next session: auto-starts, agent already knows how to use it
37```
38 
39## Quick Start
40 
41**Claude Code**
42 
43```bash
44claude mcp add forage -- npx -y forage-mcp
45```
46 
47**Cursor**
48 
49```bash
50npx forage-mcp init --client cursor
51```
52 
53That's it. Start a new session and Forage is ready.
54 
55## Tools
56 
57| Tool | Description |
58|---|---|
59| `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) |
60| `forage_evaluate` | Get details on a package — downloads, README, install command |
61| `forage_install` | Install and start an MCP server as a proxied subprocess (requires user approval) |
62| `forage_learn` | Write usage instructions to CLAUDE.md / AGENTS.md / .cursor/rules/ |
63| `forage_status` | List all installed and running tools |
64| `forage_uninstall` | Remove a tool and clean up rules |
65 
66## How It Works
67 
68Forage is a **gateway/proxy** MCP server:
69 
701. **You install Forage once** — it's the only MCP server you configure manually
712. **Forage discovers tools** — searches the Official MCP Registry, Smithery, and npm in parallel
723. **Forage installs tools** — starts them as child processes, wraps their capabilities
734. **No restart needed** — emits `list_changed` notifications so the agent picks up new tools instantly
745. **Knowledge persists** — `forage_learn` writes to agent rule files, manifest auto-starts tools next session
75 
76<details>
77<summary><strong>Architecture</strong></summary>
78 
79```
80┌─────────────────────────────────────────────┐
81│  Claude Code / Cursor / Codex               │
82│                                             │
83│  "I need to query a Postgres database"      │
84└──────────────────┬──────────────────────────┘
85                   │ MCP
86                   ▼
87┌─────────────────────────────────────────────┐
88│  Forage MCP Server                          │
89│                                             │
90│  forage_search ─── Official Registry        │
91│  forage_install    Smithery                 │
92│  forage_learn      npm                      │
93│  forage_status                              │
94│                                             │
95│  ┌─────────────┐  ┌─────────────┐          │
96│  │ Postgres MCP│  │ GitHub MCP  │  ...      │
97│  │ (subprocess)│  │ (subprocess)│          │
98│  └─────────────┘  └─────────────┘          │
99└─────────────────────────────────────────────┘
100```
101 
102When you install a tool through Forage:
103 
1041. Forage runs `npx -y <package>` as a child process
1052. Connects to it via `StdioClientTransport` (MCP client)
1063. Discovers the child server's tools via `listTools`
1074. Re-registers each tool on the Forage server with a namespaced name (`foraged__<server>__<tool>`)
1085. Sends `tools/list_changed` notification — the agent sees new tools immediately
1096. When the agent calls a proxied tool, Forage forwards the call to the child server
110 
111</details>
112 
113<details>
114<summary><strong>Persistence</strong></summary>
115 
116Forage stores its state in `~/.forage/`:
117 
118| File | Purpose |
119|---|---|
120| `manifest.json` | Installed tools, command/args, auto-start configuration |
121| `install-log.json` | Audit trail of all installs and uninstalls |
122| `cache/` | Cached registry search results |
123 
124On startup, Forage reads the manifest and auto-starts all previously installed servers. Your agent picks up right where it left off.
125 
126</details>
127 
128## CLI
129 
130Forage also includes a CLI for humans:
131 
132```bash
133forage search "postgres database"    # Search registries
134forage list                          # List installed tools
135forage init                          # Set up for Claude Code
136forage init --client cursor          # Set up for Cursor
137```
138 
139## Security
140 
141> [!IMPORTANT]
142> Forage cannot install tools without explicit user approval. Every `forage_install` call requires `confirm: true`.
143 
144- **Audit trail** — every install/uninstall is logged with timestamps to `~/.forage/install-log.json`
145- **No remote backend** — everything runs locally. Registry searches are read-only GET requests to public APIs.
146- **No secrets stored** — environment variables for child servers are passed at install time, not persisted.
147 
148## Development
149 
150```bash
151git clone https://github.com/isaac-levine/forage.git
152cd forage
153npm install
154npm run build
155```
156 
157Test locally with Claude Code:
158 
159```bash
160claude mcp add forage-dev -- node /path/to/forage/dist/server.js
161```
162 
163See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
164 
165## Roadmap
166 
167### Features
168 
169- [ ] `forage update` — check for newer versions of installed tools
170- [ ] Support for pip/cargo/brew packages (not just npm)
171- [ ] Smarter search ranking (weight by downloads, stars, description relevance)
172- [ ] Auto-configure environment variables from `.env` files
173- [ ] `forage doctor` — diagnose common setup issues
174 
175### Distribution
176 
177- [x] Publish to npm
178- [ ] Submit to the [Official MCP Registry](https://registry.modelcontextprotocol.io)
179- [ ] Submit to [Smithery](https://smithery.ai)
180- [ ] Submit to [mcp.so](https://mcp.so) and [glama.ai](https://glama.ai/mcp/servers)
181- [ ] Landing page at forage.dev
182 
183### Community
184 
185- [ ] Demo GIF / video in README
186- [ ] Write launch blog post
187- [ ] Post to r/ClaudeAI, r/LocalLLaMA, Hacker News (Show HN)
188- [ ] Share in MCP Discord / community channels
189- [ ] Write use-case guides (e.g. "Add Postgres to Claude Code in 30 seconds")
190- [ ] Add GitHub Discussions for Q&A and feature requests
191 
192## License
193 
194[MIT](LICENSE)
195