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  > 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=' \
  --data-urlencode 'redirect_uri=' \
  --data-urlencode 'code_verifier=
' \
  --data-urlencode '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上给存储库打一颗星。