mirror of
https://gitea.com/gitea/gitea-mcp.git
synced 2026-03-14 17:05:14 +00:00
bba612d238
Consolidate 110 individual MCP tools down to 45 using a method dispatch pattern, aligning tool names with the GitHub MCP server conventions. **Motivation:** LLMs work better with fewer, well-organized tools. The method dispatch pattern (used by GitHub's MCP server) groups related operations under read/write tools with a `method` parameter. **Changes:** - Group related tools into `_read`/`_write` pairs with method dispatch (e.g. `issue_read`, `issue_write`, `pull_request_read`, `pull_request_write`) - Rename tools to match GitHub MCP naming (`get_file_contents`, `create_or_update_file`, `list_issues`, `list_pull_requests`, etc.) - Rename `pageSize` to `perPage` for GitHub MCP compat - Move issue label ops (`add_labels`, `remove_label`, etc.) into `issue_write` - Merge `create_file`/`update_file` into `create_or_update_file` with optional `sha` - Make `delete_file` require `sha` - Add `get_labels` method to `issue_read` - Add shared helpers: `GetInt64Slice`, `GetStringSlice`, `GetPagination` in params package - Unexport all dispatch handler functions - Fix: pass assignees/milestone in `CreateIssue`, bounds check in `GetFileContent` Reviewed-on: https://gitea.com/gitea/gitea-mcp/pulls/143 Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com> Co-authored-by: silverwind <me@silverwind.io> Co-committed-by: silverwind <me@silverwind.io>
79 lines
3.3 KiB
Markdown
79 lines
3.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Development Commands
|
|
|
|
**Build**: `make build` - Build the gitea-mcp binary
|
|
**Install**: `make install` - Build and install to GOPATH/bin
|
|
**Clean**: `make clean` - Remove build artifacts
|
|
**Test**: `go test ./...` - Run all tests
|
|
**Hot reload**: `make dev` - Start development server with hot reload (requires air)
|
|
**Dependencies**: `make vendor` - Tidy and verify module dependencies
|
|
|
|
## Architecture Overview
|
|
|
|
This is a **Gitea MCP (Model Context Protocol) Server** written in Go that provides MCP tools for interacting with Gitea repositories, issues, pull requests, users, and more.
|
|
|
|
**Core Components**:
|
|
|
|
- `main.go` + `cmd/cmd.go`: CLI entry point and flag parsing
|
|
- `operation/operation.go`: Main server setup and tool registration
|
|
- `pkg/tool/tool.go`: Tool registry with read/write categorization
|
|
- `operation/*/`: Individual tool modules (user, repo, issue, pull, search, wiki, etc.)
|
|
|
|
**Transport Modes**:
|
|
|
|
- **stdio** (default): Standard input/output for MCP clients
|
|
- **http**: HTTP server mode on configurable port (default 8080)
|
|
|
|
**Authentication**:
|
|
|
|
- Global token via `--token` flag or `GITEA_ACCESS_TOKEN` env var
|
|
- HTTP mode supports per-request Bearer token override in Authorization header
|
|
- Token precedence: HTTP Authorization header > CLI flag > environment variable
|
|
|
|
**Tool Organization**:
|
|
|
|
- Tools are categorized as read-only or write operations
|
|
- `--read-only` flag exposes only read tools
|
|
- Tool modules register via `Tool.RegisterRead()` and `Tool.RegisterWrite()`
|
|
|
|
**Key Configuration**:
|
|
|
|
- Default Gitea host: `https://gitea.com` (override with `--host` or `GITEA_HOST`)
|
|
- Environment variables can override CLI flags: `MCP_MODE`, `GITEA_READONLY`, `GITEA_DEBUG`, `GITEA_INSECURE`
|
|
- Logs are written to `~/.gitea-mcp/gitea-mcp.log` with rotation
|
|
|
|
## Available Tools
|
|
|
|
The server provides 45 MCP tools covering:
|
|
|
|
- **User**: get_me, get_user_orgs
|
|
- **Search**: search_users, search_repos, search_org_teams
|
|
- **Repository**: create_repo, fork_repo, list_my_repos
|
|
- **Branches**: list_branches, create_branch, delete_branch
|
|
- **Tags**: list_tags, get_tag, create_tag, delete_tag
|
|
- **Files**: get_file_contents, get_dir_contents, create_or_update_file, delete_file
|
|
- **Commits**: list_commits
|
|
- **Issues**: list_issues, issue_read, issue_write
|
|
- **Pull Requests**: list_pull_requests, pull_request_read, pull_request_write, pull_request_review_write
|
|
- **Labels**: label_read, label_write
|
|
- **Milestones**: milestone_read, milestone_write
|
|
- **Releases**: list_releases, get_release, get_latest_release, create_release, delete_release
|
|
- **Wiki**: wiki_read, wiki_write
|
|
- **Time Tracking**: timetracking_read, timetracking_write
|
|
- **Actions Runs**: actions_run_read, actions_run_write
|
|
- **Actions Config**: actions_config_read, actions_config_write
|
|
- **Version**: get_gitea_mcp_server_version
|
|
|
|
## Common Development Patterns
|
|
|
|
**Testing**: Use `go test ./operation -run TestFunctionName` for specific tests
|
|
|
|
**Token Context**: HTTP requests use `pkg/context.TokenContextKey` for request-scoped token access
|
|
|
|
**Flag Access**: All packages access configuration via global variables in `pkg/flag/flag.go`
|
|
|
|
**Graceful Shutdown**: HTTP mode implements graceful shutdown with 10-second timeout on SIGTERM/SIGINT
|