CodeAlive

CodeAlive MCP：面向项目的深度上下文引擎（尤其适用于大型代码库）

只需几秒钟，即可将 AI 助手连接到 CodeAlive 强大的代码理解平台！

此 MCP（Model Context Protocol）服务可让 Claude Code、Cursor、Claude Desktop、Continue、VS Code（GitHub Copilot）、Cline、Codex、OpenCode、SourceCraft Code Assistant、SourceCraft CLI、Zed、KodaCode、GigaCode、Qwen Code、Gemini CLI、Roo Code、Goose、Kilo Code、Windsurf、Kiro、Qoder、n8n 和 Amazon Q Developer 等 AI 客户端使用 CodeAlive 的高级语义代码搜索和代码库交互功能。

什么是 CodeAlive？

CodeAlive 是一款面向大型代码库的上下文引擎，由基于图的检索提供支持，并通过 MCP 提供服务。它让 Cursor、Claude Code、Codex 等 AI Agent 能够获取精准的代码库上下文，而不必盲目地读取文件。在我们的 RepoQA 基准测试中，CodeAlive + Qwen3.6 deep 以约低 25 倍的模型成本达到了前沿 Agent 的质量，而语义搜索将捕获的令牌数减少了 45%。

它就像 Context7，不过是针对你的（大型）代码库的。

它能让 AI 编码 Agent：

• 通过语义搜索更快找到相关代码
• 了解全局情况，不局限于孤立的文件
• 借助完整的项目上下文提供更好的回答
• 通过减少猜测降低成本并节省时间

🛠 可用工具

连接后，你将可以使用以下强大工具：

1. get_data_sources - 列出已编入索引的仓库和工作区
2. semantic_search - 对已编入索引的内容进行规范的语义搜索
3. grep_search - 在文件内容中进行精确的字面文本或正则表达式搜索，还可按字面内容匹配文件名/路径（即使文件内容中从未提及名称，也会返回 Form.xml 等文件），并为内容匹配项提供行级预览
4. get_repository_ontology - 获取所选仓库的仓库级概览
5. get_file_tree - 查看某个仓库的有限深度文件树
6. read_file - 读取相对于仓库的文件路径，可选择指定行范围
7. fetch_artifacts - 加载相关搜索结果的完整源内容（缺失或无法访问的标识符会反馈给你，不会被静默丢弃）
8. get_artifact_relationships - 展开某个内容项的调用图、继承关系和引用关系
9. get_artifact_query_schema - 查看 ArtifactQuery 支持的实体、字段和示例
10. query_artifact_metadata - 对所选仓库运行只读元数据分析
11. chat - 无状态、速度较慢的综合代码库问答；仅在明确请求时调用

🎯 使用示例

完成设置后，可以尝试向 AI 助手发送以下指令：

• “显示所有可用仓库” → 使用 get_data_sources
• “查找用户服务中的身份验证代码” → 使用 semantic_search
• “查找匹配 JWT 令牌的精确正则表达式” → 使用 grep_search
• “解释此代码库中的支付流程如何运作” → 通常先使用 semantic_search/grep_search，然后视情况使用 chat

对于大多数 Agent，semantic_search 和 grep_search 应作为默认工具。chat 是速度较慢的无状态综合备用方案，耗时可能远长于检索；如果 Agent 能通过本体、搜索、获取/读取、关系、ArtifactQuery 和本地文件读取执行多步工作流，通常就没有必要使用它。如果你的 Agent 支持子 Agent，最可靠的方式是委派一个专注的子 Agent，先协调使用 semantic_search 和 grep_search。

📚 Agent 技能

为获得更佳体验，请在 MCP 服务旁安装 CodeAlive Agent 技能。MCP 服务让你的 Agent 能够使用 CodeAlive 的工具；该技能则教会它如何运用最佳工作流和查询模式，高效地使用这些工具。

对于大多数 Agent（Cursor、Copilot、Gemini CLI、Codex 和其他 30 多种）——安装该技能：

npx skills add CodeAlive-AI/codealive-skills@codealive-context-engine

对于 Claude Code——安装插件（推荐），其中包含该技能和针对 Claude 的增强功能：

/plugin marketplace add CodeAlive-AI/codealive-skills
/plugin install codealive@codealive-marketplace

目录

• Agent 技能
• 快速入门（远程）
• AI 客户端集成
• 进阶：本地开发
• 社区插件
• HTTP 部署（自托管与云端）
• Windows 与 WSL
• 可用工具
• 使用示例
• 故障排除
• 发布到 MCP 注册表
• 许可证

🚀 快速入门（远程）

最快的入门方式——无需安装！我们的远程 MCP 服务位于 https://mcp.codealive.ai/api，可让你立即使用 CodeAlive 的功能。

第 1 步：获取 API 密钥

1. 在 https://app.codealive.ai/ 注册
2. 前往 MCP 与 API
3. 点击 “+ 创建 API 密钥”
4. 立即复制 API 密钥——之后将无法再次查看！

第 2 步：打开客户端指南

在 MCP 集成指南中选择你的客户端，并按照其中最新的设置说明操作。

🚀 快速入门（Agent 安装）

你可以让 AI Agent 为你安装 CodeAlive MCP 服务。

1. 将以下提示词复制并粘贴到你的 AI Agent 中。请勿在提示词中包含 API 密钥：

Add the CodeAlive MCP server by following the guide for my client at https://docs.codealive.ai/integrations/mcp

Prefer the Remote HTTP option when available. Do not ask me to paste an API key into chat. When the key is needed, ask me to create a CodeAlive API key and copy it to my clipboard. After I confirm, insert it directly from the clipboard into the required secure configuration without displaying, echoing, logging, or exposing it in command arguments, command output, or model context. If you cannot safely use the clipboard without exposing the value, tell me exactly where to paste it myself.

然后允许执行。

2. 重启 AI Agent。

🤖 AI 客户端集成

客户端专属配置维护在 CodeAlive 文档中，以确保文件路径、传输方式和身份验证说明始终保持最新。

从这里开始：MCP 集成指南

客户端	设置指南
Claude Code	Claude Code
Claude Desktop	Claude Desktop
Cursor	Cursor
Visual Studio Code	VS Code
Windsurf	Windsurf
Cline	Cline
Continue	Continue
Codex	Codex
Gemini CLI	Gemini CLI
Amazon Q Developer	Amazon Q
OpenCode	OpenCode
SourceCraft Code Assistant 和 SourceCraft CLI	SourceCraft
Zed	Zed
ChatGPT	ChatGPT
OpenClaw	OpenClaw
KodaCode、GigaCode、Roo Code、Goose、Kilo Code、Qwen Code、Kiro、Qoder、JetBrains AI Assistant、n8n 等	其他 Agent

对于未列出的客户端，请使用以下通用连接信息，并根据该客户端的 MCP 配置格式进行调整：

• 端点： https://mcp.codealive.ai/api
• 传输方式： Streamable HTTP
• 身份验证标头： Authorization: Bearer YOUR_API_KEY_HERE

对于私有部署，请将端点替换为服务器的 /api URL。请参阅自托管了解部署说明。

连接服务只是设置工作的一半。 如果项目说明没有要求编码 Agent 优先使用 CodeAlive，它们可能会继续使用内置搜索。可直接使用的 AGENTS.md、CLAUDE.md 和客户端专属指令文件规则见指导编码 Agent。

---

🔧 高级：本地开发

适用于希望自定义或为 MCP 服务做出贡献的开发者。

前置条件

• Python 3.11+
• uv（推荐）或 pip

安装

# Clone the repository
git clone https://github.com/CodeAlive-AI/codealive-mcp.git
cd codealive-mcp

# Setup with uv (recommended)
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e .

# Or setup with pip
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate  
pip install -e .

本地服务配置

在本地安装服务后，将 MCP 客户端指向 .venv/bin/python，并将 src/codealive_mcp_server.py 作为第一个参数，同时在进程环境中提供 CODEALIVE_API_KEY。客户端专属配置请参阅 MCP 集成指南。

在本地运行 HTTP 服务

# Start local HTTP server
export CODEALIVE_API_KEY="your_api_key_here"
python src/codealive_mcp_server.py --transport http --host localhost --port 8000

# Test health endpoint
curl http://localhost:8000/health

HTTP 传输会验证 Host 和浏览器的 Origin 标头。环回主机 （localhost、127.0.0.1、::1）无需额外配置即可使用。对于 共享主机名，请配置精确的允许列表：

export CODEALIVE_MCP_ALLOWED_HOSTS="mcp.codealive.yourcompany.com"
# Only for browser callers; ordinary MCP clients do not send Origin.
export CODEALIVE_MCP_ALLOWED_ORIGINS="https://mcp.codealive.yourcompany.com"
python src/codealive_mcp_server.py --transport http --host 0.0.0.0 --port 8000

对应的可重复 CLI 选项为 --allowed-host 和 --allowed-origin。面向互联网的服务请勿使用 *。

测试本地安装

完成更改后，可快速验证一切是否正常：

# Match pyproject.toml exactly; older uv versions reject the locked setup.
uv --version  # expected: uv 0.11.28
uv sync --locked --extra test

# Install the repository pre-push dependency audit once per clone
./scripts/setup-hooks.sh

# Quick smoke test (recommended)
make smoke-test

# Or run directly
python smoke_test.py

# With your API key for full testing
CODEALIVE_API_KEY=your_key python smoke_test.py

# Run unit tests
make unit-test

# Run all tests
make test

# Equivalent direct locked test run
uv run pytest src/tests/ -q

冒烟测试会验证：

• 服务能否正常启动并连接
• 是否注册了所有工具
• 每个工具是否能正常响应
• 参数验证是否有效
• 运行时间约为 5 秒

---

🌐 社区插件

• Gemini CLI — CodeAlive 扩展
• Gemini CLI 设置指南

---

🚢 HTTP 部署（自托管与云端）

将 MCP 服务部署为 HTTP 服务，供整个团队访问，或与自托管的 CodeAlive 实例集成。

部署选项

CodeAlive MCP 服务可以使用 Docker 部署为 HTTP 服务。这样，多个 AI 客户端便可连接到同一个共享实例，并与自托管的 CodeAlive 部署集成。

Docker Compose（推荐）

根据我们的示例创建 docker-compose.yml 文件：

# Download the example
curl -O https://raw.githubusercontent.com/CodeAlive-AI/codealive-mcp/main/docker-compose.example.yml
mv docker-compose.example.yml docker-compose.yml

# Edit configuration (see below)
nano docker-compose.yml

# Start the service
docker compose up -d

# Check health
curl http://localhost:8000/health

配置选项：

1. 使用 CodeAlive Cloud（默认）：

   • 移除 CODEALIVE_BASE_URL 环境变量（默认使用 https://app.codealive.ai）
   • 对于支持 OAuth 的远程客户端，只需配置 https://mcp.codealive.ai/api，并在系统提示时 完成浏览器登录
   • 仍支持现有的 API 密钥客户端，使用 Authorization: Bearer YOUR_KEY

2. 使用自托管的 CodeAlive：

   • 将 CODEALIVE_BASE_URL 设置为你的 CodeAlive 实例 URL（例如，https://codealive.yourcompany.com）
   • 将 CODEALIVE_MCP_ALLOWED_HOSTS 设置为客户端访问此 MCP 服务时使用的确切主机名
   • 客户端必须通过 Authorization: Bearer YOUR_KEY 标头提供 API 密钥

完整配置模板请参阅 docker-compose.example.yml。

例如，目前的 Codex 和 Claude Code 客户端可以使用浏览器 OAuth，而无需存储 CodeAlive API 密钥：

codex mcp add codealive --url https://mcp.codealive.ai/api
codex mcp login codealive

claude mcp add --transport http codealive https://mcp.codealive.ai/api
# Start Claude Code and run /mcp to authenticate.

Cursor 和 OpenCode 也会根据同一个 URL 自动发现 OAuth。如果它们的 UI 未自动提示，请使用 cursor-agent mcp login codealive 或 opencode mcp auth codealive。API 密钥配置仍可作为兼容选项使用。

OAuth 2.1 部署配置

远程 HTTP 部署可以启用浏览器授权，同时在部署过程中继续支持旧版 API 密钥客户端。OAuth 模式会发布 MCP 受保护资源元数据，验证与确切的颁发者和资源绑定的 JWT，并将其交换为单独的短期工具 API 令牌。传入的 MCP 持有者令牌绝不会转发到下游。

环境变量	用途
CODEALIVE_MCP_OAUTH_ENABLED=true	为 HTTP 传输启用 OAuth 验证和 MCP 授权发现
CODEALIVE_OAUTH_ISSUER	精确的 OpenIddict 颁发者，末尾带斜杠
CODEALIVE_MCP_RESOURCE	精确的公共 MCP 资源 URL；其路径也是 HTTP MCP 路径
CODEALIVE_TOOL_API_RESOURCE	下游受众；默认为 urn:codealive:tool-api
CODEALIVE_OAUTH_INTERNAL_CLIENT_ID	仅用于令牌交换的机密资源服务器客户端
CODEALIVE_OAUTH_INTERNAL_CLIENT_SECRET	此内部客户端必需的密钥；缺少时启动会以失败关闭

授权服务器和 MCP 服务的值必须完全一致。在 CodeAlive Web.Server 中，对应的设置位于 McpOAuth 下（Enabled、Issuer、Resource、 ToolApiResource、InternalClientId 和 InternalClientSecret）。在副本和重启期间持久保存 Web.Server Data Protection 密钥环以及 OpenIddict 签名/加密证书。若要在不中断服务的情况下轮换内部凭据，请为新凭据分配新的客户端 ID，部署 Web.Server，同时配置当前的和 PreviousInternalClientId/PreviousInternalClientSecret，将 MCP 副本滚动更新为新的当前凭据对，然后移除旧凭据对。Web.Server 会有意选择启动失败，而不是在现有客户端 ID 下原地更改密钥。 在同一轮部署中启用 Web.Server 和 MCP 标志；只启用一方并非有效的稳定状态。API 密钥凭据仍遵循其明确的旧版语法，OAuth 验证失败后绝不会将其用作回退方式。

将 MCP 客户端连接到已部署的实例

使用与 CodeAlive Cloud 相同的通用连接详情，将端点替换为你的部署的 /api URL：

• 端点： https://your-server.example.com/api
• 传输方式： Streamable HTTP
• 身份验证请求头： Authorization: Bearer YOUR_API_KEY_HERE

有关确切的配置格式，请打开相关的客户端集成指南。

🪟 Windows 和 WSL

Windows 和 WSL 设置请参阅客户端专属文档：

• Claude Code
• Claude Desktop
• 所有 MCP 集成指南
• 故障排除

对于在 WSL2 中运行的自托管服务，Windows 客户端必须能够访问服务的 /api 端点。在受支持的 Windows 11 版本上使用镜像网络，或通过 WSL2 虚拟机地址连接。

🐞 故障排除

快速诊断

1. 测试托管服务：

   curl https://mcp.codealive.ai/health
   

2. 检查你的 API 密钥：

   curl -H "Authorization: Bearer YOUR_API_KEY" https://app.codealive.ai/api/v1/data_sources
   

3. 启用调试日志： 在本地服务参数中添加 --debug

常见问题

• “Connection refused” → 检查互联网连接
• “401 Unauthorized” → 确认你的 API 密钥
• “No repositories found” → 在 CodeAlive 控制面板中检查 API 密钥权限
• 客户端专属日志 → 查看你的 AI 客户端文档，了解 MCP 日志

Windows / WSL 问题

• WSL 中出现 docker: command not found → 为你的发行版启用 Docker Desktop WSL 集成（Settings → Resources → WSL integration），或使用完整路径 /usr/bin/docker
• npx/python 出现 ENOENT 或 spawn error → 非交互式 WSL Shell 不会继承 nvm/pyenv 路径。在 MCP 配置中使用绝对路径
• WSL2 中连接自托管服务时出现 Connection refused → WSL2 使用 NAT 网络；Windows 和 WSL2 中的 localhost 不同。在 .wslconfig 中启用镜像网络，或使用 WSL2 虚拟机 IP（hostname -I）
• Claude Desktop 无法连接到 WSL MCP 服务 → Claude Desktop 不支持 WSL 子进程启动。请使用 Remote HTTP（https://mcp.codealive.ai/api）、Docker Desktop 或 wsl.exe 代理模式（参见 Windows 和 WSL 部分）

获取帮助

• 📧 电子邮件：[email protected]
• 🐛 问题反馈：GitHub Issues

---

📦 发布到 MCP Registry

维护者请参阅 DEPLOYMENT.md，了解如何向 MCP Registry 发布新版本。

---

隐私政策

CodeAlive 会处理你通过此扩展发送的代码仓库和查询，以提供语义搜索和代码库分析。有关完整的隐私详情，请参阅 CodeAlive 隐私政策。

---

📄 许可证

MIT License — 详情请参阅 LICENSE 文件。

---

准备好为你的 AI 助手注入强大的代码理解能力了吗？
立即开始 →