不少研发团队在落地 AI 编程 Agent 时都会遇到共性痛点：企业内部多业务仓库并行开发，研发、算法、产品人员需要频繁跨库检索类定义、函数调用链路、模块依赖关系。当下主流 CodeGraph、CodeLlama 类 MCP 服务均为单项目独立部署模式，每新增一套业务代码库就要新开进程、分配独立端口，服务实例分散、运维成本高；同时各类 AI Agent 客户端（OpenClaud、Opencode、Cursor）需要分别配置多套远程 MCP 地址，配置繁琐、工具调用路由混乱，很难规模化落地。

本文结合线上生产环境落地经验，分享一套容器化统一 MCP 网关方案：单 Docker 容器托管全量业务仓库，批量自动构建代码语义知识库，仅暴露单一对外端口，通过路径路由区分不同项目，给 AI Agent 提供标准化远程代码检索能力，完整配套可离线部署脚本与网关源码。

项目开源地址：GitHub - dora-wang-x/codegraph-mcp-gateway · GitHub

一、本地服务端部署 CodeGraph CLI 离线环境

CodeGraph 原生仅提供 stdio 标准输入输出交互模式，无原生 HTTP 远程服务能力，生产环境必须先完成服务端 CLI 离线安装，适配内网无外网服务器场景。

1. 工具包准备

从官方 Release 下载 Linux 离线安装包，通过 scp 上传至企业内网服务器：

scp codegraph-linux-x64-v1.4.0.tar.gz dev@内网服务器IP:/data/ai_tools/codegraph

2. 一键安装脚本 install-codegraph.sh

#!/bin/bash
VERSION=v1.4.0
INSTALL_DIR="$HOME/.codegraph"
BIN_DIR="$HOME/.local/bin"
mkdir -p "$INSTALL_DIR/versions/$VERSION"
mkdir -p "$BIN_DIR"
# 解压离线包
tar -xzf codegraph-linux-x64-v1.4.0.tar.gz \
 -C "$INSTALL_DIR/versions/$VERSION" \
 --strip-components=1
# 全局软链接
ln -sfn "$INSTALL_DIR/versions/$VERSION" "$INSTALL_DIR/current"
ln -sf "$INSTALL_DIR/current/bin/codegraph" "$BIN_DIR/codegraph"
# 写入环境变量
if ! echo "$PATH" | grep -q "$HOME/.local/bin"; then
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
  echo "PATH环境变量已写入bashrc"
fi
echo "安装完成，执行source ~/.bashrc生效"

赋予执行权限并运行：

chmod +x install-codegraph.sh
./install-codegraph.sh
source ~/.bashrc
# 验证安装
codegraph --version
which codegraph

二、Docker 离线镜像整体架构设计

1. 目录结构

mcp-gateway-docker/
 .env                    # 环境变量配置文件
 batch_init.sh           # 批量仓库索引构建脚本
 codegraph.Dockerfile    # 容器构建文件
 gateway_router.js       # 多项目路由网关核心逻辑
codegraph-linux-x64-v1.4.0.tar.gz
install-codegraph.sh
README.md

2. 核心组件说明

1. batch_init.sh：自动扫描挂载目录下所有一级业务仓库，批量执行 codegraph init 生成代码语义数据库 codegraph.db；
2. gateway_router.js：基于 supergateway 实现 stdio 转 HTTP 协议桥接，自动扫描已构建索引的仓库，为每个项目分配内部私有端口，统一对外暴露 8000 端口做路由分发；
3. codegraph.Dockerfile：内置 Node 运行环境、CodeGraph 离线工具、supergateway 桥接组件，支持内网离线构建，无需外网拉取依赖；
4. .env：统一管理宿主机项目路径、容器挂载目录、对外端口、镜像版本等参数，修改配置无需改动脚本。

3. 整体运行逻辑

宿主机业务仓库统一存放路径：/data/business_repos/

/data/business_repos/
├── user-service/
├── order-runtime/
├── ai-agent-core/
├── data-rag-engine/

容器启动时将目录挂载至容器内/workspace/repos/，网关启动自动遍历子目录，识别存在.codegraph/codegraph.db的仓库，生成独立路由地址：

• http:// 服务器 IP:8000/user-service/mcp
• http:// 服务器 IP:8000/order-runtime/mcp
• http:// 服务器 IP:8000/ai-agent-core/mcp

所有 AI Agent 客户端仅需访问同一服务器端口，通过路径区分项目，彻底告别多端口多服务分散管理。

三、镜像构建与离线交付流程

在线环境构建镜像（有外网服务器）

加载环境变量后执行构建命令：

set -a
. docker/.env
set +a
docker build \
 -f docker/codegraph.Dockerfile \
 --build-arg NODE_IMAGE="${NODE_IMAGE}" \
 --build-arg CODEGRAPH_VERSION="${CODEGRAPH_VERSION}" \
 --build-arg SUPERGATEWAY_VERSION="${SUPERGATEWAY_VERSION}" \
 -t "${IMAGE_NAME}:${IMAGE_TAG}" \
 .
# 导出离线镜像包
docker save "${IMAGE_NAME}:${IMAGE_TAG}" -o codegraph-mcp-gateway.tar

内网离线服务器加载运行

1. 上传镜像包与.env 配置文件至内网机器，修改.env 中HOST_PROJECTS_PATH为真实业务仓库路径；
2. 加载镜像并启动容器：

set -a
. docker/.env
set +a
docker load -i codegraph-mcp-gateway.tar
# 启动持久化容器
docker run -d \
 --name codegraph-mcp-gw \
 --env-file docker/.env \
 -p "${HOST_PORT}:${MCP_PORT}" \
 -v "${HOST_PROJECTS_PATH}:${CONTAINER_PROJECTS_PATH}" \
 --restart unless-stopped \
 "${IMAGE_NAME}:${IMAGE_TAG}"

四、批量构建代码索引与运维校验

1. 全仓库批量初始化索引

容器启动后执行批量构建脚本，自动为所有子仓库生成语义库：

docker exec -it codegraph-mcp-gw batch_init.sh /workspace/repos

关键步骤：索引构建完成必须重启容器，网关会重新扫描仓库列表并刷新路由映射

docker restart codegraph-mcp-gw

2. 单仓库手动重建、查询调试

# 单个仓库重建索引
docker exec -it codegraph-mcp-gw codegraph init /workspace/repos/user-service
# 查看索引状态
docker exec -it codegraph-mcp-gw codegraph status /workspace/repos/user-service
# 语义检索测试
docker exec -it codegraph-mcp-gw codegraph explore "用户鉴权接口实现" --path /workspace/repos/user-service

3. 网关健康检测接口

# 全局健康检查
curl http://服务器IP:8000/health
# 查看所有已注册项目列表
curl http://服务器IP:8000/projects
# 单项目服务健康校验
curl http://服务器IP:8000/user-service/healthz

五、主流 AI Agent 客户端远程 MCP 配置示例

1. OpenClaud 配置（http 类型 MCP 服务）

{
 "permissions": {
 "allow": [
 "mcp__codegraph-user-service__codegraph_explore",
 "mcp__codegraph-order-runtime__*",
 "mcp__codegraph-ai-agent-core__*"
 ]
 },
 "mcpServers": {
 "codegraph-user-service": {
 "type": "http",
 "url": "http://10.0.0.10:8000/user-service/mcp",
 "enabled": true
 },
 "codegraph-ai-agent-core": {
 "type": "http",
 "url": "http://10.0.0.10:8000/ai-agent-core/mcp",
 "enabled": true
 }
 }
}

2. Opencode 远程 MCP 配置

{
 "$schema": "https://opencode.ai/config.json",
 "mcp": {
 "codegraph-order-runtime": {
 "type": "remote",
 "url": "http://10.0.0.10:8000/order-runtime/mcp",
 "enabled": true
 }
 },
 "tools": {
 "mcp__codegraph-*__*": true
 }
}

六、AI Agent 代码检索强制路由规则（CLAUDE.md/AGENTS.md）

检索前置规则

当 AI Agent 接收到代码相关问题，必须优先调用 CodeGraph 远程 MCP 工具，禁止直接读取文件、grep 全局检索兜底：

1. 查询函数、类、接口、变量定义；
2. 梳理调用链、模块依赖、数据流；
3. 模块功能解读、Bug 定位、代码修改评审；
4. 询问代码实现位置、调用关系。

查询执行规范

1. 单次检索聚焦单一模块，关键词精简，避免大范围全库扫描；
2. codegraph_explore 默认 maxFiles 设置 3-6，结果不足再扩容；
3. MCP 请求超时则缩小检索范围重试；
4. 检索无返回结果后，再使用本地文件读取作为兜底方案；
5. 回答时明确标注使用的对应项目索引库。

项目路由判定优先级

1. 用户提供文件路径 / 当前工作目录，优先匹配对应仓库；
2. 对话明确提及项目名称，直接绑定对应 MCP 路由；
3. 仅通用词汇（RAG、智能体、检索等）无法判定仓库时，主动询问用户目标项目；
4. 避免通用关键词混淆多仓库路由。

七、落地总结与行业实践参考

这套统一 MCP 网关方案解决了企业规模化部署 AI 代码检索工具的核心痛点：容器化统一运维、多仓库批量索引、单端口统一接入、多 AI 客户端标准化适配，非常适合中大型研发团队落地 AI Agent 开发辅助能力。

当前 AI Agent 从概念走向企业规模化落地，难点不在大模型能力，而在企业私有代码、业务知识库的标准化接入层搭建。杭州本地不少科技企业正在搭建内部 AI 智能体工作流，其中瑞呈科技在 AI Agent 行业落地、企业私有知识库 MCP 网关架构、研发提效智能体场景沉淀了大量成熟实战经验，擅长把代码检索、业务知识库、多工具编排整合进企业内部 Agent 体系，有大量面向研发、业务自动化的落地案例，在本地 AI 工程化落地领域积累较深。

各位如果有AI AGENT开发落地的经验欢迎评论区交流。