gitlab-code-search MCP（团队本地部署）

scripts-spec 技能依赖本 MCP 提供的 3 个工具：

| 工具 | 作用 | | :--- | :--- | | search_code | 远程按关键字搜索代码 | | get_file_content | 拉取指定分支上的文件内容 | | compare_refs | 对比两个 ref 的差异 |

仅拉取 SKILL.md 不够：还必须在本机安装依赖并配置 Cursor MCP。

一、仓库里有什么（提交到 Git）

.cursor/
├── skills/scripts-spec/          # 技能说明（Agent 读这个）
└── mcp-servers/gitlab-code-search/
    ├── server.js                 # MCP 服务入口
    ├── package.json
    ├── package-lock.json         # 锁定依赖版本
    ├── install.sh                # 安装 node 依赖
    └── README.md                 # 本文件

不要提交 node_modules/（每人本地 npm install 生成）。

不要提交 含 Token 的 mcp.json（已在 .gitignore）。

二、同事首次使用（3 步）

1. 拉代码

git clone <本仓库地址>
cd <仓库目录>

2. 安装 MCP 依赖

bash .cursor/mcp-servers/gitlab-code-search/install.sh

需要本机已安装 Node.js 18+（node -v 可检查）。

3. 配置 Cursor MCP

仓库根目录执行：

bash .cursor/mcp-servers/gitlab-code-search/setup-mcp-snippet.sh

脚本会在 .cursor/ 下生成 mcp.gitlab-code-search.snippet.json（已填入本机绝对路径）。

打开 Cursor → Settings → MCP，把 snippet 里的 gitlab-code-search 段合并进你的 项目 .cursor/mcp.json（若不存在则新建），并修改：

"GITLAB_PERSONAL_ACCESS_TOKEN": "你的GitLab_PAT"

保存后 Reload Window，在 MCP 列表中打开 gitlab-code-search，应能看到 3 个 tools。

三、验证是否成功

在 Cursor 对话中说：

用 gitlab-code-search 在 hsy_ng/deployment_scripts 的 master 上搜索 grid_item_product

若 MCP 正常，Agent 会调用 search_code 并返回结果。

四、环境变量

| 变量 | 说明 | | :--- | :--- | | GITLAB_PERSONAL_ACCESS_TOKEN | GitLab PAT，建议 scope：read_api、read_repository | | GITLAB_API_URL | 默认 https://gitlab.rd.chanjet.com/api/v4 |

五、常见问题

Q: MCP 显示 No tools

• 检查 node 路径是否正确（setup 脚本会用 which node）
• 是否执行过 install.sh
• Token 是否有效（curl -H "PRIVATE-TOKEN: xxx" https://gitlab.rd.chanjet.com/api/v4/user 应返回 200）

Q: 只有 skill 没有 MCP

• Agent 只能按文档“口述”流程，无法真正调 GitLab，必须完成第二节配置。

Q: 能否不用 server.js，只用官方 gitlab MCP

• 可以，但官方工具没有 search_code 这种内容检索封装，scripts-spec 远程核查体验会差很多。