Back to Directory/Developer Tools

io.github.FelixWaweru/code-fundi-mcp

CodeFundi MCP server for codebase mapping and blast-radius analysis.

Developer ToolsTypeScriptv0.1.4
View on GitHub

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

SituationAction
CODEFUNDI_API_KEY is set in MCP configUse any tool immediately — the server sends it as X-API-Key on every request
No API key configuredRun the OTP self-auth flow below (recommended) or password sign-in

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:
    • auth_mode: "otp"
    • email: the user's email
    • should_create_user: true for a new account, false for a returning user
  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

HTTP statusWhat to do
401 UnauthorizedNo valid key — run the OTP flow above, or set CODEFUNDI_API_KEY
429 Too many requestsAuth endpoints are rate-limited per IP; wait for Retry-After seconds, then retry

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

ToolDescription
code-fundi-searchSemantic and grep search across your indexed codebase map, with filters
code-fundi-researchSearch plus AI-synthesized analysis of matching code

Repositories

ToolDescription
code-fundi-list-reposList indexed repositories with pagination
code-fundi-index-repoIndex a new GitHub repository into your codebase map
code-fundi-repo-statusCheck repository indexing status
code-fundi-repo-readmeGet repository README documentation (deprecated, prefer blueprint)
code-fundi-list-public-reposBrowse the global catalog of indexed public repositories (no key needed)

Repository Intelligence

ToolDescription
code-fundi-repo-mapCross-repository dependency map: how services and packages actually connect
code-fundi-repo-blueprintREADME plus dependency and convention overview (successor to repo-readme)
code-fundi-repo-radiusBlast-Radius Guard: every file and function that breaks before you merge (PRO+)

Files

ToolDescription
code-fundi-list-filesList files in a repository
code-fundi-file-docsGet AI-generated file documentation

History

ToolDescription
code-fundi-list-historyList query history with filters
code-fundi-history-itemGet full details of a history entry
code-fundi-conversationGet conversation thread messages

Statistics

ToolDescription
code-fundi-usage-statsQuery-type usage breakdown
code-fundi-activity-statsDaily activity statistics
code-fundi-language-statsProgramming language usage

Authentication

ToolDescription
code-fundi-auth-authenticateStart OTP/password auth flow (no key needed)
code-fundi-auth-verifyVerify OTP code and obtain API key
code-fundi-auth-resendResend OTP verification email
code-fundi-list-api-keysList API keys (masked)
code-fundi-regenerate-api-keyRegenerate API key
code-fundi-disable-api-keyDisable an API key by ID (DELETE /v2/keys/{key_id})

Chat & Models

ToolDescription
code-fundi-chatFundi AI chat (POST /v1/fundi/chat; streamed responses are collected to text)
code-fundi-list-modelsList the curated chat model catalog (GET /v2/models)
code-fundi-model-limitsGet AI model limits and tier configuration (GET /v2/models/limits)

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

VariableRequiredDefaultDescription
CODEFUNDI_API_KEYNo*—API key for authentication
CODEFUNDI_BASE_URLNohttps://api.codefundi.appAPI base URL override

* Required unless using agent-driven auth tools.

License

MIT

Installation

Source-derived launch command. Check the maintainer’s required arguments and credentials before running:

bash
npx -y @codefundi/code-fundi-mcp

Set up in your AI client

Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.

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

Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.

Claude Desktop setup reference

Package

@codefundi/code-fundi-mcpnpm

Compatible MCP Clients

io.github.FelixWaweru/code-fundi-mcp works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.

  • Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.
  • Cursor~/.cursor/mcp.jsonRestart Cursor for changes to take effect.
  • VS Code.vscode/mcp.jsonReload VS Code window for changes to take effect.
  • Windsurf~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect.
  • Claude Code.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.

Learn More

Webflow MCP Server: Connect Claude Code and Review CMS AccessUse the current /mcp endpoint and inspect a known collection first. Learn when the Designer Bridge App is needed and how to review agent changes.Read articleOpenCode MCP Server Setup: Add Any MCP to Your TerminalOpenCode doesn't lock you into one AI provider, and it doesn't lock you into one MCP transport either. This guide covers the real opencode.json config, the exact JSON keys for local and remote servers, and which MCPFind-listed servers actually make sense in a terminal workflow.Read articleGitHub vs GitLab MCP: Connections and AccessUse the server for the platform holding your work. Compare account access and a real repository task before expanding permissions or changing hosts.Read article