{ "markdown": "

\n

Code Fundi

\n

The Codebase Map for AI Agents, Teams and Applications.

\n

\n

\n

\n \"Code\n
\n

\n

\n\n

\n \n \n \n \n
\n \n \n \n \n \n \n \n \n \n
\n

\n\n# Code-Fundi MCP Server\n\nA production-grade [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the [Code-Fundi](https://api.codefundi.app) API: a codebase map and blast-radius engine for AI coding agents. Enables any MCP-compatible AI assistant (Claude, Claude Code, Cursor, Windsurf, VS Code Copilot, and more) to search, research, index, and scan code repositories through natural language, and see what a change breaks before it ships.\n\nBuilt with [FastMCP](https://github.com/punkpeye/fastmcp) (TypeScript) and [Zod](https://zod.dev) for schema validation.\n\n## Getting started for AI agents\n\nIf you are an AI agent (or configuring one) and **no `CODEFUNDI_API_KEY` is set**, you must self-authenticate before using search, repos, chat, or other authenticated tools. The auth tools (`code-fundi-auth-*`) work without a pre-existing key.\n\n### Which path to use\n\n| Situation | Action |\n|-----------|--------|\n| `CODEFUNDI_API_KEY` is set in MCP config | Use any tool immediately — the server sends it as `X-API-Key` on every request |\n| No API key configured | Run the **OTP self-auth flow** below (recommended) or **password sign-in** |\n\n### Zero-config MCP setup (no API key)\n\nYou can start the MCP server without `CODEFUNDI_API_KEY` and authenticate at runtime:\n\n```json\n{\n \"mcpServers\": {\n \"code-fundi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@codefundi/code-fundi-mcp\"]\n }\n }\n}\n```\n\n### Self-authenticate with OTP (recommended)\n\nCode-Fundi uses Supabase-backed auth (`POST /v2/auth/authenticate`, `/v2/auth/verify`, `/v2/auth/resend`). OTP emails contain a **6-digit code** — magic links are not supported on this path.\n\n1. **Ask the human user for their email address.**\n2. Call **`code-fundi-auth-authenticate`** with:\n - `auth_mode`: `\"otp\"`\n - `email`: the user's email\n - `should_create_user`: `true` for a **new** account, `false` for a **returning** user\n3. Tell the user to check their inbox for a 6-digit code. The API may return `verification_required: true` and `api_key.key_state: \"agent_pending\"` until verification completes.\n4. **Ask the user for the 6-digit OTP** (human-in-the-loop — you cannot guess or bypass this step).\n5. Call **`code-fundi-auth-verify`** with the same `email` and the `token` (6 digits).\n6. On success, the MCP server **automatically configures the API key in memory** for all subsequent tool calls in this session.\n\nIf the code expired or was not received, call **`code-fundi-auth-resend`** with the same `email`, then repeat step 5.\n\n**Example dialogue:**\n\n```\nAgent: What email should I use to sign in to Code-Fundi?\nUser: dev@example.com\nAgent: [calls code-fundi-auth-authenticate] I've sent a 6-digit code to dev@example.com. Please paste it here.\nUser: 482913\nAgent: [calls code-fundi-auth-verify] You're signed in. I can now search and index your repositories.\n```\n\n### Password sign-in (alternative)\n\nFor existing accounts with a password, call **`code-fundi-auth-authenticate`** with `auth_mode: \"password\"`, the user's `email`, `should_create_user: false`, and the `password` parameter. The MCP client sends the password only in the `X-CodeFundi-Auth-Password` header (never in the JSON body). Production requires HTTPS. Returning users may receive an active API key immediately without a separate verify step.\n\n### After authentication\n\n- The API key is held **in memory** for the lifetime of the MCP server process. It is **not** persisted across IDE or MCP restarts.\n- Recommend the user add the key to their MCP config as `CODEFUNDI_API_KEY` so future sessions start authenticated.\n- A FREE-tier account and API key are created automatically on first signup.\n\n### Errors\n\n| HTTP status | What to do |\n|-------------|------------|\n| **401** Unauthorized | No valid key — run the OTP flow above, or set `CODEFUNDI_API_KEY` |\n| **429** Too many requests | Auth endpoints are rate-limited per IP; wait for `Retry-After` seconds, then retry |\n\n## Features\n\nEvery tool below is backed by the same codebase map: structural dependencies, call graph, and blast radius, indexed once and queried in milliseconds.\n\n- 🔍 **Semantic & grep code search** across your indexed codebase map\n- 🧠 **AI-powered research**: search plus AI analysis in a single call\n- 📦 **Repository management**: index, status, README, listing, public catalog\n- 🛰️ **Repository intelligence**: cross-repo dependency map, blueprint, Blast-Radius Guard (impact analysis before you merge)\n- 📄 **File documentation**: AI-generated docs for any indexed file\n- 📊 **Usage statistics**: query usage, activity, language breakdowns\n- 🔐 **Agent-driven authentication**: sign up/sign in via OTP without pre-configured keys\n- 💬 **AI chat & model insight**: direct conversation with Code-Fundi AI, model catalog, and per-tier limits\n\n## Quick Start\n\n### Install from npm (recommended)\n\nInstall the package (includes a pre-built `dist/`). The `code-fundi-mcp` binary is on your `PATH` when installed globally, or available via `npx` without cloning the repo:\n\n```bash\nnpm install -g @codefundi/code-fundi-mcp\n```\n\nOr add it to a project:\n\n```bash\nnpm install @codefundi/code-fundi-mcp\n```\n\n### Install from source (this repository)\n\n```bash\ngit clone https://github.com/Code-Fundi/code-fundi-mcp.git\ncd code-fundi-mcp\nnpm install\nnpm run build\n```\n\n### Configure\n\n**Option A — API key (fastest):** set your key as an environment variable:\n\n```bash\nexport CODEFUNDI_API_KEY=your_api_key_here\n```\n\n**Option B — no API key:** skip the env var and let the agent self-authenticate at runtime. See [Getting started for AI agents](#getting-started-for-ai-agents).\n\nZero-config MCP example (no `env` block):\n\n```json\n{\n \"mcpServers\": {\n \"code-fundi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@codefundi/code-fundi-mcp\"]\n }\n }\n}\n```\n\n### Use with Claude Desktop\n\nAfter a global install (`npm i -g @codefundi/code-fundi-mcp`), point MCP at the published binary (no path to `dist/index.js` required):\n\n```json\n{\n \"mcpServers\": {\n \"code-fundi\": {\n \"command\": \"@codefundi/code-fundi-mcp\",\n \"env\": {\n \"CODEFUNDI_API_KEY\": \"your_api_key_here\"\n }\n }\n }\n}\n```\n\nIf the binary is not on your `PATH`, use `npx` (downloads or uses the local package and runs the same entrypoint):\n\n```json\n{\n \"mcpServers\": {\n \"code-fundi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@codefundi/code-fundi-mcp\"],\n \"env\": {\n \"CODEFUNDI_API_KEY\": \"your_api_key_here\"\n }\n }\n }\n}\n```\n\n### Use with Cursor\n\nSame pattern as Claude: `command` plus optional `args` only, no manual path to the repo:\n\n```json\n{\n \"mcpServers\": {\n \"code-fundi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@codefundi/code-fundi-mcp\"],\n \"env\": {\n \"CODEFUNDI_API_KEY\": \"your_api_key_here\"\n }\n }\n }\n}\n```\n\nWhen developing **inside this repo**, you can run `npm run dev` or `npx tsx src/index.ts` without building first.\n\n### Development Mode\n\n```bash\nnpm run dev # Run with tsx (no build needed)\nnpx fastmcp inspect src/index.ts # Open MCP Inspector UI\nnpx fastmcp dev src/index.ts # Test with MCP CLI\n```\n\n## Tools Reference (27 tools)\n\nCovers the Code-Fundi **V2** API for codebase mapping and blast-radius analysis: search (including search-with-chat / research), repositories (list, index, status, readme, public catalog), repository intelligence (map, blueprint, radius), files, history, statistics, API keys, authentication, plus **Fundi chat** (`POST /v1/fundi/chat`) and the V2 model catalog / limits (`GET /v2/models`, `GET /v2/models/limits`).\n\n### Search\n\n| Tool | Description |\n|------|-------------|\n| `code-fundi-search` | Semantic and grep search across your indexed codebase map, with filters |\n| `code-fundi-research` | Search plus AI-synthesized analysis of matching code |\n\n### Repositories\n\n| Tool | Description |\n|------|-------------|\n| `code-fundi-list-repos` | List indexed repositories with pagination |\n| `code-fundi-index-repo` | Index a new GitHub repository into your codebase map |\n| `code-fundi-repo-status` | Check repository indexing status |\n| `code-fundi-repo-readme` | Get repository README documentation (deprecated, prefer blueprint) |\n| `code-fundi-list-public-repos` | Browse the global catalog of indexed public repositories (no key needed) |\n\n### Repository Intelligence\n\n| Tool | Description |\n|------|-------------|\n| `code-fundi-repo-map` | Cross-repository dependency map: how services and packages actually connect |\n| `code-fundi-repo-blueprint` | README plus dependency and convention overview (successor to repo-readme) |\n| `code-fundi-repo-radius` | Blast-Radius Guard: every file and function that breaks before you merge (PRO+) |\n\n### Files\n\n| Tool | Description |\n|------|-------------|\n| `code-fundi-list-files` | List files in a repository |\n| `code-fundi-file-docs` | Get AI-generated file documentation |\n\n### History\n\n| Tool | Description |\n|------|-------------|\n| `code-fundi-list-history` | List query history with filters |\n| `code-fundi-history-item` | Get full details of a history entry |\n| `code-fundi-conversation` | Get conversation thread messages |\n\n### Statistics\n\n| Tool | Description |\n|------|-------------|\n| `code-fundi-usage-stats` | Query-type usage breakdown |\n| `code-fundi-activity-stats` | Daily activity statistics |\n| `code-fundi-language-stats` | Programming language usage |\n\n### Authentication\n\n| Tool | Description |\n|------|-------------|\n| `code-fundi-auth-authenticate` | Start OTP/password auth flow (no key needed) |\n| `code-fundi-auth-verify` | Verify OTP code and obtain API key |\n| `code-fundi-auth-resend` | Resend OTP verification email |\n| `code-fundi-list-api-keys` | List API keys (masked) |\n| `code-fundi-regenerate-api-key` | Regenerate API key |\n| `code-fundi-disable-api-key` | Disable an API key by ID (`DELETE /v2/keys/{key_id}`) |\n\n### Chat & Models\n\n| Tool | Description |\n|------|-------------|\n| `code-fundi-chat` | Fundi AI chat (`POST /v1/fundi/chat`; streamed responses are collected to text) |\n| `code-fundi-list-models` | List the curated chat model catalog (`GET /v2/models`) |\n| `code-fundi-model-limits` | Get AI model limits and tier configuration (`GET /v2/models/limits`) |\n\n## Authentication\n\nTwo modes: **pre-configured API key** (`CODEFUNDI_API_KEY` in MCP config) or **agent-driven OTP/password auth** at runtime. Full step-by-step instructions, tool names, and error handling are in [Getting started for AI agents](#getting-started-for-ai-agents) at the top of this README.\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `CODEFUNDI_API_KEY` | No* | — | API key for authentication |\n| `CODEFUNDI_BASE_URL` | No | `https://api.codefundi.app` | API base URL override |\n\n\\* Required unless using agent-driven auth tools.\n\n## License\n\nMIT", "bytes": 11909, "sha": "e1d15559d470bc1c039940754f69e1f14d51eb6428eabf7857d5d8c7666ff783", "repo_slug": "code-fundi/code-fundi-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_felixwaweru_code_fundi_mcp_8f0fbe05/readme" }