feat: dual-mode — MCP server and CLI skill in one file

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.
This commit is contained in:
2026-06-24 10:44:46 +03:00
parent a6162a855c
commit 9a5750ddca
9 changed files with 543 additions and 130 deletions
+20
View File
@@ -2,6 +2,26 @@
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