# genmcp/grpc-demo architecture

> Architecture diagram of the GitHub repository genmcp/grpc-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/genmcp/grpc-demo
- Repository: https://github.com/genmcp/grpc-demo

## Overview

##### Project Type and Purpose
- This is a demo full-stack “service-exposure” pipeline. It bridges an existing gRPC service to AI models by converting binary gRPC into JSON/HTTP and then into the Model-Context Protocol (MCP).
- Key objective: show how to expose an untouchable gRPC service to LLMs without modifying its code, using gRPC-Gateway and `gen-mcp`.

##### File Structure
Top-level directories:
- 000_grpc_server – the original gRPC server (Go, .proto, generated pb.go files, main.go)
- 001_grpc_proxy – the gRPC-Gateway HTTP/JSON proxy (config YAMLs, swagger.json, generated pb.go and pb.gw.go)
- 002_genmcp_grpc – the MCP exposure service (mcpfile.yaml)
Other artifacts: go.mod/go.sum in each, indicating independent Go modules.

##### README Insights
- Confirms three independent services running on ports:
- gRPC Server on 50051
- HTTP Proxy on 9090
- MCP Server on 8080

##### Main Components
a. AI Model (LLM)
b. MCP Server (`gen-mcp` service; reads mcpfile.yaml; port 8080)
c. HTTP Proxy (gRPC-Gateway service; port 9090)
d. gRPC Server (Core Feature service; port 50051)
e. Supporting artifacts (feature.proto, generated stubs)

##### Component Interactions & Data Flow
1. AI Model issues a tool call (JSON) → MCP Server
2. MCP Server transforms JSON tool call → HTTP GET/POST → HTTP Proxy
3. HTTP Proxy uses gRPC-Gateway to convert HTTP/JSON to gRPC call → gRPC Server
4. gRPC Server processes the request, returns Protobuf response → HTTP Proxy
5. HTTP Proxy serializes to JSON → MCP Server
6. MCP Server returns JSON tool output → AI Model

##### Architectural Patterns & Design Principles
- Layered Proxy Pattern: binary gRPC layer remains untouched; an HTTP proxy layer isolates translation concerns.
- Single-Responsibility per service: each module has a clear role (serve, proxy, expose).
- Configuration-driven: YAML configs for gateway and MCP, minimizing code changes.

##### Technologies and Frameworks to Label
- Go (programming language)
- gRPC + Protobuf (000_grpc_server)
- grpc-gateway (001_grpc_proxy)
- OpenAPI/Swagger (generated JSON)
- gen-mcp (002_genmcp_grpc; Model-Context Protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD
    AI["AI Model (LLM)"]:::external
    SharedProto["features.proto"]:::artifact
    MCP["MCP Server<br/>Port: 8080"]:::mcp
    Proxy["HTTP Proxy<br/>Port: 9090"]:::proxy
    Server["gRPC Server<br/>Port: 50051"]:::grpc

    AI -->|"1. JSON RPC"| MCP
    MCP -->|"2. HTTP GET/POST"| Proxy
    Proxy -->|"3. gRPC GetTopFeature()"| Server
    Server -->|"4. Protobuf Response"| Proxy
    Proxy -->|"5. JSON"| MCP
    MCP -->|"6. JSON Tool Output"| AI

    SharedProto -.-> Server
    SharedProto -.-> Proxy

    click Server "https://github.com/genmcp/grpc-demo/tree/main/000_grpc_server/"
    click SharedProto "https://github.com/genmcp/grpc-demo/blob/main/000_grpc_server/features.proto"
    click Proxy "https://github.com/genmcp/grpc-demo/tree/main/001_grpc_proxy/"
    click MCP "https://github.com/genmcp/grpc-demo/tree/main/002_genmcp_grpc/"

    classDef external stroke-dasharray: 5 5,fill:none,stroke:#999;
    classDef mcp fill:#9f6,stroke:#333;
    classDef proxy fill:#f96,stroke:#333;
    classDef grpc fill:#6cf,stroke:#333;
    classDef artifact fill:#ccc,stroke:#333;
```
