Contributing

How to Contribute

We welcome contributions to the GitHub MCP Server. Bug fixes, new features, documentation, and tests are all valuable.

Ways to Contribute

• Report bugs: open an issue on GitHub.
• Suggest features: start a discussion with context and expected behavior.
• Improve docs: fix typos, add examples, clarify steps.
• Add tests: increase coverage for existing modules.
• Submit code: fixes or new capabilities aligned with project goals.

Development Setup

1. Fork and clone the repository:

   git clone https://github.com/YOUR-USERNAME/github-go-server-mcp.git
   cd github-go-server-mcp

2. Install dependencies: Go 1.25.0+ and go mod tidy.

3. Run tests:

   go test ./...

4. Build the server:

   go build -o github-mcp-server-v3 ./cmd/github-mcp-server/

Contribution Guidelines

• Follow standard Go conventions (gofmt, go vet).
• Use conventional commits (feat:, fix:, docs:…).
• Add tests for new features; keep existing tests green.
• Describe pull requests clearly and link related issues.
• Update documentation when behavior or APIs change.

Tip

Before a large feature, open an issue to align on approach and avoid duplicate work.

Project Architecture

Modular Structure (Updated 2026-02-11)

The project follows Go 1.25 best practices with a highly modular architecture:

Core Directories

• cmd/github-mcp-server/ - Main entry point and application bootstrap
• internal/server/ - MCP server implementation and handlers
• pkg/ - Reusable packages and libraries
  • git/ - Git operations (split into 5 focused modules)
  • github/ - GitHub API client wrapper
  • admin/ - Administrative operations
  • safety/ - 4-tier safety system
  • types/ - Shared type definitions

Tool Definitions (Modular Organization)

All tool definitions are organized by category in internal/server/:

internal/server/
├── server.go                          # Main MCP handler (728 lines)
├── tool_definitions_git_info.go       # 8 Git info tools
├── tool_definitions_git_basic.go      # 5 basic Git tools
├── tool_definitions_git_advanced.go   # 21 advanced Git tools
├── tool_definitions_hybrid.go         # 3 hybrid tools
├── tool_definitions_github.go         # 4 GitHub API tools
├── tool_definitions_dashboard.go      # 7 dashboard tools
├── tool_definitions_response.go       # 3 response tools
├── tool_definitions_repair.go         # 7 repair tools
├── admin_tools.go                     # 22 admin tools
└── tool_annotations.go                # Annotation helpers

Benefits: Easy navigation, minimal merge conflicts, clear responsibility separation

Git Operations (4 Focused Modules)

Git operations in pkg/git/ are split by functionality:

pkg/git/
├── operations.go          # Base infrastructure (176 lines)
├── operations_basic.go    # 12 basic operations (219 lines)
├── operations_files.go    # 8 file operations (245 lines)
├── operations_branch.go   # 9 branch/merge operations (535 lines)
└── operations_advanced.go # 19 advanced operations (967 lines)

Benefits: High cohesion, better parallel compilation, easier testing

Adding New Tools

1. Choose the appropriate category file in internal/server/:

   • Git info → tool_definitions_git_info.go
   • Basic Git → tool_definitions_git_basic.go
   • GitHub API → tool_definitions_github.go
   • Admin → admin_tools.go

2. Add tool definition using the types.Tool struct:

   {
       Name:        "tool_name",
       Title:       "Human-Readable Title",
       Description: "Clear description",
       InputSchema: types.ToolInputSchema{
           Type: "object",
           Properties: map[string]types.Property{
               "param": {Type: "string", Description: "Parameter description"},
           },
           Required: []string{"param"},
       },
       Annotations: ReadOnlyAnnotation(), // or DestructiveAnnotation(), etc.
   }

3. Add handler in the CallTool() switch in server.go.

4. Implement the operation in the relevant package (pkg/git/, pkg/github/, etc.).

5. Run tests: go test ./....

---

Release Notes

Release notes and version history are now in a separate page: Release Notes →

• v2.1.0 (2024-10-20): Advanced Git operations + conflict management
• v2.0.0 (2024-10-15): Complete rewrite in Go with JSON-RPC 2.0
• v1.0.0 (2024-10-01): Initial release

Changelog Format

This project follows Keep a Changelog and Semantic Versioning.

Change Types

• 🚀 Added: New features
• 🔧 Changed: Changes to existing functionality
• 🗑️ Deprecated: Features that will be removed
• ❌ Removed: Removed features
• 🐛 Fixed: Bug fixes
• 🛡️ Security: Security improvements
• 🔄 Updated: Dependency updates
• 🧪 Testing: Test-related changes
• 🎨 Code Quality: Code quality improvements
• 📚 Documentation: Documentation changes

License

This project is licensed under the MIT License. By contributing, you agree that your contributions will be licensed under the same license.