web3-research-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for AI agents (Claude Code and others) working in this repository.

What this is

web3-research-mcp is a Model Context Protocol server that runs locally and gives an AI client (Claude Desktop, Cursor, etc.) a toolset for deep crypto research. It sends searches and token lookups to external providers (including CoinGecko and DeFiLlama), fetches supplied page URLs, and stores research state/resources locally.

It runs over stdio as a single Node process. There is no database and no network service to stand up: the client launches it via npx web3-research-mcp and talks to it on stdin/stdout.

Stack

• TypeScript (ESM, "type": "module"), compiled with tsc to dist/.
• @modelcontextprotocol/sdk — McpServer + StdioServerTransport.
• zod — tool/prompt input schemas.
• duck-duck-scrape — web/news/image/video search (no API key).
• cheerio — parse fetched HTML. Network I/O uses the global fetch.
• Node >= 18 (CI builds on 20.x and 22.x).

Build & run

npm ci            # install (use this in CI / clean checkouts)
npm run build     # tsc -> dist/
npm start         # node dist/server.js   (talks MCP over stdio)
npm run dev       # build + start

There is no test suite and no linter configured. CI (.github/workflows/ci.yml) is the source of truth for "does it pass": it runs npm ci → npm run build → asserts dist/server.js exists → node --check bin/cli.js → node bin/cli.js --help. Before opening a PR, run npm run build locally and make sure it's clean — tsc runs with strict: true, so type errors fail the build.

Layout

bin/cli.js                  npx entrypoint — spawns dist/server.js over stdio
src/server.ts               wires up McpServer: resources, the token-research prompt,
                            then calls registerAllTools()
src/tools/index.ts          registerAllTools() -> research + coingecko + defillama
src/tools/researchTools.ts  search, fetch-content, research-with-keywords,
                            create-research-plan, update-status, list-resources, ...
src/tools/coinGeckoTool.ts  coingecko-data / coingecko-search / coingecko-tickers
src/tools/defiLlamaTool.ts  defillama-data / defillama-search
src/utils/searchUtils.ts    performSearch / fetchContent / searchSource (DDG + fetch)
src/utils/format.ts         fmtUsd number formatting; quoteInput/escapeText for
                            caller text echoed in tool output and logs
src/storage/researchStorage.ts  in-memory + on-disk research state and resources,
                            and the ResearchData / ResearchResource types