HomeWork/gitea-mcp
5
0
Fork 0
mirror of https://gitea.com/gitea/gitea-mcp.git synced 2026-08-03 15:49:23 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat(cmd): add -S/--scope to load only selected tool scopes (#219)

Browse Source 
`-O` / `--tools` can already narrow the exposed tool set, but it needs every tool spelled out by name. `-S` / `--scope` (`GITEA_SCOPES`) complements it by selecting whole scopes, using the same names the `Scope` column of the tool tables documents.

```bash
gitea-mcp -S issue,pull_request                     # only those scopes
gitea-mcp --scope repository,branch --tools get_me   # those scopes plus one extra tool
```

## What changed

- Each scope is one `tool.Tool` registry carrying a canonical name, so `operation/repo` is split into the six scopes its files already imply: `repository` (`repo.go` + `tree.go`), `file`, `branch`, `tag`, `commit`, `release`. The other twelve packages map 1:1, giving 18 scopes.
- The two allowlists combine as a **union**: with neither set every tool loads; with only `--tools` set behaviour is unchanged; with both set, the selected scopes' tools plus the individually named tools load. `-r` / `GITEA_READONLY` still hides write tools on top.
- Scope names are normalized on input (case, spaces, hyphens), so `Pull Request`, `pull-request` and `PULL_REQUEST` all resolve to `pull_request`. Unknown names only warn and list the valid scopes, mirroring how `--tools` treats unknown tool names.
- The `Scope` column of all three READMEs now uses the canonical names verbatim, so it doubles as the reference for `--scope`, and `TestReadmeToolTables` compares that column against the registry in both directions — no translation table needed.
- Flag parsing moves from `cmd.init()` into `Execute()`. `main()` only ever calls `Execute()`, so this is behaviourally equivalent, and it makes the `cmd` package testable at all: previously the `init()` parse of `os.Args` hit `flag.CommandLine`'s `ExitOnError` on `go test`'s own `-test.*` flags.

## Verification

`make fmt`, `make lint-go` (0 issues) and `go test ./...` all pass. New tests cover the filter matrix (no filters / scope-only / tools-only regression / union / read-only interaction / unknown scope), scope-name uniqueness across `domainTools`, and the flag+env parsing and normalization.

Smoke-tested `tools/list` over stdio against the built binary:

| flags | tools exposed |
| :-- | :-- |
| _none_ | 54 (identical to `main`) |
| `-S branch` | `create_branch`, `delete_branch`, `list_branches` |
| `--scope 'Pull Request,TAG'` | the 4 `pull_request` + 4 `tag` tools |
| `-O get_me` | `get_me` (unchanged) |
| `-S commit -O get_me` | `get_commit`, `list_commits`, `get_me` |
| `-S file -r` | `get_dir_contents`, `get_file_contents` |
| `-S bogus,issue` | the 4 `issue` tools, plus a warning naming the valid scopes |

Reviewed-on: https://gitea.com/gitea/gitea-mcp/pulls/219
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: yp05327 <576951401@qq.com>
This commit is contained in:
yp05327
2026-07-27 18:12:29 +00:00
committed by bircni
parent c97c38996c
commit 21aa4684d9
29 changed files with 580 additions and 235 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.zh-tw.md
+64 -57
View File
@@ -129,63 +129,70 @@ Cursor 等客戶端可使用 stdio 命令：
## 可用工具
| 工具 | 範圍 | 存取 | 描述 |
| :--------------------------- | :------- | :--- | :------------------------------------------------------------------- |
| get_gitea_mcp_server_version | 版本 | 讀取 | 取得 Gitea MCP 伺服器版本 |
| get_me | 用戶 | 讀取 | 取得目前已認證用戶 |
| get_user_orgs | 用戶 | 讀取 | 列出目前用戶的組織 |
| search_users | 搜尋 | 讀取 | 搜尋用戶 |
| search_org_teams | 搜尋 | 讀取 | 搜尋組織中的團隊 |
| search_repos | 搜尋 | 讀取 | 搜尋倉庫 |
| search_issues | 搜尋 | 讀取 | 跨倉庫搜尋問題和拉取請求 |
| notification_read | 通知 | 讀取 | 讀取通知：列出（可限定倉庫）或依 ID 取得會話 |
| notification_write | 通知 | 寫入 | 將某條或全部通知標記為已讀 |
| label_read | 標籤 | 讀取 | 讀取倉庫或組織標籤 |
| label_write | 標籤 | 寫入 | 寫入標籤（倉庫或組織）：創建、編輯、刪除 |
| milestone_read | 里程碑 | 讀取 | 讀取里程碑：取得單個或列出 |
| milestone_write | 里程碑 | 寫入 | 寫入里程碑：創建、更新、刪除 |
| wiki_read | Wiki | 讀取 | 讀取 Wiki：列出頁面、取得內容、修訂歷史 |
| wiki_write | Wiki | 寫入 | 寫入 Wiki 頁面：創建、更新、刪除 |
| timetracking_read | 時間追蹤 | 讀取 | 讀取時間追蹤：問題/倉庫耗時、活動計時器、我的追蹤記錄 |
| timetracking_write | 時間追蹤 | 寫入 | 寫入時間追蹤：計時器和記錄項目 |
| package_read | 軟體套件 | 讀取 | 讀取軟體套件註冊表：列出套件、列出版本或取得某個版本 |
| package_write | 軟體套件 | 寫入 | 刪除軟體套件版本（不可復原） |
| list_issues | 問題 | 讀取 | 列出倉庫問題 |
| attachment_read | 問題 | 讀取 | 讀取問題/評論附件：列出中繼資料、取得中繼資料或下載內容 |
| issue_read | 問題 | 讀取 | 讀取問題：詳情、評論或標籤 |
| issue_write | 問題 | 寫入 | 寫入問題：創建、更新、管理評論和標籤 |
| list_pull_requests | 拉取請求 | 讀取 | 列出倉庫拉取請求 |
| pull_request_read | 拉取請求 | 讀取 | 讀取拉取請求：詳情、差異、變更檔案、頭部提交狀態、審查 |
| pull_request_write | 拉取請求 | 寫入 | 寫入拉取請求：創建、更新、關閉、重新開啟、合併、更新分支、管理審查者 |
| pull_request_review_write | 拉取請求 | 寫入 | 寫入 PR 審查：創建、提交、刪除、駁回 |
| actions_config_read | Actions | 讀取 | 讀取 Actions 密鑰和變數 |
| actions_config_write | Actions | 寫入 | 寫入 Actions 密鑰和變數：更新插入、創建、更新、刪除 |
| actions_run_read | Actions | 讀取 | 讀取 Actions 工作流程、執行、作業、日誌和產物 |
| actions_run_write | Actions | 寫入 | 寫入 Actions 執行：觸發、取消、重新執行 |
| create_repo | 倉庫 | 寫入 | 創建新倉庫 |
| fork_repo | 倉庫 | 寫入 | 復刻倉庫 |
| list_my_repos | 倉庫 | 讀取 | 列出目前用戶擁有的倉庫 |
| list_org_repos | 倉庫 | 讀取 | 列出組織中的倉庫 |
| get_repository_tree | 倉庫 | 讀取 | 取得倉庫檔案樹 |
| get_file_contents | 文件 | 讀取 | 取得檔案內容與中繼資料 |
| get_dir_contents | 文件 | 讀取 | 取得目錄中的項目 |
| create_or_update_file | 文件 | 寫入 | 創建或更新檔案（提供 sha 以更新現有檔案） |
| delete_file | 文件 | 寫入 | 刪除檔案 |
| create_branch | 分支 | 寫入 | 創建新分支 |
| delete_branch | 分支 | 寫入 | 刪除分支 |
| list_branches | 分支 | 讀取 | 列出倉庫分支 |
| create_tag | Git 標籤 | 寫入 | 創建標籤 |
| delete_tag | Git 標籤 | 寫入 | 刪除標籤 |
| get_tag | Git 標籤 | 讀取 | 取得標籤詳情 |
| list_tags | Git 標籤 | 讀取 | 列出倉庫標籤 |
| list_commits | 提交 | 讀取 | 列出倉庫提交 |
| get_commit | 提交 | 讀取 | 取得提交詳情 |
| create_release | 版本發布 | 寫入 | 創建版本發布 |
| delete_release | 版本發布 | 寫入 | 刪除版本發布 |
| get_release | 版本發布 | 讀取 | 依 ID 取得版本發布 |
| get_latest_release | 版本發布 | 讀取 | 取得最新版本發布 |
| list_releases | 版本發布 | 讀取 | 列出倉庫版本發布 |
| 工具 | 範圍 | 存取 | 描述 |
| :--------------------------- | :----------- | :- | :--------------------------------- |
| get_gitea_mcp_server_version | version | 讀取 | 取得 Gitea MCP 伺服器版本 |
| get_me | user | 讀取 | 取得目前已認證用戶 |
| get_user_orgs | user | 讀取 | 列出目前用戶的組織 |
| search_users | search | 讀取 | 搜尋用戶 |
| search_org_teams | search | 讀取 | 搜尋組織中的團隊 |
| search_repos | search | 讀取 | 搜尋倉庫 |
| search_issues | search | 讀取 | 跨倉庫搜尋問題和拉取請求 |
| notification_read | notification | 讀取 | 讀取通知：列出（可限定倉庫）或依 ID 取得會話 |
| notification_write | notification | 寫入 | 將某條或全部通知標記為已讀 |
| label_read | label | 讀取 | 讀取倉庫或組織標籤 |
| label_write | label | 寫入 | 寫入標籤（倉庫或組織）：創建、編輯、刪除 |
| milestone_read | milestone | 讀取 | 讀取里程碑：取得單個或列出 |
| milestone_write | milestone | 寫入 | 寫入里程碑：創建、更新、刪除 |
| wiki_read | wiki | 讀取 | 讀取 Wiki：列出頁面、取得內容、修訂歷史 |
| wiki_write | wiki | 寫入 | 寫入 Wiki 頁面：創建、更新、刪除 |
| timetracking_read | timetracking | 讀取 | 讀取時間追蹤：問題/倉庫耗時、活動計時器、我的追蹤記錄 |
| timetracking_write | timetracking | 寫入 | 寫入時間追蹤：計時器和記錄項目 |
| package_read | packages | 讀取 | 讀取軟體套件註冊表：列出套件、列出版本或取得某個版本 |
| package_write | packages | 寫入 | 刪除軟體套件版本（不可復原） |
| list_issues | issue | 讀取 | 列出倉庫問題 |
| attachment_read | issue | 讀取 | 讀取問題/評論附件：列出中繼資料、取得中繼資料或下載內容 |
| issue_read | issue | 讀取 | 讀取問題：詳情、評論或標籤 |
| issue_write | issue | 寫入 | 寫入問題：創建、更新、管理評論和標籤 |
| list_pull_requests | pull_request | 讀取 | 列出倉庫拉取請求 |
| pull_request_read | pull_request | 讀取 | 讀取拉取請求：詳情、差異、變更檔案、頭部提交狀態、審查 |
| pull_request_write | pull_request | 寫入 | 寫入拉取請求：創建、更新、關閉、重新開啟、合併、更新分支、管理審查者 |
| pull_request_review_write | pull_request | 寫入 | 寫入 PR 審查：創建、提交、刪除、駁回 |
| actions_config_read | actions | 讀取 | 讀取 Actions 密鑰和變數 |
| actions_config_write | actions | 寫入 | 寫入 Actions 密鑰和變數：更新插入、創建、更新、刪除 |
| actions_run_read | actions | 讀取 | 讀取 Actions 工作流程、執行、作業、日誌和產物 |
| actions_run_write | actions | 寫入 | 寫入 Actions 執行：觸發、取消、重新執行 |
| create_repo | repository | 寫入 | 創建新倉庫 |
| fork_repo | repository | 寫入 | 復刻倉庫 |
| list_my_repos | repository | 讀取 | 列出目前用戶擁有的倉庫 |
| list_org_repos | repository | 讀取 | 列出組織中的倉庫 |
| get_repository_tree | repository | 讀取 | 取得倉庫檔案樹 |
| get_file_contents | file | 讀取 | 取得檔案內容與中繼資料 |
| get_dir_contents | file | 讀取 | 取得目錄中的項目 |
| create_or_update_file | file | 寫入 | 創建或更新檔案（提供 sha 以更新現有檔案） |
| delete_file | file | 寫入 | 刪除檔案 |
| create_branch | branch | 寫入 | 創建新分支 |
| delete_branch | branch | 寫入 | 刪除分支 |
| list_branches | branch | 讀取 | 列出倉庫分支 |
| create_tag | tag | 寫入 | 創建標籤 |
| delete_tag | tag | 寫入 | 刪除標籤 |
| get_tag | tag | 讀取 | 取得標籤詳情 |
| list_tags | tag | 讀取 | 列出倉庫標籤 |
| list_commits | commit | 讀取 | 列出倉庫提交 |
| get_commit | commit | 讀取 | 取得提交詳情 |
| create_release | release | 寫入 | 創建版本發布 |
| delete_release | release | 寫入 | 刪除版本發布 |
| get_release | release | 讀取 | 依 ID 取得版本發布 |
| get_latest_release | release | 讀取 | 取得最新版本發布 |
| list_releases | release | 讀取 | 列出倉庫版本發布 |
> **說明：** 部分工具是聚合的、基於操作的工具，單個工具透過 `method` 參數暴露多個操作。當伺服器以唯讀模式執行時（`-r` / `GITEA_READONLY`），存取為「寫入」的工具會被隱藏；可透過 `-O` / `--tools`（`GITEA_TOOLS`）過濾對外暴露的工具集合。
> **說明：** 部分工具是聚合的、基於操作的工具，單個工具透過 `method` 參數暴露多個操作。當伺服器以唯讀模式執行時（`-r` / `GITEA_READONLY`），存取為「寫入」的工具會被隱藏；可透過 `-S` / `--scope`（`GITEA_SCOPES`）依範圍過濾，或透過 `-O` / `--tools`（`GITEA_TOOLS`）依工具名稱過濾對外暴露的工具集合。
未設定任一參數時，會載入所有工具；僅設定 `--scope` 時，會載入這些範圍內的所有工具；僅設定 `--tools` 時，只會載入指定名稱的工具；兩者皆設定時，會載入所選範圍的工具與指定工具名稱的聯集。範圍名稱即上表「範圍」欄中的值，未知的範圍名稱僅會在啟動時發出警告並被忽略。
```bash
gitea-mcp -S issue,pull_request
gitea-mcp --scope repository,branch --tools get_me
```
許多工具支援 `page` 和 `per_page` 分頁參數。最大有效頁面大小由 Gitea 伺服器的 `[api].MAX_RESPONSE_ITEMS` 設定決定（預設 **50**），超出的值會被靜默截斷。