内容
<p align="center">
<b>英文</b> | <a href="README.fa.md">فارسی</a>
</p>
# GitHub MCP 精简版
一个最小化的 [MCP](https://modelcontextprotocol.io) （模型上下文协议）服务器，
用于创建 GitHub 仓库、提交文件和发布版本，
使用一个普通的个人访问令牌（PAT）。
无需 Docker，无需本地 Git 安装，也无需 GitHub Copilot 订阅
—— 与托管的 `api.githubcopilot.com/mcp/` 服务器不同，
后者需要 Copilot 权限。 本服务器直接与常规的
GitHub REST API (`api.github.com`) 进行通信，
使用普通的 `fetch` 请求，因此它是一个依赖轻量级的文件，
您可以几分钟内阅读完毕。
## 为什么存在这个项目
大多数 MCP GitHub 集成都需要完整的本地 Git 工具链、
Docker 容器或 Copilot 授权的托管端点。 `github-mcp-lite` 适用于
以下情况：您只需要一个 AI 助手能够：
- 创建一个新的仓库，
- 将一批文件推送到仓库中，并一次性提交，
- 发布一个版本，
只需使用您已有的令牌。
## 工具列表
| 工具 | 描述 | 是否破坏性？ |
| --- | --- | --- |
| `get_authenticated_user` | 返回配置令牌帐户的登录/个人资料。 | 否 |
| `create_repository` | 创建由身份验证用户拥有的仓库。 自动初始化为 README，以便默认分支立即存在。 | 否 |
| `commit_files` | 在单个提交中创建或更新一个或多个文本文件。 | 是（覆盖文件内容） |
| `create_release` | 发布标记的 GitHub 版本。 | 否 |
| `delete_repository` | 永久删除仓库。 需要 `delete_repo` 令牌范围。 | **是，不可逆转** |
每个工具都带有 `readOnlyHint` / `destructiveHint` /
`openWorldHint` 元数据，以便 MCP 客户端可以显示适当的确认提示。
### `get_authenticated_user`
无输入。 返回令牌所有者的 `{ login, html_url, name }`。
### `create_repository`
| 参数 | 类型 | 是否必需 | 备注 |
| --- | --- | --- | --- |
| `name` | 字符串 | 是 | 仓库名称 |
| `description` | 字符串 | 否 | 仓库描述 |
| `private` | 布尔值 | 否 | 默认值为 `false`（公开） |
返回 `{ full_name, html_url, clone_url, default_branch }`。
### `commit_files`
| 参数 | 类型 | 是否必需 | 备注 |
| --- | --- | --- | --- |
| `owner` | 字符串 | 是 | 仓库所有者 |
| `repo` | 字符串 | 是 | 仓库名称 |
| `branch` | 字符串 | 否 | 默认值为仓库的默认分支 |
| `message` | 字符串 | 是 | 提交消息 |
| `files` | `{ path, content }` 数组 | 是 | 仅限 UTF-8 文本内容；至少一个文件 |
内部创建 blob、树和提交，通过 Git 数据 API，
然后快速转发分支引用 - 所以它是一个真正的单个提交，
不是每个文件的提交。 返回 `{ commit_sha, html_url, files_changed }`。
### `create_release`
| 参数 | 类型 | 是否必需 | 备注 |
| --- | --- | --- | --- |
| `owner` | 字符串 | 是 | 仓库所有者 |
| `repo` | 字符串 | 是 | 仓库名称 |
| `tag_name` | 字符串 | 是 | 例如 `v1.0.0` |
| `name` | 字符串 | 否 | 版本标题 |
| `body` | 字符串 | 否 | 版本说明（Markdown） |
| `target_commitish` | 字符串 | 否 | 要标记的分支或提交 SHA；默认为默认分支 |
| `draft` | 布尔值 | 否 | 默认值为 `false` |
| `prerelease` | 布尔值 | 否 | 默认值为 `false` |
返回 `{ html_url, id, tag_name }`。
### `delete_repository`
| 参数 | 类型 | 是否必需 | 备注 |
| --- | --- | --- | --- |
| `owner` | 字符串 | 是 | 仓库所有者 |
| `repo` | 字符串 | 是 | 仓库名称 |
永久删除仓库。 返回 `{ deleted: true, full_name }`。
需要具有 `delete_repo` 范围的经典 PAT - 细粒度令牌通常不能删除仓库。
## 安装
### 前提条件
- [Node.js](https://nodejs.org/) 18+（用于原生 `fetch` 支持）
- GitHub [个人访问令牌](https://github.com/settings/tokens)，
具有 `repo` 范围（如果要使用 `delete_repository`，请添加 `delete_repo`）
> **注意：** 仓库**创建**不受细粒度 PAT 的可靠支持，
> 因此建议使用**经典**令牌。
### 克隆并安装依赖项
```bash
git clone https://github.com/MatinMHF/github-mcp-lite.git
cd github-mcp-lite
npm install
```
### 配置令牌
服务器从环境中的 `GITHUB_PERSONAL_ACCESS_TOKEN` 或
`GITHUB_TOKEN` 读取令牌。 在启动之前设置其中一个 -
如果两者都不存在，进程将立即退出并显示错误。
## 用法
### 直接运行
```bash
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx node index.js
```
服务器通过 stdio 进行通信，因此它旨在由 MCP
客户端（Claude Code、Claude Desktop 等）启动，
而不是单独交互运行。
### 在 Claude Code 中注册
```bash
claude mcp add github-lite -s user -e GITHUB_PERSONAL_ACCESS_TOKEN=<your_token> -- node /path/to/index.js
```
在 Windows PowerShell 上，请引用分隔符为 `"--"` -
PowerShell 静默地剥夺了一个裸 `--`，在它到达脚本的参数之前，
这会破坏参数解析：
```powershell
claude mcp add github-lite -s user -e GITHUB_PERSONAL_ACCESS_TOKEN=<your_token> "--" node "C:/path/to/index.js"
```
### 在 Claude Desktop（或任何 MCP 兼容客户端）中注册
在客户端的 MCP 服务器配置中添加一个条目（例如
`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"github-lite": {
"command": "node",
"args": ["C:/path/to/github-mcp-lite/index.js"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
}
}
}
}
```
### 示例工作流程
注册到 MCP 客户端后，通常的会话：
1. **"我是谁认证的？"** → 调用 `get_authenticated_user`
2. **"创建一个名为 `my-project` 的公共仓库"** → 调用 `create_repository`
（自动初始化为 README，以便默认分支存在）
3. **"将这些文件提交到它"** → 调用 `commit_files`，带有 `{ path, content }` 条目数组，
在单个提交中写入
4. **"发布 v1.0.0 版本"** → 调用 `create_release`
## 安全说明
- 令牌在启动时从环境中读取一次，永不记录。
- `commit_files` 和 `delete_repository` 在其工具注释中标记为 `destructiveHint: true` -
行为良好的 MCP 客户端应在调用它们之前提示确认。
- 由于此服务器在每个工具上都有 `openWorldHint: true`（它对 `api.github.com` 进行真正的网络调用），
请仅使用它来访问您实际需要的令牌范围。
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取指南。 该项目遵循
[行为准则](CODE_OF_CONDUCT.md)。 若要报告安全问题，请参阅
[SECURITY.md](SECURITY.md)。
## 许可证
MIT
