MCP Protocol Implementation

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/github-mcp-server/main.go
• cmd/mcpcurl/README.md
• pkg/github/repositories.go
• cmd/github-mcp-server/generate_docs.go
• e2e/e2e_test.go
• pkg/github/workflow_prompts.go

The Model Context Protocol (MCP) implementation in this project provides a standardized interface for AI models to interact with GitHub resources. It acts as a bridge between the MCP JSON-RPC protocol and the GitHub API, enabling models to perform actions such as repository management, file operations, and workflow automation.

The implementation supports various transport mechanisms, primarily stdio, and categorizes capabilities into "toolsets" that can be selectively enabled. This architecture allows for dynamic tool discovery, strict parameter validation, and secure execution of GitHub operations.
Sources: cmd/github-mcp-server/main.go:34-45, cmd/mcpcurl/README.md:5-10, e2e/e2e_test.go:136-146

Architecture and Components

The server is built using the mcp-go SDK and follows a modular design where GitHub capabilities are exposed as MCP Tools, Resources, and Prompts.

Core Server Lifecycle

The server initializes by parsing configuration through cobra and viper. It can be started in a stdio mode, which facilitates communication via standard input/output streams using JSON-RPC messages. During initialization, the server negotiates protocol versions and provides server metadata to the client.

The flow starts with command-line execution and transitions into a persistent JSON-RPC loop.
Sources: cmd/github-mcp-server/main.go:34-58, e2e/e2e_test.go:158-166

Configuration Options

The server behavior is controlled through global flags and environment variables.

Option	Type	Description	Default
toolsets	StringSlice	Comma-separated list of tool groups to enable	All tools
read-only	Bool	Restricts operations to read-only GitHub calls	false
gh-host	String	GitHub hostname for Enterprise installations	github.com
dynamic-toolsets	Bool	Enables dynamic discovery of toolsets	false
content-window-size	Int	Specifies size of content window for results	5000

Sources: cmd/github-mcp-server/main.go:81-94

MCP Tools Implementation

Tools represent the executable actions available to the AI model. Each tool is defined with a name, description, input schema (JSON Schema), and a handler function.

Repository and File Operations

The repositories.go file implements several core MCP tools. For example, get_file_contents uses a multi-stage resolution logic to fetch file data, supporting branch, tag, and SHA references.

This sequence illustrates the data flow for retrieving repository content.
Sources: pkg/github/repositories.go:354-410, pkg/github/repositories.go:773-830

Key Implemented Tools

Tools are grouped into functional areas. Below is a subset of the repository management tools:

Tool Name	Parameters (Required)	Description
create_repository	name	Creates a new repo in personal account or org.
get_file_contents	owner, repo	Fetches file or directory content.
push_files	owner, repo, branch, files, message	Pushes multiple files in one commit.
create_branch	owner, repo, branch	Creates a new branch from a source branch.
delete_file	owner, repo, path, message, branch	Deletes a file using Git Data API for signing.

Sources: pkg/github/repositories.go:281-295, pkg/github/repositories.go:572-595, pkg/github/repositories.go:683-714

Workflow Prompts

Prompts are predefined instruction sets or "guided workflows" that assist the model in completing complex tasks. These are registered as mcp.Prompt types.

IssueToFixWorkflow

This workflow provides a multi-step sequence for problem resolution:

1. Creation: Model creates a well-structured GitHub issue.
2. Assignment: The issue is assigned to a coding agent (e.g., Copilot).
3. Monitoring: The process monitors for Pull Request creation.

The handler returns a GetPromptResult containing a list of PromptMessage objects that set the context for the model.
Sources: pkg/github/workflow_prompts.go:13-35

Documentation and Schema Discovery

The implementation includes an automated documentation system that generates Markdown descriptions of all available tools by introspecting the toolsets.

Tool Discovery Mechanism

1. The tools/list JSON-RPC method is called by the client.
2. The server iterates through enabled toolsets.
3. Each tool's JSON Schema is exported to the client.
4. Clients like mcpcurl use this to dynamically build CLI commands or validation logic.

Sources: cmd/mcpcurl/README.md:105-111, cmd/github-mcp-server/generate_docs.go:132-156

Protocol Testing (E2E)

End-to-End tests verify the protocol implementation by spinning up the server and interacting with it using an actual MCP Client.

• Stdio Client: Tests use mcpClient.NewStdioMCPClient to execute the server binary (often via Docker) and communicate over pipes.
• In-Process Client: For debugging, the tests can run the server in-process using mcpClient.NewInProcessClient.
• Verification: Tests validate lifecycle events like Initialize and functional calls like CallTool.

Sources: e2e/e2e_test.go:94-115, e2e/e2e_test.go:150-166

The MCP implementation provides a robust, schema-driven interface for GitHub interactions, ensuring that AI models can operate within defined constraints while leveraging complex GitHub workflows.