mirror of https://gitea.com/gitea/gitea-mcp.git synced 2026-03-13 16:35:12 +00:00

Files

silverwind bba612d238 Consolidate tools from 110 to 45 using method dispatch (#143 )

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>

2026-03-06 19:12:15 +00:00

3.3 KiB

Raw Permalink Blame History

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