# Architecture of the grep-mcp Server Leveraging FastMCP: A Technical Deep Dive

> Explore the grep-mcp server architecture. Learn how FastMCP, asynchronous patterns, and clean separation enable high-performance code search on GitHub.

- Repository: [gal peretz/grep-mcp](https://github.com/galprz/grep-mcp)
- Tags: architecture
- Published: 2026-02-16

---

The **grep-mcp** server demonstrates modern asynchronous architecture patterns by combining the **FastMCP** framework with intelligent response parsing and flexible transport layers. This lightweight Model Context Protocol (MCP) implementation enables high-performance code search across GitHub repositories while maintaining clean separation of concerns between API consumption, data transformation, and client communication.

## Core Architectural Components

The architecture rests on several pillars that work together to deliver seamless code search functionality:

| Component | Role | Key Implementation Details |
|-----------|------|-----------------------------|
| **FastMCP Instance** | Creates the MCP server and registers tools | Instantiated in [`server.py`](https://github.com/galprz/grep-mcp/blob/main/server.py) as `FastMCP("grep-mcp")`【/src/grep_mcp/server.py#L16-L18】 |
| **MCP Tool Registration** | Exposes the `grep_query` function to MCP clients | Decorated with `@mcp.tool()` in [`server.py`](https://github.com/galprz/grep-mcp/blob/main/server.py)【/src/grep_mcp/server.py#L51-L64】 |
| **Async HTTP Client** | Calls the external `grep.app` API without blocking the event loop | Uses `aiohttp.ClientSession` with a 30-second timeout【/src/grep_mcp/server.py#L25-L30】 |
| **Response Parser & Formatter** | Normalises JSON returned by `grep.app`, extracts snippets, line numbers, and adds syntax-highlighting markers | Functions `_extract_text_from_html`, `_extract_line_numbers`, `_get_language_from_extension`, `_format_code_snippet`, and `_format_grep_response` in [`server.py`](https://github.com/galprz/grep-mcp/blob/main/server.py)【/src/grep_mcp/server.py#L36-L58】【/src/grep_mcp/server.py#L66-L78】 |
| **Transport Layer** | Supports STDIO (default) for CLI-based MCP clients and SSE for web-based clients | Transport selection handled in `main()` via the `--transport` argument【/src/grep_mcp/server.py#L30-L34】 |
| **Starlette + SSE** | Wraps the MCP server for HTTP-based event streaming | `create_starlette_app` builds the Starlette instance and wires it to the MCP server via `SseServerTransport`【/src/grep_mcp/server.py#L61-L78】 |

## Modular Async Design in the grep-mcp Architecture

The **grep-mcp server architecture** follows a **modular, asynchronous design** that maximizes performance and scalability:

1. **FastMCP Initialization**: The lightweight MCP server object provides the foundation for tool registration and protocol compliance.

2. **Async HTTP Request Handling**: When the `grep_query` tool is invoked, it performs non-blocking API calls to `grep.app`, ensuring the event loop remains responsive during network I/O.

3. **Intelligent Response Transformation**: Raw API responses undergo parsing and normalization to extract structured data, including syntax-highlighted code snippets and precise line number mappings.

4. **Flexible Transport Abstraction**: The architecture seamlessly switches between STDIO and SSE transports based on deployment requirements, supporting both command-line MCP clients and web-based integrations.

5. **ASGI-Ready Deployment**: For browser-based or remote access, **Starlette** hosts SSE endpoints at `/sse` with message ingestion at `/messages/`, enabling real-time streaming capabilities.

## Implementation Examples

### STDIO Transport Mode (Default)

Launch the **grep-mcp server** using standard input/output for local MCP client connections:

```bash
python -m grep_mcp

```

*The server runs the FastMCP instance and listens on standard input/output, ready for MCP clients.*

### SSE Transport Mode for Web Integration

Deploy with **Server-Sent Events** for HTTP-based accessibility:

```bash
python -m grep_mcp --transport sse --host 0.0.0.0 --port 8080

```

*This launches a Starlette app that serves the MCP server over HTTP at `http://0.0.0.0:8080/sse`.*

### Client Integration Pattern

Connect to the **grep-mcp architecture** from Python MCP clients:

```python
from mcp.client import MCPClient

client = MCPClient("grep-mcp")  # Connects to the FastMCP server

result_json = client.call_tool(
    "grep_query",
    query="async def main",
    language="Python",
    repo="fastapi/fastapi",
    path="src/"
)

print(result_json)  # Structured JSON with snippets and statistics

```

### Core HTTP Logic

The underlying async pattern driving the **grep-mcp server** search functionality:

```python
import aiohttp, asyncio

async def fetch_grep_results(query):
    url = "https://grep.app/api/search"
    params = {"q": query}
    async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30)) as sess:
        async with sess.get(url, params=params) as resp:
            data = await resp.json()
            return data

```

*The actual `grep_query` implementation extends this pattern with validation, error handling, and response formatting.*

## Project Structure and Key Files

Understanding the **architecture of the grep-mcp server** requires familiarity with its organized codebase:

| File | Purpose | Link |
|------|---------|------|
| [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py) | Core server, FastMCP initialization, tool registration, transport handling, response formatting | [server.py](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py) |
| [`src/grep_mcp/__main__.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/__main__.py) | Entry-point module that invokes `main()` | [__main__.py](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/__main__.py) |
| [`pyproject.toml`](https://github.com/galprz/grep-mcp/blob/main/pyproject.toml) | Project metadata, dependencies, console-script entry point | [pyproject.toml](https://github.com/galprz/grep-mcp/blob/main/pyproject.toml) |
| [`README.md`](https://github.com/galprz/grep-mcp/blob/main/README.md) | High-level documentation, usage instructions, **grep-mcp architecture** overview | [README.md](https://github.com/galprz/grep-mcp/blob/main/README.md) |

These files collectively define the complete **FastMCP-based architecture**, demonstrating how asynchronous HTTP calls, intelligent response processing, and transport flexibility combine to deliver robust code search capabilities for AI assistants and development tools.