ai/gitea-mcp
1
0
Fork 0
mirror of https://gitea.com/gitea/gitea-mcp.git synced 2025-10-29 09:21:49 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
gitea-mcp/CLAUDE.md
appleboy e4aa29b0f9 docs: document development workflow and MCP tool usage 
- Add CLAUDE.md file with guidance for using Claude Code in this repository
- Document development commands, architecture overview, and tool organization
- List available MCP tools with their main categories and functions
- Provide notes on configuration, authentication, and common development practices

Signed-off-by: appleboy <appleboy.tw@gmail.com>
2025-09-27 19:17:00 +08:00

3.0 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 40+ MCP tools covering:

  • User: get_my_user_info, get_user_orgs, search_users
  • Repository: create_repo, fork_repo, list_my_repos, search_repos
  • Branches/Tags: create_branch, delete_branch, list_branches, create_tag, list_tags
  • Files: get_file_content, create_file, update_file, delete_file, get_dir_content
  • Issues: create_issue, list_repo_issues, create_issue_comment, edit_issue
  • Pull Requests: create_pull_request, list_repo_pull_requests, get_pull_request_by_index
  • Releases: create_release, list_releases, get_latest_release
  • Wiki: create_wiki_page, update_wiki_page, list_wiki_pages
  • Search: search_repos, search_users, search_org_teams
  • 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