Schema Introspection
Relevant source files
The following files were used as context for generating this wiki page:
Schema introspection in the GitHub MCP Server is the mechanism by which the server's capabilities—specifically its tools, toolsets, and resource templates—are programmatically explored and documented. This system allows clients to dynamically discover available functions, validate parameters against defined JSON schemas, and generate automated documentation or command-line interfaces based on the current state of the server code.
Sources: cmd/mcpcurl/README.md:1-15, cmd/github-mcp-server/generate_docs.go:25-30
Dynamic Tool Discovery
The GitHub MCP Server implementation utilizes the Model Context Protocol (MCP) to expose a list of available tools. This discovery process is facilitated primarily through the tools/list JSON-RPC method. Clients like mcpcurl connect to the server via standard input/output (stdio) and request the tool schema to build a local command structure dynamically.
Discovery Workflow
The following sequence illustrates how a client introspects the server to determine available functionality:
The server's response includes detailed metadata for each tool, including its name, description, and an InputSchema that defines required and optional parameters.
Sources: cmd/mcpcurl/README.md:105-115, cmd/mcpcurl/README.md:120-125
Automated Documentation Generation
A dedicated module within the server, generate_docs.go, performs static introspection of the codebase to update README.md and other documentation files. It uses a ToolsetGroup initialized with mock clients to evaluate the definitions of all registered tools without requiring live GitHub API connectivity.
Implementation Details
The documentation engine iterates through all toolsets (e.g., pull_requests, repos, issues) and extracts schema information using the following logic:
- Toolset Enumeration: Identifies all registered toolsets except
dynamicandcontext. - Tool Sorting: Available tools within each set are sorted alphabetically for deterministic output.
- Schema Extraction: For each tool, the
InputSchema.Propertiesare parsed to identify parameter names, types (including array types), descriptions, and requirement status.
| Introspection Step | Component Involved | Output Format |
|---|---|---|
| Load Toolsets | github.DefaultToolsetGroup | toolsets.ToolsetGroup object |
| Format Name | formatToolsetName | Human-readable string (e.g., "Pull Requests") |
| Parse Schema | generateToolDoc | Markdown list with name, type, required |
Sources: cmd/github-mcp-server/generate_docs.go:45-60, cmd/github-mcp-server/generate_docs.go:120-145, cmd/github-mcp-server/generate_docs.go:175-210
Schema-Based Validation
The introspection system ensures that tool calls are valid before they are processed by the GitHub API. This is achieved by mapping internal Go structures to MCP tool definitions. For example, the list_discussions tool defines its parameters using MCP-specific helper functions that establish the schema constraints.
Parameter Mapping
Tools define their schema using fluent API calls such as mcp.WithString, mcp.WithNumber, and mcp.Enum. These definitions include metadata that the server uses to validate incoming CallToolRequest objects.
// Example of a tool defining its introspectable schema
func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
return mcp.NewTool("list_discussions",
mcp.WithString("owner", mcp.Required(), mcp.Description("Repository owner")),
mcp.WithString("orderBy",
mcp.Description("Order discussions by field."),
mcp.Enum("CREATED_AT", "UPDATED_AT"),
),
// ... additional schema definitions
),
func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
// Internal validation using the defined schema
owner, err := RequiredParam[string](https://github.com/BablAdm/github-mcp-server/blob/HEAD/request%2C%20%22owner%22)
// ... handler logic
}
}
Sources: pkg/github/discussions.go:105-135, pkg/github/discussions.go:140-150
CLI Command Generation
The mcpcurl tool demonstrates a practical application of schema introspection. It interprets the JSON schema provided by the server to generate a CLI with the following features:
- Subcommands: Each MCP tool becomes a subcommand under
tools. - Flags: Command-line flags are automatically generated from the tool's input schema properties.
- Validation: The CLI handles type validation (e.g., ensuring
issue_numberis a float/number) and enum validation (restricting values to allowable sets defined in the schema) before sending the request to the server.
Sources: cmd/mcpcurl/README.md:10-15, cmd/mcpcurl/README.md:95-103
Testing and Verification
End-to-end (E2E) tests verify the introspection capabilities by initializing an MCPServer instance and calling ListTools. These tests ensure that the server correctly reports the existence of tools based on the enabled toolsets.
Tests specifically check that if a toolset (like pull_requests) is disabled, its corresponding tools (like get_pull_request) do not appear in the introspected tool list.
Sources: e2e/e2e_test.go:195-215, pkg/github/issues_test.go:30-40
Summary
Schema introspection provides the foundation for the GitHub MCP Server's flexibility. By exposing its internal tool definitions via standard JSON schemas, the server enables automated documentation, dynamic CLI generation, and robust parameter validation. This architecture ensures that as new GitHub API capabilities are added to the Go codebase, they are immediately discoverable and usable by any compliant MCP client without requiring manual client-side updates.