mcpcurl: CLI Overview
Relevant source files
The following files were used as context for generating this wiki page:
mcpcurl is a command-line interface (CLI) tool designed to dynamically interact with Model Context Protocol (MCP) servers. Its primary purpose is to bridge the gap between structured MCP tool schemas and a traditional terminal environment by automatically generating CLI commands based on the capabilities exposed by a connected server.
Within the context of the github-mcp-server project, mcpcurl serves as a versatile debugging and administrative utility. It allows developers to execute GitHub-specific operations—such as managing issues, repositories, and pull requests—directly from the command line by communicating with the MCP server via standard input/output (stdio).
Sources: cmd/mcpcurl/README.md:1-12, cmd/github-mcp-server/main.go:34-45
Core Architecture and Data Flow
The architecture of mcpcurl is built upon dynamic discovery. Rather than having hardcoded commands for every GitHub operation, it relies on the MCP server's self-describing nature to build its interface at runtime.
Dynamic Command Generation
The tool follows a multi-step process to initialize its command structure:
- Server Connection: It establishes a connection to an MCP server using a shell command provided via the
--stdio-server-cmdflag. - Schema Retrieval: It issues a JSON-RPC request (
tools/list) to the server. - Command Building: Based on the returned JSON schema, it generates subcommands under the
toolscategory. Each tool's parameters are converted into CLI flags. - Validation: It applies validation logic for required parameters, data types, and enums as defined in the server's input schema.
Sources: cmd/mcpcurl/README.md:105-115, cmd/mcpcurl/README.md:95-103
Request Execution Flow
The following diagram illustrates the sequence of operations when a user executes a command like mcpcurl tools get_issue:
This flow ensures that mcpcurl acts as a transparent proxy that enforces the server's contract without needing internal knowledge of the GitHub API.
Sources: cmd/mcpcurl/README.md:105-115, e2e/e2e_test.go:130-150
Command Structure and Usage
mcpcurl provides a hierarchical command structure. While the tools command is the most significant due to its dynamic nature, other static commands facilitate schema inspection.
Global Configuration
The tool requires specific global flags to establish the environment for the MCP server.
| Flag | Type | Description | Required |
|---|---|---|---|
--stdio-server-cmd | string | Shell command to invoke the MCP server (e.g., docker run ... or a local binary). | Yes |
--pretty | boolean | Pretty print JSON responses (defaults to true). | No |
Sources: cmd/mcpcurl/README.md:41-45, cmd/mcpcurl/README.md:65-68
Primary Commands
tools: The root for all dynamically discovered tool subcommands.- Example:
mcpcurl tools create_issue --owner ... --repo ... --title ... - Includes help text generated directly from the tool's description in the MCP schema.
- Example:
schema: Fetches and displays the raw JSON schema provided by the MCP server. This is useful for debugging the interface between the client and server.help: Standard CLI help functionality accessible for any subcommand.
Sources: cmd/mcpcurl/README.md:47-53, cmd/mcpcurl/README.md:95-103
Integration with GitHub MCP Tools
When used with the github-mcp-server, mcpcurl exposes a wide array of GitHub-specific capabilities. These tools are implemented in the pkg/github module and are exposed via the MCP protocol.
Resource Management Examples
The following table highlights key tools that become available in mcpcurl when connected to the GitHub MCP server:
| Tool Name | Parameters (Partial) | Implementation Source |
|---|---|---|
get_issue | owner, repo, issue_number | pkg/github/issues.go:185 |
create_issue | owner, repo, title, body | pkg/github/issues.go:510 |
list_commits | owner, repo, sha, author | pkg/github/repositories.go:85 |
push_files | owner, repo, branch, files | pkg/github/repositories.go:515 |
get_file_contents | owner, repo, path, ref | pkg/github/repositories.go:330 |
Logic for Path Matching in get_file_contents
When a user requests file contents through the CLI, the underlying server logic handles cases where the exact path might not be known. If a path does not point directly to a file or directory, the server attempts to find matching paths in the Git tree.
Server Instantiation for CLI Use
To use mcpcurl with the project's server, the server must be started in stdio mode. The github-mcp-server main entry point provides this command, which mcpcurl then invokes.
// From cmd/github-mcp-server/main.go
var stdioCmd = &cobra.Command{
Use: "stdio",
Short: "Start stdio server",
RunE: func(_ *cobra.Command, _ []string) error {
token := viper.GetString("personal_access_token")
// ... configuration setup ...
return ghmcp.RunStdioServer(stdioServerConfig)
},
}
In practice, a user might run:
./mcpcurl --stdio-server-cmd "./github-mcp-server stdio" tools list_issues --owner golang --repo go
Sources: cmd/github-mcp-server/main.go:34-60, cmd/mcpcurl/README.md:41-45
Summary
mcpcurl is an essential component of the github-mcp-server ecosystem, providing a dynamic and type-safe way to interact with GitHub via the Model Context Protocol. By leveraging JSON-RPC and stdio communication, it transforms complex server-side tool schemas into an accessible command-line interface, enabling efficient management of GitHub resources without requiring a custom CLI for every new feature.