code-fundi-mcp

Code Fundi

面向 AI Agent、团队和应用的代码库地图。

Code-Fundi MCP 服务

面向 Code-Fundi API 的生产级 Model Context Protocol (MCP) 服务：一个代码库地图和影响范围引擎，专为 AI 编码 Agent 打造。它支持任何兼容 MCP 的 AI 助手（Claude、Claude Code、Cursor、Windsurf、VS Code Copilot 等）通过自然语言搜索、研究、索引和扫描代码仓库，并在变更发布前查看它会导致哪些问题。

使用 FastMCP（TypeScript）构建，并通过 Zod 进行架构验证。

AI Agent 快速入门

如果你是 AI Agent（或正在配置 AI Agent），且未设置 CODEFUNDI_API_KEY，则必须先完成身份验证，才能使用搜索、仓库、聊天或其他需要身份验证的工具。身份验证工具（code-fundi-auth-*）无需预先配置密钥即可使用。

选择使用方式

情况	操作
在 MCP 配置中设置了 CODEFUNDI_API_KEY	可立即使用任意工具 — 服务会在每次请求中通过 X-API-Key 发送密钥
未配置 API 密钥	使用下方的 OTP 自助身份验证流程（推荐）或密码登录

零配置 MCP 设置（无 API 密钥）

无需设置 CODEFUNDI_API_KEY 即可启动 MCP 服务，并在运行时完成身份验证：

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

使用 OTP 自助完成身份验证（推荐）

Code-Fundi 使用由 Supabase 支持的身份验证（POST /v2/auth/authenticate、/v2/auth/verify、/v2/auth/resend）。OTP 邮件中包含一个 6 位数验证码 — 此流程不支持魔法链接。

1. 向用户询问其电子邮件地址。
2. 使用以下参数调用 code-fundi-auth-authenticate：
   • auth_mode："otp"
   • email：用户的电子邮件地址
   • should_create_user：新账户设为 true，已有账户设为 false
3. 告知用户查看收件箱并获取 6 位数验证码。在验证完成前，API 可能会返回 verification_required: true 和 api_key.key_state: "agent_pending"。
4. 向用户索取 6 位数 OTP（需要用户参与 — 你无法猜测或绕过此步骤）。
5. 使用相同的 email 和 token（6 位数）调用 code-fundi-auth-verify。
6. 验证成功后，MCP 服务会自动在内存中配置 API 密钥，供本次会话后续的所有工具调用使用。

如果验证码已过期或未收到，请使用相同的 email 调用 code-fundi-auth-resend，然后重复步骤 5。

对话示例：

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

密码登录（备选方式）

对于已有密码的账户，使用 auth_mode: "password"、用户的 email、should_create_user: false 和 password 参数调用 code-fundi-auth-authenticate。MCP 客户端仅通过 X-CodeFundi-Auth-Password 标头发送密码（绝不会放在 JSON 请求体中）。生产环境必须使用 HTTPS。已有账户的用户可能会立即获得有效的 API 密钥，无需单独执行验证步骤。

身份验证后

• API 密钥会在 MCP 服务进程的整个生命周期内保存在内存中。IDE 或 MCP 重启后，密钥不会保留。
• 建议用户将密钥添加到 MCP 配置中，作为 CODEFUNDI_API_KEY，以便后续会话启动时已完成身份验证。
• 首次注册时会自动创建 FREE 层级账户和 API 密钥。

错误

HTTP 状态码	处理方法
401 未授权	没有有效密钥——运行上述 OTP 流程，或设置 CODEFUNDI_API_KEY
429 请求过多	身份验证端点按 IP 限流；等待 Retry-After 秒后重试

功能

以下每个工具都由同一份代码库映射提供支持：结构依赖关系、调用图和影响范围只需索引一次，查询耗时仅为毫秒级。

• 🔍 语义搜索和 grep 代码搜索：搜索已索引的代码库映射
• 🧠 AI 驱动的研究：通过单次调用完成搜索和 AI 分析
• 📦 仓库管理：索引、状态、README、列表、公开目录
• 🛰️ 仓库智能分析：跨仓库依赖关系图、蓝图、影响范围防护（合并前进行影响分析）
• 📄 文件文档：为任意已索引文件生成 AI 文档
• 📊 使用统计：查询使用量、活动情况和语言分布
• 🔐 由 Agent 驱动的身份验证：通过 OTP 注册或登录，无需预先配置密钥
• 💬 AI 聊天与模型洞察：直接与 Code-Fundi AI 对话，查看模型目录和各层级限制

快速开始

从 npm 安装（推荐）

安装此软件包（包含预构建的 dist/）。全局安装后，code-fundi-mcp 二进制文件可通过 PATH 使用；也可以使用 npx，无需克隆仓库：

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

或者将其添加到项目中：

npm install @codefundi/code-fundi-mcp

从源代码安装（此仓库）

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

配置

选项 A — API 密钥（最快）： 将密钥设置为环境变量：

export CODEFUNDI_API_KEY=your_api_key_here

选项 B — 不使用 API 密钥： 跳过环境变量，让 Agent 在运行时自行完成身份验证。请参阅AI Agent 入门指南。

零配置 MCP 示例（没有 env 块）：

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

与 Claude Desktop 配合使用

全局安装（npm i -g @codefundi/code-fundi-mcp）后，将 MCP 指向已发布的二进制文件（无需指定 dist/index.js 的路径）：

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

如果二进制文件不在 PATH 中，请使用 npx（下载或使用本地软件包，并运行相同的入口点）：

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

与 Cursor 配合使用

与 Claude 的配置方式相同：只需设置 command 和可选的 args，无需手动指定仓库路径：

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

在此仓库内开发时，可以运行 npm run dev 或 npx tsx src/index.ts，无需先进行构建。

开发模式

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

工具参考（27 个工具）

涵盖 Code-Fundi V2 API 的代码库映射和影响范围分析：搜索（包括搜索并聊天／研究）、仓库（列表、索引、状态、README、公开目录）、仓库智能分析（映射、蓝图、影响范围）、文件、历史记录、统计信息、API 密钥、身份验证，以及 Fundi 聊天（POST /v1/fundi/chat）和 V2 模型目录／限制（GET /v2/models、GET /v2/models/limits）。

搜索

工具	描述
code-fundi-search	在已索引的代码库映射中进行语义搜索和 grep 搜索，并支持筛选
code-fundi-research	搜索并对匹配的代码进行 AI 综合分析

仓库

工具	描述
code-fundi-list-repos	分页列出已索引的仓库
code-fundi-index-repo	将新的 GitHub 仓库索引到代码库映射中
code-fundi-repo-status	检查仓库索引状态
code-fundi-repo-readme	获取仓库 README 文档（已弃用，建议使用蓝图）
code-fundi-list-public-repos	浏览已索引公开仓库的全局目录（无需密钥）

仓库洞察

工具	描述
code-fundi-repo-map	跨仓库依赖关系图：服务和软件包实际如何连接
code-fundi-repo-blueprint	README、依赖项和约定概览（repo-readme 的继任者）
code-fundi-repo-radius	影响范围防护：合并前找出所有会出问题的文件和函数（PRO+）

文件

工具	描述
code-fundi-list-files	列出仓库中的文件
code-fundi-file-docs	获取 AI 生成的文件文档

历史记录

工具	描述
code-fundi-list-history	按筛选条件列出查询历史记录
code-fundi-history-item	获取历史记录条目的完整详情
code-fundi-conversation	获取对话线程消息

统计信息

工具	描述
code-fundi-usage-stats	按查询类型划分的使用情况
code-fundi-activity-stats	每日活动统计信息
code-fundi-language-stats	编程语言使用情况

身份验证

工具	描述
code-fundi-auth-authenticate	启动 OTP/密码身份验证流程（无需密钥）
code-fundi-auth-verify	验证 OTP 代码并获取 API 密钥
code-fundi-auth-resend	重新发送 OTP 验证邮件
code-fundi-list-api-keys	列出 API 密钥（已屏蔽）
code-fundi-regenerate-api-key	重新生成 API 密钥
code-fundi-disable-api-key	按 ID 禁用 API 密钥（DELETE /v2/keys/{key_id}）

聊天与模型

工具	描述
code-fundi-chat	Fundi AI 聊天（POST /v1/fundi/chat；流式响应会汇总为文本）
code-fundi-list-models	列出精选聊天模型目录（GET /v2/models）
code-fundi-model-limits	获取 AI 模型限制和层级配置（GET /v2/models/limits）

身份验证

有两种模式：预配置 API 密钥（在 MCP 配置中设置 CODEFUNDI_API_KEY），或在运行时使用由 Agent 驱动的 OTP/密码身份验证。完整的分步说明、工具名称和错误处理方式，请参阅本 README 顶部的面向 AI Agent 的入门指南。

环境变量

变量	必需	默认值	描述
CODEFUNDI_API_KEY	否*	—	用于身份验证的 API 密钥
CODEFUNDI_BASE_URL	否	https://api.codefundi.app	API 基础 URL 覆盖值

* 除非使用由 Agent 驱动的身份验证工具，否则必需。

许可证

MIT