How grep-mcp Parses Command-Line Arguments to Select the Transport Mode

The grep-mcp entry point uses Python's argparse module to parse the --transport flag, defaulting to stdio mode while supporting sse for web-based communication.

The grep-mcp repository (galprz/grep-mcp) implements a Model Context Protocol (MCP) server that exposes grep functionality to AI assistants. When launching the server, the main entry point must determine whether to communicate via standard input/output or over HTTP using Server-Sent Events. This transport mode selection is handled through a robust command-line argument parsing system implemented in the core server module.

Entry Point Architecture

The executable entry point follows a minimal bootstrap pattern that delegates all logic to the main server implementation.

The __main__.py Bootstrap

The file src/grep_mcp/__main__.py serves as the package entry point. It contains minimal boilerplate that imports and immediately invokes the main() function from the server.py module:

# src/grep_mcp/__main__.py

from grep_mcp.server import main

main()

This separation of concerns ensures that argument parsing and server initialization logic resides in a dedicated module while maintaining a clean executable interface.

Argument Parser Setup in server.py

Inside src/grep_mcp/server.py, the main() function constructs an argparse.ArgumentParser instance and defines three critical parameters that control server behavior:

# src/grep_mcp/server.py

import argparse

def main():
    parser = argparse.ArgumentParser(description='Grep MCP Server')
    parser.add_argument(
        '--transport',
        choices=['stdio', 'sse'],
        default='stdio',
        help='Transport mode (stdio or sse)'
    )
    parser.add_argument(
        '--host',
        default='0.0.0.0',
        help='Host to bind to (for SSE mode)'
    )
    parser.add_argument(
        '--port',
        type=int,
        default=8080,
        help='Port to listen on (for SSE mode)'
    )
    
    args = parser.parse_args()
    # Transport selection logic follows...

The --transport argument uses the choices constraint to restrict inputs to either stdio or sse, with stdio serving as the default for backward compatibility and CLI usage. The --host and --port arguments are typed specifically for the SSE transport mode, allowing users to configure the network binding when running the server as a web service.

Transport Mode Selection Logic

After parsing completes, the main() function evaluates args.transport to determine which execution path to initialize. This branching logic cleanly separates the two transport implementations.

Standard I/O Mode (stdio)

When args.transport equals 'stdio' (the default), the server invokes the MCP instance's run() method with the transport parameter explicitly set:

# src/grep_mcp/server.py

if args.transport == 'stdio':
    mcp.run(transport='stdio')

This mode establishes a standard input/output communication channel between the MCP server and its client (typically an AI assistant or IDE). The server reads JSON-RPC messages from stdin and writes responses to stdout, making it ideal for local process spawning and pipe-based integration.

Server-Sent Events Mode (sse)

When the user specifies --transport sse, the server transitions to HTTP-based communication using Server-Sent Events. This path requires additional setup:

# src/grep_mcp/server.py

elif args.transport == 'sse':
    from starlette.applications import Starlette
    import uvicorn
    
    # Create the Starlette application with SSE endpoints

    app = create_starlette_app(mcp)
    
    # Launch the Uvicorn server with configured host and port

    uvicorn.run(app, host=args.host, port=args.port)

In this mode, the create_starlette_app() function (defined elsewhere in the module) constructs a Starlette application that exposes the MCP endpoints over HTTP. The server then launches Uvicorn as the ASGI server, binding to the host and port values parsed from the command line. This transport mode enables remote clients to connect to the grep functionality over the network, supporting browser-based AI assistants or distributed architectures.

Practical Usage Examples

The command-line interface supports both local CLI integration and network deployment scenarios.

Run the server in default stdio mode for local AI assistant integration:

# Default stdio mode (no flags required)

python -m grep_mcp

# Explicit stdio specification

python -m grep_mcp --transport stdio

Deploy the server as a web service with custom network binding:

# SSE mode with default host (0.0.0.0) and port (8080)

python -m grep_mcp --transport sse

# SSE mode with custom binding

python -m grep_mcp --transport sse --host 127.0.0.1 --port 9000

Summary

• The entry point at src/grep_mcp/__main__.py delegates to main() in server.py, maintaining clean separation between bootstrap and logic.
• Argument parsing uses Python's argparse module to define --transport, --host, and --port parameters, with stdio as the default transport.
• Transport selection branches on args.transport: stdio mode invokes mcp.run(transport='stdio') for standard I/O, while sse mode constructs a Starlette application and launches Uvicorn with the configured host and port.
• The implementation supports both local process integration via pipes and network deployment via HTTP Server-Sent Events.

Frequently Asked Questions

What is the default transport mode when running grep-mcp without arguments?

The default transport mode is stdio (standard input/output). When you run python -m grep_mcp without specifying --transport, the argument parser automatically sets the transport to stdio, enabling immediate communication via pipes for local AI assistant integration.

How do I run grep-mcp as a web server instead of a command-line tool?

To run grep-mcp as a web server, specify --transport sse when launching the module. This mode activates the Server-Sent Events transport, which creates a Starlette application and starts a Uvicorn server. You can optionally customize the network binding using --host and --port parameters.

Why does the SSE transport mode require host and port arguments while stdio does not?

The SSE (Server-Sent Events) transport operates over HTTP, requiring a network socket to bind to a specific IP address and port number for incoming client connections. In contrast, stdio mode communicates through the process's standard input and output streams, which are already established by the operating system when the process starts, eliminating the need for network configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}