AI导哈

代码仓库远程检查工具

CodeSherpa是一个通过SSH和MCP协议实现AI客户端只读访问远程代码仓库的服务，支持多种MCP工具和客户端。

  • by boridon
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 boridon/code-sherpa

使用说明

CodeSherpa

AI-guided repository exploration over SSH via MCP

CodeSherpa是什么？

CodeSherpa是一个远程MCP服务器，允许AI客户端使用严格的只读工具集通过SSH检查存储库。

支持的MCP工具：

  • healthcheck_remote
  • list_files
  • read_file
  • search_code
  • git_status
  • git_diff
  • git_log

兼容的MCP客户端：

  • ChatGPT（自定义连接器）
  • 克劳德桌面版
  • 光标
  • 其他MCP兼容代理

快速开始

在本地克隆并启动CodeSherpa。

git clone https://github.com/boridon/code-sherpa.git
cd code-sherpa
cp .env.example .env
docker compose up -d

然后将您的MCP客户端连接到：

https://your-domain.example/mcp

建筑

MCP Client
    |
    v
CodeSherpa (HTTPS)
    |
    v
SSH (read-only user)
    |
    v
Private repository host

要点：

  • 存储库数据保留在SSH目标主机上。
  • CodeSherpa只公开只读MCP工具。
  • 路径遍历和敏感路径段被阻止。
  • 支持OAuth访问令牌和传统固定承载令牌。

安全模型

  • 使用只读SSH用户（无sudo）。
  • 拒绝的路径段包括 .git, .env, node_modules，以及类似的敏感路径。
  • 绝对路径和 .. 遍历被拒绝。
  • /mcp 需要 mcp:read OAuth访问令牌的范围。
  • 传统的固定承载令牌身份验证可以保持启用状态以进行内部测试。

注意：OAuth会话、授权码和令牌在当前实现中位于内存中。当容器重新启动时，它们会被重置。

Docker部署

1.克隆和准备

git clone https://github.com/boridon/code-sherpa.git
cd code-sherpa
cp .env.example .env
mkdir -p secrets

2.添加SSH密钥

  • 将您的私钥放在 secrets/id_ed25519
  • 生成已知主机：
ssh-keyscan -H <ssh-host> > secrets/known_hosts
chmod 600 secrets/id_ed25519
chmod 644 secrets/known_hosts

3.启动服务

docker compose build
docker compose up -d
docker compose ps
curl http://127.0.0.1:8787/health

Cloudflare 隧道

您可以通过两种方式在Cloudflare上运行CodeSherpa。

A.侧车集装箱（代币模式）

docker compose -f docker-compose.yml -f docker-compose.cloudflare.yml up -d

此模式使用 CLOUDFLARE_TUNNEL_TOKEN 从 .env.

B.配置文件模式(cloudflared-config.yml)

入口示例：

ingress:
  - hostname: code-sherpa.example.com
    service: http://localhost:8787
  - service: http_status:404

如果 cloudflared 您的主机上未安装：

  • Debian/Ubuntu： sudo apt-get install cloudflared
  • RHEL/CentOS/Fedora： sudo dnf install cloudflared
  • macOS（Homebrew）： brew install cloudflared

MCP连接器的OAuth

CodeSherpa包括一个用于连接器设置流的最小内置OAuth授权服务器。

OAuth发现端点：

  • GET /.well-known/oauth-authorization-server
  • GET /.well-known/openid-configuration

OAuth端点：

  • GET /authorize
  • POST /token
  • GET /login
  • POST /login
  • GET /oauth/consent
  • POST /oauth/consent

OAuth配置文件：

  • 授权类型：授权码+PKCE(S256)
  • 范围： mcp:read
  • 公共客户支持：是(token_endpoint_auth_method=none 允许）
  • 刷新令牌：支持

ChatGPT连接器值（示例）

使用以下示例值：

  • MCP端点： https://code-sherpa.example.com/mcp
  • 发行人： https://code-sherpa.example.com
  • 授权端点： https://code-sherpa.example.com/authorize
  • 令牌终结点： https://code-sherpa.example.com/token
  • 范围： mcp:read

环境变量

使用 .env.example 作为基线。

必修的：

  • SSH_HOST
  • SSH_PORT
  • SSH_USERNAME
  • REPO_ROOT
  • MCP_BEARER_TOKEN （用于可选的遗留/手动测试）
  • OAUTH_ISSUER_BASE_URL
  • OAUTH_LOGIN_USERNAME
  • OAUTH_LOGIN_PASSWORD
  • OAUTH_SESSION_SECRET

可选/常用：

  • PORT （默认值 8787)
  • MCP_SERVER_NAME （默认值 code-sherpa)
  • MCP_SERVER_VERSION （默认值 0.1.0)
  • OAUTH_COOKIE_SECURE （默认值 true)
  • MAX_FILE_BYTES, MAX_SEARCH_RESULTS, MAX_LOG_COMMITS, MAX_RESPONSE_CHARS

示例 .env 代码片段（安全占位符）：

PORT=8787
MCP_SERVER_NAME=code-sherpa
SSH_HOST=ssh-host.example.internal
SSH_PORT=22
SSH_USERNAME=repo_reader
REPO_ROOT=/srv/repos/project
OAUTH_ISSUER_BASE_URL=https://code-sherpa.example.com
OAUTH_LOGIN_USERNAME=replace-me
OAUTH_LOGIN_PASSWORD=replace-me
OAUTH_SESSION_SECRET=replace-with-long-random-secret
MCP_BEARER_TOKEN=replace-with-long-random-token

最低验证

1.OAuth发现

curl -i http://127.0.0.1:8787/.well-known/oauth-authorization-server
curl -i http://127.0.0.1:8787/.well-known/openid-configuration

2.遗留承载测试

curl -i -X POST http://127.0.0.1:8787/mcp \
  -H "Authorization: Bearer ${MCP_BEARER_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0.0.1"}}}'

3.OAuth令牌交换

浏览器登录+同意后，交换授权码：

curl -i -X POST http://127.0.0.1:8787/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=<authorization-code>' \
  --data-urlencode 'redirect_uri=<same-redirect-uri-used-at-authorize>' \
  --data-urlencode 'code_verifier=<pkce-code-verifier>' \
  --data-urlencode 'client_id=<client-id>'

项目结构

code-sherpa
├── src/
│   ├── index.ts
│   ├── oauth.ts
│   ├── pkce.ts
│   ├── session.ts
│   └── token-store.ts
├── docs/
│   └── logo.svg
├── Dockerfile
├── docker-compose.yml
├── docker-compose.cloudflare.yml
├── cloudflared-config.example.yml
├── cloudflared-config.yml
├── .env.example
├── .gitignore
├── LICENSE
└── README.md

许可证

麻省理工学院

贡献

欢迎问题和拉取请求。

如果CodeSherpa对你有用，可以考虑在GitHub上给存储库打一颗星。

相关 MCP