内容
# 本地代码MCP
`local-code-mcp`是一个可重用的、基于配置文件的MCP服务器，用于通过可流式传输的HTTP端点安全地检查和更改本地Git仓库。RentingHub是第一个配置文件/插件；没有将RentingHub业务逻辑嵌入到核心服务器中。
安全模型默认拒绝：
- 默认绑定到`127.0.0.1`；
- 文件、Git、推送、强制推送和破坏性模式默认禁用；
- 没有原始shell工具；
- 命令是不可变的argv数组，从活动配置文件加载并使用`shell: false`运行；
- 每个文件路径都限定在配置的仓库中，包括符号链接解析；
- 类似于机密和配置文件中拒绝的路径被阻止；
- 直接推送到`main`、`master`或配置文件默认分支被阻止；
- 所有工具调用都审计到`logs/audit.log`，敏感参数被涂黑。
## 需求
- Node.js 20 或更新版本
- Git
- `rg` 是可选的；`search_code` 降级为 Node 实现
- GitHub CLI `gh` 是可选的，仅在自动创建PR时需要
- Tailscale 是可选的，独立于 Node 依赖图之外
## 安装和运行
```bash
export MCP_HOST=127.0.0.1
export MCP_PORT=3333
export MCP_ACTIVE_PROFILE=rentinghub
export MCP_PROFILE_PATH="$PWD/profiles/rentinghub.json"
export MCP_AUTH_MODE=bearer
export MCP_BEARER_TOKEN="$(openssl rand -hex 32)"
export MCP_PUBLIC_MODE=true
export MCP_ENABLE_FILE_WRITE=false
export MCP_ENABLE_GIT_WRITE=false
export MCP_ENABLE_PUSH=false
export MCP_ENABLE_DESTRUCTIVE=false
export MCP_TOOL_CATALOG_MODE=chatgpt_default
npm install
npm run build
npm run start
```
健康检查：
```bash
curl http://127.0.0.1:3333/health
```
MCP 端点：
```txt
http://127.0.0.1:3333/mcp
```
支持的环境变量：
```txt
MCP_HOST=127.0.0.1
MCP_PORT=3333
MCP_ACTIVE_PROFILE=rentinghub
MCP_PROFILE_PATH=/absolute/path/to/profiles/rentinghub.json
MCP_AUTH_MODE=none|bearer|oauth
MCP_BEARER_TOKEN=<required when exposed remotely>
MCP_PUBLIC_BASE_URL=https://host.example
MCP_OAUTH_ISSUER=https://host.example
MCP_OAUTH_ADMIN_SECRET=<local approval secret>
MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS=3600
MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS=2592000
MCP_OAUTH_STORAGE_PATH=./data/oauth-store.json
MCP_OAUTH_DEBUG=false
MCP_ALLOWED_ORIGINS=<comma-separated exact origins>
MCP_PUBLIC_MODE=false
MCP_ENABLE_FILE_WRITE=false
MCP_ENABLE_GIT_WRITE=false
MCP_ENABLE_PUSH=false
MCP_ENABLE_DESTRUCTIVE=false
MCP_ENABLE_FORCE_PUSH=false
MCP_ENABLE_GH_WRITE=false
MCP_ENABLE_GH_MERGE=false
MCP_ENABLE_GIT_REWRITE=false
MCP_GIT_REMOTE=origin
MCP_MAX_READ_BYTES=262144
MCP_MAX_OUTPUT_BYTES=200000
MCP_TOOL_CATALOG_MODE=chatgpt_default|chatgpt_code|chatgpt_full|power_user|debug (default: chatgpt_default)
LOCAL_CODE_MCP_TOOL_CATALOG=chatgpt_full (alternative env to explicitly override tool catalog mode)
```
`MCP_TOOL_CATALOG_MODE` 限制了哪些工具暴露给AI客户端，以防止ChatGPT/Cursor选择低级或废弃的工具（如`apply_patch`或`write_file`）而不是首选的高级工具（如`apply_patch_batch`和`run_targeted_validation`）。
## Tailscale Funnel
启动本地服务器，然后公开其端口：
```bash
tailscale funnel 3333
```
后台模式：
```bash
tailscale funnel --bg 3333
```
公共端点将是：
```txt
https://<machine>.<tailnet>.ts.net/mcp
```
## Codex 配置
导出与MCP_BEARER_TOKEN相同的 bearer token：
```bash
export LOCAL_CODE_MCP_TOKEN="<same token used by MCP_BEARER_TOKEN>"
```
添加到 `~/.codex/config.toml` 或受信任项目的 `.codex/config.toml`：
```toml
[mcp_servers.local_code_mcp]
url = "https://<machine>.<tailnet>.ts.net/mcp"
bearer_token_env_var = "LOCAL_CODE_MCP_TOKEN"
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"
enabled_tools = [
"repo_info",
"list_files",
"search_code",
"read_file",
"git_status",
"git_diff",
"inspect_package_scripts",
"read_test_failures",
"apply_patch",
"run_check",
"run_validation_sequence",
"git_create_branch",
"git_add",
"git_commit",
"git_push_branch",
"github_create_pr",
"rentinghub_scan_architecture",
"rentinghub_run_core_validation"
]
[mcp_servers.local_code_mcp.tools.apply_patch]
approval_mode = "approve"
[mcp_servers.local_code_mcp.tools.run_check]
approval_mode = "approve"
[mcp_servers.local_code_mcp.tools.run_validation_sequence]
approval_mode = "approve"
[mcp_servers.local_code_mcp.tools.git_add]
approval_mode = "approve"
[mcp_servers.local_code_mcp.tools.git_commit]
approval_mode = "approve"
[mcp_servers.local_code_mcp.tools.git_push_branch]
approval_mode = "approve"
[mcp_servers.local_code_mcp.tools.github_create_pr]
approval_mode = "approve"
```
## ChatGPT Web OAuth 设置
以OAuth模式启动服务器，并禁用所有写入权限：
```bash
cd /Volumes/Home_EX/Projects/local-code-mcp
export MCP_HOST=127.0.0.1
export MCP_PORT=3333
export MCP_ACTIVE_PROFILE=rentinghub
export MCP_PROFILE_PATH="$PWD/profiles/rentinghub.json"
export MCP_AUTH_MODE=oauth
export MCP_PUBLIC_MODE=true
export MCP_PUBLIC_BASE_URL="https://ats-mac-mini.tail60fb71.ts.net"
export MCP_OAUTH_ISSUER="https://ats-mac-mini.tail60fb71.ts.net"
export MCP_OAUTH_ADMIN_SECRET="$(openssl rand -hex 16)"
export MCP_ENABLE_FILE_WRITE=false
export MCP_ENABLE_GIT_WRITE=false
export MCP_ENABLE_PUSH=false
export MCP_ENABLE_DESTRUCTIVE=false
echo "ADMIN SECRET FOR OAUTH APPROVAL:"
echo "$MCP_OAUTH_ADMIN_SECRET"
npm run build
npm start
```
## 代码风格的项目信任
服务器实现了一个类似Codex的项目信任系统，以安全地管理多个项目，在运行时切换项目，并强制执行权限。
信任存储路径：`~/.local/share/local-code-mcp/config.toml`（或通过`MCP_TRUST_STORE_PATH`配置）。
### 命令
```bash
mcptrust trust rentinghub \
--repo /Volumes/Home_EX/Projects/RentingHub \
--profile-path /Volumes/Home_EX/Projects/local-code-mcp/profiles/rentinghub.json \
--github Phamtuandat/RentingHub \
--mode full \
--default \
--yes
mcpfull rentinghub
mcpread /Volumes/Home_EX/Projects/UnknownRepo
mcptrust list
mcptrust current
mcptrust doctor
mcpswitch mentorly
mcpstop
```
### 交互式 Codex 风格的提示
当运行 `mcpfull` 或 `mcpread` 在不受信任的目录上时，CLI 将要求明确批准：
```txt
mcpfull /Volumes/Home_EX/Projects/Mentorly
Project is not trusted:
/Volumes/Home_EX/Projects/Mentorly
Trust this folder with full workspace permissions? [y/N]
```
## 安全限制
- 这是一个应用程序级别的仓库沙盒，而不是VM或OS账户边界。以较低权限用户运行它以获得更强的隔离。
- bearer 和不透明的OAuth访问令牌如果被盗用，可以重放。在疑似暴露后轮换/撤销本地OAuth存储，避免shell历史，截图，日志和提交的配置。
- Tailscale Funnel使端点可通过互联网访问。不在此处实施速率限制和网络级滥用控制。
- 允许的项目命令使用服务器进程用户的权限执行，可以运行项目生命周期行为。保持配置文件定义最小并审查。
- Git钩子可能在提交/推送期间执行。审查仓库钩子并为不受信任的仓库使用专用环境。
- `gh` 使用本地认证的GitHub账户。将该账户/令牌范围限定为仅所需的仓库。
- 审计日志和检查日志可能包含仓库输出。它们是模式`0600`，被Git忽略，应根据本地策略保留和删除。
- 源白名单是补充性的； bearer/OAuth令牌验证是MCP请求的主要控制。 OAuth批准没有内置的速率限制器。保持管理员秘密强大，临时和私有，并依赖Funnel/网络控制来限制暴露。
