a-limasov-ii
9a5750ddca
Expose the same 66 Gitea tools two ways from server/gitea_mcp.py:
- MCP server (no subcommand -> mcp.run()), as before
- CLI: `<tool> --flags` prints one JSON object {success, data/error}
A new @tool decorator registers each function in both FastMCP and a TOOLS
registry; a CLI dispatcher builds argparse from each function's signature and
wraps results in the repo's JSON+success contract. Adds `list-tools` for
discovery. No tool logic duplicated.
- Rewrite skills/gitea/SKILL.md for CLI-first usage (MCP kept as an option)
- Sync version to 0.3.0 across plugin.json, pyproject.toml, SKILL.md
- Add tests/unit/test_cli.py (dispatch routing, flag typing, errors, main)
- Document dual-mode in README.md and CLAUDE.md
- Ignore coverage artifacts
Tests: 119 passed, 93% coverage.
94 lines
3.5 KiB
Markdown
94 lines
3.5 KiB
Markdown
# gitea-platform-mcp
|
|
|
|
Full Gitea platform management — 66 tools for repositories, issues, PRs, branches, files, releases, webhooks, and organizations.
|
|
|
|
## Two ways to run (one source file)
|
|
|
|
`server/gitea_mcp.py` is both an MCP server and a CLI. The 66 tool functions are
|
|
shared; only the entrypoint differs:
|
|
|
|
- **MCP server** — registered via `.mcp.json`, tools appear as `mcp__gitea__<tool>`.
|
|
This is how you connect it to an MCP-aware client.
|
|
- **CLI skill** — `uv run server/gitea_mcp.py <tool> --flags` prints one JSON
|
|
object on stdout. This is how Cline (and the `skills/gitea` skill) uses it.
|
|
|
|
```bash
|
|
# CLI examples
|
|
uv run --project . server/gitea_mcp.py --config ./config.json list_instances
|
|
uv run --project . server/gitea_mcp.py --config ./config.json get_repo --owner andrey --repo infra
|
|
uv run --project . server/gitea_mcp.py list-tools # self-describing catalogue
|
|
```
|
|
|
|
CLI output contract: exactly one JSON object — `{"success": true, "data": …}` or
|
|
`{"success": false, "error": …}`. Check the `success` field, not the exit code.
|
|
|
|
## Setup (one-time)
|
|
|
|
### 1. Edit config.json
|
|
|
|
Open `config.json` in the plugin folder and fill in your Gitea details:
|
|
|
|
```json
|
|
{
|
|
"instances": {
|
|
"default": {
|
|
"url": "https://your-gitea.example.com",
|
|
"token": "your_personal_access_token"
|
|
}
|
|
},
|
|
"default": "default"
|
|
}
|
|
```
|
|
|
|
### Multiple Gitea instances
|
|
|
|
```json
|
|
{
|
|
"instances": {
|
|
"home": {
|
|
"url": "https://gitea.home.example.com",
|
|
"token": "token_for_home"
|
|
},
|
|
"work": {
|
|
"url": "https://gitea.work.example.com",
|
|
"token": "token_for_work"
|
|
}
|
|
},
|
|
"default": "home"
|
|
}
|
|
```
|
|
|
|
Then in chat: "покажи репозитории на work" — Claude передаст `instance="work"` в инструмент.
|
|
|
|
### 2. Create a Gitea token
|
|
|
|
Gitea → Settings → Applications → Personal Access Tokens
|
|
|
|
Recommended permissions: `repo`, `issue`, `notification`, `user`, `organization`
|
|
|
|
### 3. Verify connection
|
|
|
|
After installing, ask: "проверь подключение к Gitea" — Claude вызовет `get_current_user` и `get_server_info`.
|
|
|
|
## Requirements
|
|
|
|
- `uv` installed (https://docs.astral.sh/uv/)
|
|
- Gitea instance accessible from your computer
|
|
|
|
## Tools (66)
|
|
|
|
| Category | Tools |
|
|
|----------|-------|
|
|
| Meta | list_instances, get_server_info, get_current_user |
|
|
| Repositories | list_my_repos, search_repos, get_repo, create_repo, create_org_repo, update_repo, delete_repo, fork_repo, set_repo_topics |
|
|
| Branches & Tags | list_branches, get_branch, create_branch, delete_branch, list_tags |
|
|
| Files | list_directory, get_file, create_file, update_file, delete_file |
|
|
| Issues | list_issues, get_issue, create_issue, update_issue, close_issue, reopen_issue, list_issue_comments, add_issue_comment, edit_issue_comment, delete_issue_comment |
|
|
| Labels & Milestones | list_labels, create_label, add_issue_labels, list_milestones, create_milestone |
|
|
| Pull Requests | list_pull_requests, get_pull_request, create_pull_request, update_pull_request, merge_pull_request, get_pr_diff, list_pr_files, list_pr_reviews, create_pr_review |
|
|
| Releases | list_releases, get_latest_release, create_release, delete_release |
|
|
| Webhooks | list_repo_webhooks, create_repo_webhook, delete_repo_webhook |
|
|
| Users & Orgs | get_user, search_users, list_my_orgs, get_org, list_org_repos, list_org_members, list_org_teams |
|
|
| Commits | list_commits, get_commit, compare_branches, list_repo_contributors |
|
|
| Notifications | list_notifications, mark_all_notifications_read |
|