How openai/sample-deep-research-mcp works
Project type and purpose
• This is a minimalist Python-based microservice (an MCP server) whose sole job is to search and fetch “cupcake” orders from a local JSON data store. It exposes an HTTP SSE endpoint for clients to stream search results.
File structure
• Top-level files only:
• sample_mcp.py – the Python server implementation
• records.json – flat JSON file containing cupcake orders
• requirements.txt – Python dependencies (likely MCP library, SSE support)
• README.md, LICENSE, .gitignore – documentation & project metadata
README for additional insights
• The server listens on http://127.0.0.1:8000 using SSE transport
• No external database or multi-module code – it reads directly from records.json
• Dependency on “Deep Research style MCP” framework (imported in sample_mcp.py)
Main components and their relationships
a. Components
• Client (could be browser, CLI, other MCP-aware consumer)
• SSE Transport Layer (HTTP endpoint in sample_mcp.py)
• MCP Server Logic (sample_mcp.py)
• Data Store (records.json)
b. Data flow & interactions
1. Client issues an MCP query (over HTTP) → SSE endpoint
2. Server logic loads/parses records.json
3. Server filters/matches orders per query
4. Server pushes matching results back to client as SSE events
c. Architectural patterns
• Single-module microservice pattern
• File-based data store instead of full RDBMS/NoSQL
• Event-streaming (Server-Sent Events) as communication pattern
d. Key technologies
• Python 3.x
• “Deep Research style” MCP framework (in sample_mcp.py)
• SSE (HTTP event stream)
• JSON for data persistence
Detailed capture of essential elements
• Configuration detail if sample_mcp.py references a port or endpoint path.
• Streaming nature of the response.