# gitea-mcp

Stdio MCP for Gitea's REST API. It exposes read-only access to user,
repository/content, refs, commits, issues, pull requests, releases, wiki,
actions, packages, and organisation data. Exact tool names and schemas live in
`cmd/gitea-mcp/tools_*.go`.

## Auth

`gitea-mcp` uses Gitea's OAuth2 server with PKCE and stores its session under
wallet key `gitea`. Gitea web SSO through Authentik is incidental; API tokens
are minted by Gitea.

Config is `[services.gitea]` with inline `issuer`, `client_id`, optional
`client_secret`, and `base_url`. Scopes are compiled in `cmd/gitea-mcp/main.go`;
after scope changes, clear the wallet entry with `sherlock logout gitea`.

## Operation

When `gitea-mcp` is installed, `sherlock <agent>` includes it in the generated
MCP config. The first tool call authenticates lazily; later calls use refreshed
keyring tokens. `gitea-mcp --probe` verifies auth and one API call without an
agent.

## Known limitation

Some Gitea versions narrow OAuth grants to `read:user` and `read:repository`.
Tools that require issue, organisation, or package scopes can return 403 even
though the MCP starts correctly. That is a Gitea-side scope grant issue, not a
sherlock startup failure.