内容
forgejo-mcp
一款 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，为 AI 客户端提供工具，以便通过 REST API 与 [Forgejo](https://forgejo.org) 或 Gitea 实例进行交互：仓库、问题、评论、文件、拉取请求和 CI 状态。
它通过 stdio 使用 MCP 协议，并使用 `fetch` 调用 Forgejo/Gitea REST API。整个服务器打包成一个单独的 `dist/index.js` 文件，无需运行时框架。
## 安全模型
服务器暴露 **只读工具和附加写操作** —— 创建问题、问题/拉取请求评论和拉取请求。默认情况下，**没有合并、删除或管理员工具**。这使其在无人值守的情况下是安全的，并限制了 API token 的权限范围。将其与最小权限 token（仓库读/写，问题读/写，用户读）配对使用。
一组有限的破坏性操作在 **[需选择开启的提升权限层](#需选择开启的提升权限层-默认关闭)** 后可用。默认情况下，未设置提升权限环境变量时，工具表面与上述安全默认设置相同。
## 工具列表
| 工具 | 类型 | 目的 |
|------|------|---------|
| `list_repositories` | 读取 | 列出用户的仓库（默认：认证用户） |
| `get_repository` | 读取 | 仓库元数据，包括默认分支 |
| `list_issues` | 读取 | 列出问题；按状态和标签过滤；分页 |
| `get_issue` | 读取 | 单个问题，包含正文、标签、指派人 |
| `create_issue` | 写入 | 打开问题（可选标签、指派人） |
| `list_issue_comments` | 读取 | 问题或拉取请求上的评论 |
| `create_issue_comment` | 写入 | 在问题或拉取请求上添加评论 |
| `get_file_content` | 读取 | 解码文件内容（默认分支如果没有引用） |
| `list_directory` | 读取 | 列出目录的条目（根目录如果没有路径） |
| `create_file` | 写入 | 从纯文本内容创建文件（可选新分支） |
| `update_file` | 写入 | 替换文件的内容（传递 `sha` 以防止并发编辑） |
| `list_pull_requests` | 读取 | 列出拉取请求；按状态过滤；分页 |
| `get_pull_request` | 读取 | 单个拉取请求，包含合并状态 |
| `get_pull_request_diff` | 读取 | 拉取请求的统一差异，纯文本 |
| `create_pull_request` | 写入 | 从头部分支打开拉取请求到基准分支 |
| `get_commit_status` | 读取 | 引用提交的综合 CI/提交状态 |
| `list_branches` | 读取 | 列出分支，包含最新提交和保护状态；分页 |
| `get_branch` | 读取 | 按名称获取单个分支 |
| `create_branch` | 写入 | 从源引用创建分支（默认分支如果没有） |
| `list_commits` | 读取 | 列出提交；按起始引用和路径过滤；分页 |
| `get_commit` | 读取 | 按 SHA 或引用获取单个提交 |
| `list_releases` | 读取 | 列出发布；分页 |
| `get_release` | 读取 | 按 ID 获取单个发布，包含备注和草稿/预发布标志 |
| `create_release` | 写入 | 为标签创建发布（草稿、预发布、备注） |
| `list_tags` | 读取 | 列出标签，包含目标提交；分页 |
| `get_tag` | 读取 | 按名称获取单个标签 |
| `create_tag` | 写入 | 在分支或提交上创建标签（可选注释） |
| `list_pull_request_reviews` | 读取 | 拉取请求上的评论（批准、更改请求、评论） |
| `create_pull_request_review` | 写入 | 提交评论（`APPROVE`、`REQUEST_CHANGES` 或 `COMMENT`） |
| `request_pull_request_reviewers` | 写入 | 请求用户（和组织团队）在拉取请求上进行评论 |
| `list_labels` | 读取 | 仓库中定义的标签（ID、名称、颜色）；分页 |
| `add_labels` | 写入 | 将标签（按 ID）添加到问题或拉取请求；保留现有标签 |
| `add_assignees` | 写入 | 将用户指派到问题或拉取请求；保留现有指派人 |
## 配置
在运行时通过环境变量提供目标和令牌：
- `FORGEJO_BASE_URL` — 例如 `https://git.example.com`
- `FORGEJO_TOKEN` — Forgejo/Gitea API 令牌
永远不要硬编码令牌；启动时从秘密存储中注入。
### Claude 代码
两种设置方式，二选一：根据您更注重可移植性还是将令牌保留在 Claude 配置文件之外。
#### 选项 A — `npx`（推荐）
一旦软件包发布到 npm，就无需本地检查或构建：
```sh
claude mcp add forgejo \
--env FORGEJO_BASE_URL=https://git.example.com \
--env FORGEJO_TOKEN=... \
-- npx -y @rubicontv/forgejo-mcp
```
可移植且自我更新。注意，这会将令牌存储在 Claude Code 的配置文件（`~/.claude.json`）中。如果您希望令牌不要接触到该文件，请使用选项 B。
#### 选项 B — 本地包装器（将令牌保留在配置文件之外）
一个小型启动器在启动时加载一个 `chmod 600` 环境文件，因此令牌仅存在于该文件中（理想情况下，从秘密管理器中获取），而不会在 `~/.claude.json` 中：
```sh
#!/bin/sh
# ~/.config/forgejo-mcp/launch.sh
set -eu
. "$HOME/.config/forgejo-mcp/forgejo-mcp.env" # 设置 FORGEJO_BASE_URL、FORGEJO_TOKEN
export FORGEJO_BASE_URL FORGEJO_TOKEN
exec npx -y @rubicontforgejo-mcp # 或：exec node /pathforgejo-mcp/dist
```
将 Claude Code 指向包装器 — 没有 `env` 块，因此配置文件中没有秘密：
```json
{
"mcpServers": {
"forgejo": "command": "/Users/you/.config/forgejo-mcp/launch.sh"
}
}
}
```
#### 从本地构建运行（无需 npm）
如果您从检出软件包工作：
```json
{
"mcpServers": {
"forgejo": {
"command": "node",
"args": ["/path/to/forgejo-mcp/dist/index.js"],
"env": {
"FORGEJO_BASE_URL": "https://git.example.com",
"FORGEJO_TOKEN": "..."
}
}
}
}
```
#### 允许列表
要让代理在每次调用时无需提示，请允许列表。在**安全默认界面**（无提升权限层）上，整个服务器的允许列表是允许的：
```
mcp__forgejo
```
**如果您启用了提升权限层，请勿执行此操作** — 允许整个服务器的列表也将允许 `merge_pull_request` / `delete_branch` 在无需提示的情况下运行。仅允许使用特定的安全工具，例如：
```
mcpjo__create_issue
mcp__forgejo__create_pull_request
```
请参阅 [提升权限层](#需选择开启的提升权限层-默认关闭) 中的允许列表警告。
## 需选择开启的提升权限层（默认关闭）
服务器可以选择公开 **一组最小的破坏性工具**。此权限层 **默认关闭**，必须由操作员有意启用。
| 工具 | 类型 | 操作 |
|------|------|-----------|
| `merge_pull_request` | 提升权限 | 合并拉取请求（`merge` / `rebase` / `squash`）到其基准分支 |
| `delete_branch` | 提升权限 | 永久删除分支 |
每个提升权限工具的描述都以 `[ELEVATED — DESTRUCTIVE]` 为前缀。
### 为什么它受到严格限制
该服务器向不受信任的内容** 的 LLM 提供工具 — 问题正文、拉取请求文本、。这是提示注入的表面：一个误导的代理不应能够合并或删除任何内容。因此，提升权限层是 **双重限制** 的，并使用 **单独的令牌**。
### 启用它 - 双重限制
仅当 **同时设置以下两个条件** 时，才会注册提升权限工具：
- `FORGEJO_MCP_ELEVATED=1`选择开启的标志，和
- `FOR_MCP_ELEVATED_TOKEN` — 与 `FOR_TOKEN` **不同的** 令牌。
默认的 `JO_TOKEN` **永远不会** 执行提升权限 提升权限调用**专门** 使用 `FORGECP_ELEVATED_TOKEN请将该令牌限制在破坏性工具实际需要的仓库和权限范围内设置了 `FOR_MCP_ELEVATED` 但 `FORGEJO_MCP_ELEVATED_TOKEN` 丢失，服务器 **关闭**：不会注册提升，并在标准错误中记录警告。
```json
{
mcpServers": {
"forgejo": {
command": "node",
"args": ["/path/to/forgejo-m/index.js"],
" "FORGEJO_BASE_URL": "https.example.com",
GEJO_TOKEN": "/写令牌…",
"FORGEJO_MCPATED": "1",
"FORGECP_ELEVATED_TOKEN": "…不同的、范围令牌…"
}
}
}
}
```
### ⚠️ 允许列表警告 - 请在启用前阅读
通常，MCP **整个服务器允许列表** （例如 `mcp__forgejo`），以便代理可以自主使用它，无需每次调用都提示。**如果了提升权限层，则在允许列表中**，工具也可以在无需提示。注入到问题或拉取请求中的单一提示有效载荷可以代表您合并或删除。
因此，当启用提升权限层时：
- **不要对整个服务器进行允许列表** （`mcp__forgejo`）。
- **仅允许列表您想要自主运行的特定安全工具** （例如 `__forgejo_issue`），并_pull_request`delete_branch` 留给每次都要求明确服务器无法强制执行允许列表 — 不同的和此警告是缓解措施。启用提升权限工具员拥有的决策。
### 永久排除
提升权限层故意很小。以下内容 **永远不会** 暴露，无论任何标志如何：用户管理、秘密/变量写入、权限或协作者更改，以及组织/仓库管理。这些不适合交给读取不受信任内容的 LLM，因此通过设计永久排除。添加任何破坏性工具都需要操作员明确同意和匹配的令牌范围审查。
## 构建和测试
```bash
npm install
npm run build # esbuild -> dist/index.js
npm run smoke # 构建，然后运行无令牌的 MCP 握手 + 工具/列表
npm run typecheck # tsc --noEmit
```
## 贡献者
[](https://github.com/rubicon/forgejo-mcp/graphs/contributors)
参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 开始使用，[Code of Conduct](CODE_OF_CONDUCT.md) 了解社区期望，[SECURITY.md](SECURITY.md) 私下报告漏洞。
## 许可证和归属
根据 [Apache License 2.0](LICENSE) 许可。这是一个独立的、干净室的实现；参见 [NOTICE](NOTICE)。它受到 [`nsvk13/forgejo-mcp-server`](https://github.com/nsvk13/forgejo-mcp-server) 的启发，感谢他们，但没有共享任何源代码。
