AI导哈

远程代码库管理服务器

coding-mcp是一款让AI代理能够远程执行代码库操作（如读写、搜索、运行命令等）的MCP服务器，适用于开发团队协作和自动化代码管理场景。

  • by kieutrongthien
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 kieutrongthien/coding-mcp

使用说明

编码MCP

生产就绪的MCP服务器，允许AI代理在远程存储库上执行编码任务。

这是怎么一回事？

coding-mcp 是一个 MCP（模型上下文协议） 该服务器将您的代码存储库作为一组工具和资源公开，AI代理可以使用这些工具和资源来读取、写入、搜索和运行命令——所有这些都不需要代理对存储库进行本地访问。

主要目标： 在托管代码的机器上部署一台服务器，然后将任何与MCP兼容的代理（Claude、Cursor等）连接到它。该代理可以浏览文件、编辑代码、运行构建和测试、管理git等等，所有这些都可以通过结构化的MCP工具调用来实现。

┌──────────────────────────────────────────────┐
│  AI Agent (Claude / Cursor / any MCP client) │
└────────────────┬─────────────────────────────┘
                 │  MCP over HTTP or STDIO
                 ▼
┌──────────────────────────────────────────────┐
│           coding-mcp server                  │
│  (runs on the machine with your repos)       │
│                                              │
│  Tools: files · git · search · commands      │
│  Resources: project index · file content     │
│  Prompts: implement · review · fix tests     │
└──────────────────┬───────────────────────────┘
                   │  filesystem + git
                   ▼
      /projects/repo-a  /projects/repo-b  …

文档

亮点

  • 具有持久索引的多项目注册表
  • 安全的文件操作和修补（结构化编辑+统一的差异块）
  • 具有结构化输出的Git命令集
  • 基于允许列表的命令运行器，具有超时和输出限制
  • 二进制安全文件资源（文本和base64 blob模式）
  • 双传输支持：STDIO和HTTP（流式传输或SSE）
  • HTTP API密钥身份验证+RBAC（查看器/编辑器/管理员）
  • OpenTetry挂钩用于请求和工具级跟踪
  • 带有请求ID和时间的结构化操作信封
  • 变异操作的审计日志记录

快速开始

全局安装：

npm install -g @kieutrongthien/coding-mcp

注册一个或多个项目根目录（包含您的repos的目录）：

coding-mcp init /projects

启动服务器：

# HTTP transport (for remote agents)
coding-mcp serve --transport http --host 0.0.0.0 --port 4000 --mode streamable

# STDIO transport (for local agents like Cursor or Claude Desktop)
coding-mcp serve --transport stdio

从源代码构建

git clone https://github.com/kieutrongthien/coding-mcp.git
cd coding-mcp
cp .env.example .env
npm install
npm run build
npm install -g .

CLI命令

命令 描述
coding-mcp init [path] 扫描目录中的项目并写入注册表。默认为当前工作目录。
coding-mcp add <path> 将新的根目录添加到项目注册表中。
coding-mcp remove <path> 从项目注册表中删除根目录。
coding-mcp serve 启动MCP服务器。接受 --transport, --host, --port，以及 --mode 旗帜。

开发快捷方式（无需构建步骤）：

npm run dev:stdio
npm run dev:http
npm run dev:serve -- --transport http --host 127.0.0.1 --port 3001 --mode sse

MCP工具

工具是代理的主要接口。每个工具都接受一个 project_id （返回者 list_projects)并在该项目的根目录内运行，防止任何路径遍历到它之外。

项目工具

工具 说明
list_projects 列出在配置的根目录中发现的所有项目。
get_project 获取特定项目的元数据（路径、检测到的工具、包管理器、git信息）。
refresh_project_index 重新扫描一个项目或所有项目以获取新添加的存储库。

文件工具

工具 说明
list_directory 列出项目中给定路径的文件和子目录。
read_file 读取文件内容，可选地限制为行范围。
read_multiple_files 在一次调用中读取多个文件。
create_file 创建一个新文件。集 overwrite: true 替换现有文件。
write_file 覆盖现有文件的全部内容。
replace_in_file 查找并替换文件中的文本（第一个匹配项或所有匹配项）。
apply_patch 对文件应用统一的差异或结构化编辑操作列表。
delete_file 删除文件或目录。需要 confirm: true 作为安全卫士。
move_file 移动或重命名文件或目录。

搜索工具

工具 说明
search_files 在项目中按名称或路径模式搜索文件。
grep_content 使用类似正则表达式的模式搜索文件内容。返回具有文件路径和行号的匹配行。
get_project_tree 将项目的目录树设置为可配置的深度。
summarize_project 返回项目堆栈、包管理器、检测到的工具和顶级树的摘要。

Git工具

工具 说明
git_status 显示当前工作树状态（已修改、暂存、未跟踪的文件）。
git_diff 将非阶段性或阶段性变化显示为统一差异
git_branch_list 列出所有本地和远程分支。
git_checkout_branch 切换到现有分支。
git_checkout_new_branch 创建并切换到新分支。
git_pull 从远程拉取最新更改。
git_add 阶段一个或多个文件或路径。
git_restore 放弃对指定路径的工作树更改。需要 confirm: true.
git_commit 使用给定的消息创建提交。
git_push Push提交到远程分支。支持 set_upstream.
git_log 显示具有可配置限制的最近提交历史记录。
git_show 通过引用显示特定提交、标记或git对象的详细信息
git_create_tag 创建带注释的标记。

命令工具

命令在项目目录中运行。仅在 ALLOWED_COMMANDS 允许排外主义。

工具 说明
run_build 运行从项目工具中自动检测到的构建命令（例如。 npm run build, make).
run_test 运行从项目工具中自动检测到的测试命令（例如。 npm test, pytest).
run_lint 运行从项目工具中自动检测到的lint命令（例如。 npm run lint, ruff).
run_command_safe 运行任何带有显式参数、工作目录和超时的分配命令。

MCP资源

资源公开了代理可以通过URI直接获取的只读数据。

资源URI 描述
project://index 所有索引项目的JSON列表。
project://{project_id}/tree 项目目录树（深度4）。
project://{project_id}/readme 项目的原始内容 README.md.
project://{project_id}/package-json 项目的原始内容 package.json.
project://{project_id}/git-status 当前git状态为JSON。
project://file/{project_id}/{path} 任何文件的内容。文本文件返回为 text；二进制文件为base64 blob.
project://file-meta/{project_id}/{path} 文件的元数据（大小、MIME类型、编码、截断状态）。

MCP提示

提示提供了预构建的指令，代理可以调用这些指令来启动结构化编码工作流。

提示 描述
analyze-project 让代理分析项目的架构、风险和改进。
implement-task 要求代理在项目中执行所描述的任务。
explain-file 请代理解释特定文件的工作原理。
generate-commit-message 要求代理根据差异摘要生成常规提交消息。
review-diff 让代理检查差异中的错误、回归和缺失的测试。
fix-test-failures 根据原始测试输出，要求代理修复失败的测试。

MCP客户端示例

克劳德桌面（STDIO）

{
  "mcpServers": {
    "coding-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/coding-mcp/dist/src/main/stdio.js"],
      "env": {
        "PROJECTS_ROOTS": "/projects"
      }
    }
  }
}

光标（STDIO）

{
  "mcpServers": {
    "coding-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/coding-mcp/dist/src/main/stdio.js"],
      "env": {
        "PROJECTS_ROOTS": "/projects,/srv/repos",
        "ENABLE_STDIO": "true",
        "ENABLE_HTTP": "false"
      }
    }
  }
}

通用HTTP MCP客户端

{
  "mcpServers": {
    "coding-mcp-http": {
      "url": "http://your-host:4000",
      "headers": {
        "x-api-key": "editor-key"
      }
    }
  }
}

配置

直接使用环境变量或通过以下方式提供JSON/YAML配置文件 MCP_CONFIG_PATH.

核心设置

变量 描述
PROJECTS_ROOTS 以逗号分隔的根目录列表，用于扫描项目（首选）。
PROJECTS_ROOT 单一根目录（传统兼容性）。
ENABLE_HTTP 启用HTTP传输(true/false).
ENABLE_STDIO 启用STDIO传输(true/false).
HTTP_HOST HTTP服务器绑定地址（默认 127.0.0.1).
HTTP_PORT HTTP服务器端口（默认 3000).
HTTP_MODE HTTP传输模式： streamable 或 sse.
MAX_FILE_SIZE 读取操作的最大文件大小（字节）。
MAX_OUTPUT_SIZE 最大命令或资源输出大小（字节）。
COMMAND_TIMEOUT_MS 命令执行超时（毫秒）。
RETRY_MAX_ATTEMPTS 暂时失败的重试尝试次数。
RETRY_BASE_DELAY_MS 重试之间的基本延迟（毫秒）。
ALLOWED_COMMANDS 允许的命令列表，以逗号分隔 run_command_safe.
PROTECTED_PATHS 无法修改的逗号分隔路径模式。
LOG_LEVEL 日志冗长： trace, debug, info, warn, error.
REGISTRY_FILE 项目注册表JSON文件的路径。
AUDIT_LOG_FILE 变异操作的审计日志路径。
HTTP_REQUEST_LOG_FILE HTTP请求日志的路径。

安全设置

变量 描述
ENABLE_AUTH 为HTTP传输启用API-key身份验证。
AUTH_HEADER_NAME 用于传递API密钥的HTTP头（默认值 x-api-key).
AUTH_API_KEYS 中以逗号分隔的密钥列表 key:role:id 格式。

可观察性设置

变量 描述
ENABLE_OTEL 启用OpenTetry跟踪。
OTEL_SERVICE_NAME 跟踪中报告的服务名称。
OTEL_EXPORTER_OTLP_ENDPOINT 用于跟踪导出的OTLP HTTP端点。
OTEL_EXPORTER_OTLP_HEADERS 中OTLP导出器的标头 key=value,key2=value2 格式。

HTTP安全（身份验证/RBAC）

在将HTTP传输公开给外部代理时启用API-key身份验证。

ENABLE_AUTH=true
AUTH_HEADER_NAME=x-api-key
AUTH_API_KEYS=viewer-key:viewer:viewer1,editor-key:editor:editor1,admin-key:admin:admin1

在请求标头中传递密钥：

x-api-key: editor-key

角色：

角色 权限
viewer 只读操作
editor 读取+非破坏性写入、构建和测试操作
admin 完全访问权限，包括破坏性操作

HTTP监控端点

启用HTTP传输时：

端点 描述
GET /healthz 活体检查
GET /readyz 使用索引项目计数进行准备情况检查
GET /metrics 基本指标： request_count, error_count，延迟摘要

开放遥测

跟踪可以通过OTLP HTTP导出：

ENABLE_OTEL=true
OTEL_SERVICE_NAME=coding-mcp
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer%20token

发射跨度：

  • mcp.http.request
  • mcp.tool.{operation}

响应合同

所有工具响应都遵循相同的信封格式。

成功操作：

{
  "ok": true,
  "project_id": "abc123",
  "operation": "read_file",
  "data": {},
  "warnings": [],
  "errors": [],
  "request_id": "uuid",
  "duration_ms": 12
}

操作失败：

{
  "ok": false,
  "operation": "write_file",
  "error_code": "SECURITY_ERROR",
  "message": "Operation blocked for protected path",
  "details": {},
  "request_id": "uuid",
  "duration_ms": 7
}

建筑

服务器使用一个具有模块化层的共享核心：

  • config：环境/配置文件加载和运行时验证
  • core：响应合同、错误、日志记录、遥测挂钩、锁
  • services：文件系统、git、补丁、命令执行、身份验证、项目注册表
  • mcp：绑定到共享服务的工具/资源/提示注册表
  • main：CLI和传输引导(stdio, http, serve/init/add/remove)

STDIO和HTTP传输共享相同的服务层，在允许特定于传输的控制（如HTTP身份验证）的同时保持行为一致。

验证

npm run typecheck
npm test

许可证

麻省理工学院

相关 MCP