Hiddenden/AegisGitea-MCP
5
0 Fork 0
Code Issues 2 Pull Requests Actions Packages Projects 1 Releases 1 Wiki Activity

docs: fix the claude mcp add form, pin the package index, document known limitations

Browse Source 
The --env option swallowed the server name, so the stdio command is reordered. uvx now always
names the project registry because the package name is not registered on public PyPI.
README gains a Known limitations section, the READ_ONLY wording is corrected, packaging.md
warns about --extra-index-url and the Le Chat admin requirement is mentioned.
This commit is contained in:
Latte committed 2026-10-14 18:01:19 +02:00
1 parent 8786502b8c
commit 59d0e43aae
8 files changed
+102 -34
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+38 -9
View File
@@ -145,9 +145,12 @@ Gitea token, `<MCP_BEARER_TOKEN>` is the value from the env file.
Claude Code:
```bash
claude mcp add --transport stdio --env GITEA_URL=https://git.example.com --env GITEA_TOKEN=<your-gitea-token> aegis-gitea -- uvx aegis-gitea-mcp
claude mcp add --env GITEA_URL=https://git.example.com --env GITEA_TOKEN=<your-gitea-token> --transport stdio aegis-gitea -- uvx --index https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/ aegis-gitea-mcp
```
Keep `--transport stdio` and the server name after the `--env` options: `--env` accepts several
values, so an option placed before the name would swallow it.
Claude Desktop, Cursor and other local clients that read an `mcpServers` block:
```json
@@ -155,7 +158,7 @@ Claude Desktop, Cursor and other local clients that read an `mcpServers` block:
"mcpServers": {
"aegis-gitea": {
"command": "uvx",
"args": ["aegis-gitea-mcp"],
"args": ["--index", "https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/", "aegis-gitea-mcp"],
"env": {
"GITEA_URL": "https://git.example.com",
"GITEA_TOKEN": "<your-gitea-token>"
@@ -165,9 +168,16 @@ Claude Desktop, Cursor and other local clients that read an `mcpServers` block:
}
```
`uvx` installs the package from your configured index (see [packaging.md](docs/packaging.md)
for the Gitea registry). To run from a clone instead, use `uv` as the command with the
arguments `--directory /path/to/AegisGitea-MCP run aegis-gitea-mcp`.
Always pass the `--index` of the project's registry. The name `aegis-gitea-mcp` is not
registered on public PyPI, so a bare `uvx aegis-gitea-mcp` would resolve there, and whoever
registers that name would receive your Gitea token through the environment. The owner should
reserve the name on PyPI to close that gap (see [packaging.md](docs/packaging.md)). To run from
a clone instead, use `uv` as the command with the arguments
`run --directory /path/to/AegisGitea-MCP aegis-gitea-mcp serve`, or on the command line:
```bash
claude mcp add --env GITEA_URL=https://git.example.com --env GITEA_TOKEN=<your-gitea-token> --transport stdio aegis-gitea -- uv run --directory /path/to/AegisGitea-MCP aegis-gitea-mcp serve
```
### Remote streamable HTTP
@@ -184,7 +194,8 @@ claude.ai custom connector: Settings, Connectors, Add custom connector, URL
Claude registers itself (dynamic client registration) and sends you to Gitea to sign in.
Mistral Le Chat custom connector: Intelligence, Connectors, Add Connector, Custom MCP
Connector, URL `https://gitea-mcp.example.com/mcp` (HTTPS with a valid certificate).
Connector, URL `https://gitea-mcp.example.com/mcp` (HTTPS with a valid certificate). Adding
connectors in Le Chat may require workspace admin rights.
Authentication is either HTTP Bearer Token with the `MCP_BEARER_TOKEN` value, or OAuth 2.1 with
dynamic client registration so users sign in with their own Gitea account.
@@ -267,7 +278,7 @@ you with mode 0600 (what `setup` writes); any other `./.env` is ignored with a w
| `MCP_HOST`, `MCP_PORT`, `MCP_PATH` | `127.0.0.1`, `8080`, `/mcp` | HTTP bind and endpoint path |
| `MCP_BEARER_TOKEN` | unset | Static bearer for HTTP, at least 32 characters |
| `OAUTH_ENABLED` | `false` | Per-user OAuth on HTTP |
| `READ_ONLY` | `false` | Expose only read-only operations |
| `READ_ONLY` | `false` | Expose only operations annotated read-only |
| `TOOLSETS` | `all` | Comma separated domains to expose |
| `DISABLED_TOOLS` | empty | Tool names to hide |
| `SECRET_DETECTION_MODE` | `mask` | `off`, `mask` or `block` |
@@ -277,8 +288,10 @@ Every variable, its default and its validation rules are in
## What is config-gated, and what is impossible
Config-gated, all optional: `READ_ONLY` (only GET operations, and `gitea_api_request` accepts
only GET), `TOOLSETS` (domains), `DISABLED_TOOLS` (single tools, an unknown name is a startup
Config-gated, all optional: `READ_ONLY` (exposes only the operations annotated read-only, which
are the GET operations plus a few POST endpoints that do not change anything, such as the
markdown and markup render endpoints and the file-contents query; `gitea_api_request` stays
listed but accepts only GET), `TOOLSETS` (domains), `DISABLED_TOOLS` (single tools, an unknown name is a startup
error), and `SECRET_DETECTION_MODE` (`mask` replaces secret-like strings in results, `block`
withholds a result that contains one, `off` disables it; exact redaction of the server's own
tokens always applies). A filtered tool is neither listed nor callable.
@@ -288,6 +301,22 @@ writes to the instance configuration, and instance-wide OAuth applications (UI o
registers its OAuth application as a user application of the admin). `gitea_api_request` reaches
anything newer than the pinned spec once Gitea ships it.
## Known limitations
A token with the `all` scope does not make every tool work. Check
[docs/integration-coverage.md](docs/integration-coverage.md), generated by running every tool
against a live Gitea 28.1.0, for the per-tool outcome.
- `gitea_user_create_token`, `gitea_user_get_tokens` and `gitea_user_delete_access_token` need
basic authentication with the account password (a Gitea API rule). The server always sends
token authentication, so these three return 401 through it. Create tokens in the Gitea UI.
- Some operations depend on instance state and answer 404 or an error until it exists: the
commit signing keys (`gitea_misc_get_signing_key`, `gitea_repo_signing_key` and their SSH
variants) when the instance has none, user badges (Gitea cannot create badges through the
API), unadopted repositories, and similar. The coverage report lists them with the reason.
- Tools that depend on a runner, such as workflow runs and jobs, only return data once an
Actions runner is registered.
## Result and error format
A successful call returns one text item with JSON (see