How alucek/quick-mcp-example works
Project type and purpose
• This is a minimal example of a Model Context Protocol (MCP) system, consisting of:
– An MCP Server (“mcp_server.py”) exposing tools, resources, prompts
– A CLI-based MCP Client (“client.py”) that connects to and interacts with the server
– Supplementary material (not code) in “MCP_Setup.ipynb” for vector-DB setup
• Purpose: demonstrate how to standardize LLM interactions by plugging in data sources (vector DB), invoking tools, selecting resources, and running preset prompts via the protocol
File structure
• Top-level scripts
– mcp_server.py: server implementation (HTTP or RPC endpoints, tool and resource registration)
– client.py: simple command-line client that connects to the server, passes messages, displays responses
• Configuration files
– pyproject.toml, uv.lock, .python-version: dependency and environment management
– .gitignore
• Documentation & assets
– MCP_Setup.ipynb: Jupyter notebook to build the Chroma vector DB and embed PDF content
– media/: static images (mcp_arch.png, core_comp.png, mcp_plan.png)
Extract architecture insights from README
• Three logical roles in MCP ecosystem:
– Servers: expose tools (function calls), resources (URIs), prompts (templates)
– Clients: manage connections, LLM integration, message routing
– Hosts (not implemented here): UI layers, embedding in larger applications
• Example flow:
1. Client connects to server
2. Server advertises available tools/resources/prompts
3. Client requests context or executes tool (e.g. vector DB query via Chroma)
4. LLM responses pass back through client for display
a. Main components
– CLI Client (client.py)
– MCP Server (mcp_server.py)
– Vector Database (ChromaDB instance configured via MCP_Setup.ipynb)
– LLM Provider (external API or local model invoked by client)
– Static Resources (PDFs, config files exposed by server)
– Prompts registry (in-memory or file-backed templates)
b. Relationships & data flow
1. Client initializes and opens protocol connection to Server
2. Server registers and advertises:
• Tools → e.g. “vector_search()”
• Resources → e.g. “/datasets/manual.pdf”
• Prompts → e.g. “summarize_document”
3. Client requests resource list; user selects context
4. Client sends LLM request, optionally invoking tool → Server calls ChromaDB, returns results
5. Client feeds tool output or static resource into LLM prompt via LLM Provider
6. LLM response routed back to Client for display in CLI
c. Architectural patterns & principles
– Protocol-oriented modularity: server interface decoupled from client UI
– Single responsibility: each component focuses on one concern (tool execution, message passing, data storage)
– Plug-and-play extensibility: new servers, clients or hosts can be introduced without breaking the protocol
d. Key technologies & frameworks
– Python (async or sync HTTP/RPC framework in mcp_server.py)
– ChromaDB for vector retrieval
– Jupyter Notebook for initial DB setup (MCP_Setup.ipynb)
– uv for virtual environment & dependency management
– Standard JSON-RPC or HTTP for client-server communication
– Client (CLI)
– MCP Server
– Vector Database
– LLM Provider
– Static Resources
– Prompts Registry
– Client → Server (API call: listTools, callTool, listResources, runPrompt)
– Server → Vector DB (tool invocation: vector_search)
– Client → LLM Provider (final prompt execution)
– Resource fetch (Client or Server → Static Resources)
– Blue for compute components (Client, Server)
– Green for data stores (ChromaDB, Static Resources)
– Orange for external services (LLM Provider)
Detail without over-complication
• Every protocol endpoint or message type relevant to this example
• Where tools vs. resources vs. prompts diverge in the flow