forgejo-mcp/CLAUDE.md

Forgejo MCP Server

A Model Context Protocol (MCP) server that enables MCP clients to interact with Gitea/Forgejo repositories.

Project Overview

This project provides MCP integration for managing Forgejo/Gitea repositories through MCP-compatible clients such as Claude Desktop, Continue, and other LLM applications.

Supported Operations

• Issues (create, edit, comment, close)
• Labels (list, create, edit, delete)
• Milestones (list, create, edit, delete)
• Releases (list, create, edit, delete, manage assets)
• Pull requests (list, view)
• Repository search and listing
• Wiki pages (create, edit, delete)
• Forgejo Actions tasks (view)

Transport Modes

• stdio: Standard input/output (best for local integration)
• sse: Server-Sent Events over HTTP (best for web apps) - planned
• http: HTTP POST requests (best for simple integrations) - planned

Architecture

Core Components

• cmd/: CLI application using Cobra framework
  • root.go: Main command with global configuration
  • stdio.go: Stdio transport mode implementation
• types/: Data structures and response types
  • api.go: MCP response types wrapping Forgejo SDK types
• main.go: Application entry point

Key Dependencies

• MCP SDK: github.com/modelcontextprotocol/go-sdk
  • There are 3 important sub packages: mcp, jsonschema and jsonrpc
• Forgejo SDK: codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v2
• CLI Framework: github.com/spf13/cobra
• Configuration: github.com/spf13/viper

If you need to get documentation of these packages, go doc should be the best bet.

Implementation Strategy

• 🟢 SDK-based (71%): Use official Forgejo SDK where available
• 🟡 Custom HTTP (29%): Implement custom requests for unsupported features (Wiki, Actions, Issue dependencies)

Configuration

CLI Arguments

forgejo-mcp stdio --server https://git.example.com --token your_token

Environment Variables

• FORGEJOMCP_SERVER: Forgejo server URL
• FORGEJOMCP_TOKEN: Access token

Config File

Default location: ~/.forgejo-mcp.yaml

Priority: CLI args > Environment variables > Config file

Development

Language and Style

• Code/Comments: English (open source project)
• Documentation: English (unless .tw.md suffix for Traditional Chinese)

Key Files

• proposal.tw.md: Project requirements (Traditional Chinese)
• features.tw.md: Feature specifications (Traditional Chinese)
• design.tw.md: Architecture documentation (Traditional Chinese)
• swagger.v1.json: API documentation

Response Format

• Error responses: Plain text
• Success responses: Markdown format in MCP TextContent.Text field
• Structured data: Dual format (markdown + JSON) for MCP compatibility

Architecture Decisions

• Use endpoint-based markdown formatting rather than type-based to avoid LLM confusion
• Each data type implements ToMarkdown() method for reusability
• Endpoint handlers add context-specific headers and descriptions
• Tool responses: Use single TextContent with markdown formatting (follows MCP best practices)
• Tool organization: Mixed modular architecture with sub-packages for logical grouping

Tool Architecture

The project uses a mixed modular architecture for organizing MCP tools:

Structure

tools/
├── module.go           # ToolImpl interface definition
├── registry.go         # Unified tool registration
├── helpers.go          # Shared utility functions
├── issue/              # Issue-related operations
│   ├── crud.go         # create/edit/delete issue
│   ├── list.go         # list_issues
│   ├── comment.go      # issue comments
│   ├── label.go        # issue label operations
│   ├── attach.go       # issue attachments
│   └── dep.go          # issue dependencies
├── label/              # Label management
│   └── crud.go         # all label operations
├── milestone/          # Milestone management
│   └── crud.go         # all milestone operations
├── release/            # Release management
│   ├── crud.go         # create/edit/delete release
│   └── attach.go       # release attachments
├── pullreq/            # Pull Request operations
│   ├── list.go         # list pull requests
│   └── view.go         # get pull request details
├── action/             # Forgejo Actions (CI/CD)
│   └── list.go         # list_action_tasks
├── wiki/               # Wiki pages
│   ├── crud.go         # create/edit/delete wiki pages
│   └── list.go         # list wiki pages
└── repo/               # Repository operations
    └── list.go         # repository listing and search

Design Principles

• Logical grouping: Related tools grouped in sub-packages
• Single responsibility: Each file handles closely related operations
• Interface-driven: All tools implement the ToolImpl interface
• Extensibility: Easy to add new tools and categories
• Testability: Each module can be independently tested

Development Workflow

1. Test-Driven Development (TDD)
2. Red-Green-Refactor cycle
3. Human review at each step
4. Git commit after each milestone

Useful Commands

Go Commands

# Build the project for release
go build -o forgejo-mcp

# Check compilation error
go build ./...

# Run tests
go test ./...

# Format code
goimports -w .

# Get dependencies
go mod tidy

Swagger

# Find definition of specified api endpoint
#   .paths["/path/to/endpoint"].http_method
jq '.paths["/repos/{owner}/{repo}/labels/{id}"].patch' swagger.v1.json

# Get summary string of specified api endpoint
#   .paths["/path/to/endpoint"].http_method.summary
#
# Change "summary" to "parameters" or "responses" to get params/responses
jq '.paths["/repos/{owner}/{repo}/labels/{id}"].patch.summary' swagger.v1.json

# Get referenced type definition
#
# for "$refs": "#/abc/def"
jq '.abc.def' swagger.v1.json

Additional tools

• my-git-server: Tools to access remote git server. The repository is ronmi/forgejo-mcp.
• gopls: Go language server to query for difinitions, references, and more.