forage: Instructions file for Claude Code

Forage

Self-improving tool discovery for AI agents. An MCP server that lets agents find, install, and learn to use new tools without human intervention or restarts.

Project Overview

Forage is a gateway/proxy MCP server. It's installed once and acts as a hub — when an agent discovers and installs a new tool through Forage, Forage starts it as a subprocess, wraps its capabilities, and emits list_changed notifications so the agent can use it immediately.

Core Flow

1. Agent calls forage_search("postgres database") to find tools
2. Agent calls forage_install("@modelcontextprotocol/server-postgres", { confirm: true }) to install
3. Forage starts the server as a child process, wraps its tools, notifies the agent
4. Agent calls forage_learn(...) to persist instructions in CLAUDE.md
5. Next session: Forage auto-starts from ~/.forage/manifest.json

Architecture

src/
├── server.ts              # MCP server entry — tool registration + proxy lifecycle
├── cli.ts                 # CLI: init, search, list
├── tools/                 # One file per MCP tool (search, evaluate, install, learn, status, uninstall)
├── registries/            # API clients for Official MCP Registry, Smithery, npm
├── proxy/
│   ├── manager.ts         # Spawns/stops child MCP servers via StdioClientTransport
│   └── wrapper.ts         # Namespaces child tools as foraged__<server>__<tool>
├── rules/
│   ├── detector.ts        # Detects CLAUDE.md, AGENTS.md, .cursor/rules/
│   └── writer.ts          # Adds/removes tool blocks with <!-- forage:name --> markers
└── persistence/
    ├── manifest.ts        # ~/.forage/manifest.json read/write
    └── log.ts             # ~/.forage/install-log.json audit trail

Tech Stack

• TypeScript with ES modules ("type": "module")
• @modelcontextprotocol/sdk — MCP server and client
• Node.js >= 18 (uses native fetch, AbortSignal.timeout)
• No runtime dependencies beyond the MCP SDK (which bundles Zod)

Development