Proto Server

# MCP Proto Server A Model Context Protocol (MCP) server that indexes Protocol Buffer (.proto) files and exposes their structure to AI agents. ## Features - 🔍 **Recursive Scanning**: Automatically discovers all .proto files in a directory tree - 📦 **Full Parsing**: Extracts packages, services, RPCs, messages, enums, and comments - 🔎 **Fuzzy Search**: Fast fuzzy matching across names, fields, and comments - 🚀 **MCP Compliant**: Standard MCP server with structured JSON outputs - ⚡ **Recursive Type Resolution**: Automatically resolves all nested types in a single call (8-15x efficiency gain!) - 📊 **Efficient**: Handles thousands of proto files with minimal memory footprint - 🔄 **File Watching**: Optional auto-reindexing on file changes ## Installation ```bash pip install -r requirements.txt ``` ## Usage ### Basic Usage ```bash # Index a directory of proto files python mcp_proto_server.py --root /path/to/protos # Use environment variable export PROTO_ROOT=/path/to/protos python mcp_proto_server.py # Enable file watching for auto-reindexing python mcp_proto_server.py --root /path/to/protos --watch ``` ### MCP Tools The server exposes three main tools: #### 1. search_proto Fuzzy search across all proto definitions (services, messages, enums, fields, comments). ```json { "query": "UserService" } ``` #### 2. get_service_definition Get complete service definition including all RPC methods. ```json { "name": "UserService" } ``` #### 3. get_message_definition Get message structure with all fields and types. ```json { "name": "User" } ``` ## Architecture ``` mcp-proto/ ├── mcp_proto_server.py # Main MCP server entry point ├── proto_parser.py # Proto file parser ├── proto_indexer.py # In-memory index with search ├── requirements.txt # Python dependencies └── examples/ # Example proto files ``` ### Components 1. **proto_parser.py**: Parses .proto files using a custom lexer/parser - Handles proto2 and proto3 syntax - Extracts comments, options, and metadata - No external gRPC dependencies needed 2. **proto_indexer.py**: Manages the searchable index - In-memory data structures for fast lookup - Fuzzy search with RapidFuzz - Incremental updates for file watching 3. **mcp_proto_server.py**: MCP server implementation - Uses official MCP Python SDK - Exposes tools as MCP resources - Structured JSON responses ## Example Queries ### Search for authentication-related definitions ``` search_proto("authentication") → Returns all services, messages with "auth" in name/fields/comments ``` ### Get a specific service ``` get_service_definition("UserService") → Returns full RPC method list with request/response types ``` ### Get message structure ``` get_message_definition("CreateUserRequest") → Returns all fields with types and comments ``` ## Configuration | Variable | Description | Default | |----------|-------------|---------| | `PROTO_ROOT` | Root directory to scan | Current directory | | `--watch` | Enable file watching | Disabled | | `--verbose` | Enable debug logging | Disabled | ## Performance - **Indexing**: ~1000 files/second on modern hardware - **Search**: Sub-millisecond fuzzy matching - **Memory**: ~1-2 KB per proto definition ## Future Enhancements - [ ] Semantic embeddings for advanced search - [ ] Persistent caching with SQLite - [ ] Import resolution and dependency graphs - [ ] REST API wrapper - [ ] gRPC reflection integration