Code Fundi

The Codebase Map for AI Agents, Teams and Applications.

Code-Fundi MCP Server

A production-grade Model Context Protocol (MCP) server for the Code-Fundi 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.

Built with FastMCP (TypeScript) and Zod for schema validation.

Getting started for AI agents

If 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.

Which path to use

Zero-config MCP setup (no API key)

You can start the MCP server without `CODEFUNDI_API_KEY` and authenticate at runtime:

{
  "mcpServers": {
    "code-fundi": {
      "command": "npx",
      "args": ["-y", "@codefundi/code-fundi-mcp"]
    }
  }
}

Self-authenticate with OTP (recommended)

Code-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.

1. Ask the human user for their email address.

2. Call `code-fundi-auth-authenticate` with:

3. 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.

4. Ask the user for the 6-digit OTP (human-in-the-loop — you cannot guess or bypass this step).

5. Call `code-fundi-auth-verify` with the same `email` and the `token` (6 digits).

6. On success, the MCP server automatically configures the API key in memory for all subsequent tool calls in this session.

If the code expired or was not received, call `code-fundi-auth-resend` with the same `email`, then repeat step 5.

Example dialogue:

Agent: What email should I use to sign in to Code-Fundi?
User:  dev@example.com
Agent: [calls code-fundi-auth-authenticate] I've sent a 6-digit code to dev@example.com. Please paste it here.
User:  482913
Agent: [calls code-fundi-auth-verify] You're signed in. I can now search and index your repositories.

Password sign-in (alternative)

For 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.

After authentication

• The API key is held in memory for the lifetime of the MCP server process. It is not persisted across IDE or MCP restarts.
• Recommend the user add the key to their MCP config as `CODEFUNDI_API_KEY` so future sessions start authenticated.
• A FREE-tier account and API key are created automatically on first signup.

Errors

Features

Every tool below is backed by the same codebase map: structural dependencies, call graph, and blast radius, indexed once and queried in milliseconds.

• 🔍 Semantic & grep code search across your indexed codebase map
• 🧠 AI-powered research: search plus AI analysis in a single call
• 📦 Repository management: index, status, README, listing, public catalog
• 🛰️ Repository intelligence: cross-repo dependency map, blueprint, Blast-Radius Guard (impact analysis before you merge)
• 📄 File documentation: AI-generated docs for any indexed file
• 📊 Usage statistics: query usage, activity, language breakdowns
• 🔐 Agent-driven authentication: sign up/sign in via OTP without pre-configured keys
• 💬 AI chat & model insight: direct conversation with Code-Fundi AI, model catalog, and per-tier limits

Quick Start

Install from npm (recommended)

Install 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:

npm install -g @codefundi/code-fundi-mcp

Or add it to a project:

npm install @codefundi/code-fundi-mcp

Install from source (this repository)

git clone https://github.com/Code-Fundi/code-fundi-mcp.git
cd code-fundi-mcp
npm install
npm run build

Configure

Option A — API key (fastest): set your key as an environment variable:

export CODEFUNDI_API_KEY=your_api_key_here

Option B — no API key: skip the env var and let the agent self-authenticate at runtime. See Getting started for AI agents.

Zero-config MCP example (no `env` block):

{
  "mcpServers": {
    "code-fundi": {
      "command": "npx",
      "args": ["-y", "@codefundi/code-fundi-mcp"]
    }
  }
}

Use with Claude Desktop

After a global install (`npm i -g @codefundi/code-fundi-mcp`), point MCP at the published binary (no path to `dist/index.js` required):

{
  "mcpServers": {
    "code-fundi": {
      "command": "@codefundi/code-fundi-mcp",
      "env": {
        "CODEFUNDI_API_KEY": "your_api_key_here"
      }
    }
  }
}

If the binary is not on your `PATH`, use `npx` (downloads or uses the local package and runs the same entrypoint):

{
  "mcpServers": {
    "code-fundi": {
      "command": "npx",
      "args": ["-y", "@codefundi/code-fundi-mcp"],
      "env": {
        "CODEFUNDI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Use with Cursor

Same pattern as Claude: `command` plus optional `args` only, no manual path to the repo:

{
  "mcpServers": {
    "code-fundi": {
      "command": "npx",
      "args": ["-y", "@codefundi/code-fundi-mcp"],
      "env": {
        "CODEFUNDI_API_KEY": "your_api_key_here"
      }
    }
  }
}

When developing inside this repo, you can run `npm run dev` or `npx tsx src/index.ts` without building first.

Development Mode

npm run dev                          # Run with tsx (no build needed)
npx fastmcp inspect src/index.ts    # Open MCP Inspector UI
npx fastmcp dev src/index.ts        # Test with MCP CLI

Tools Reference (27 tools)

Covers 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`).

Search

Repositories

Repository Intelligence

Files

History

Statistics

Authentication

Chat & Models

Authentication

Two 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 at the top of this README.

Environment Variables

\* Required unless using agent-driven auth tools.

License

MIT