How oscargbocanegra/mcp-for-beginners works
Project type and purpose
• This is a minimal “hands-on tutorial” demonstrating a Model Context Protocol (MCP) server/client setup in Python.
• It uses FastMCP (server framework) and the MCP Python SDK (client library) to illustrate basic tool registration and invocation, plus resource endpoints (greeting/farewell).
File structure
• Top level:
• mcp_demo/
– server.py → defines and runs an MCP server
– client.py → connects to that server and invokes tools/resources
• pyproject.toml, requirements.txt, uv.lock → Python packaging & dependency management
• .github/, update-readme.sh → CI/docs tasks
• No database or external service folders yet—pure in-process client↔server via stdio/JSON-RPC.
README for additional insights
• Confirms Python 3.12+ environment managed by uv
• Server exposes four math tools and two resource endpoints
• Client uses session.call_tool() and session.call_resource()
• Communication is over stdio pipes orchestrated by uv
Main components and interactions
a. Components
1. Python Host Environment (runs both client & server processes)
2. uv Package Manager (bootstraps environment & pipelines)
3. MCP Server (FastMCP)
– Tool Registry (add, subtract, multiply, divide)
– Resource Handlers (greeting://, farewell://)
4. MCP Client (Python SDK session)
5. JSON-RPC over stdio (communication channel)
b. Relationships & data flow
• Client issues JSON-RPC requests → STDIO pipe → Server
• Server looks up tool/resource → executes handler → returns JSON-RPC response → STDIO → Client
c. Architectural patterns
• RPC-style microservice (1 process per role)
• Plugin-like tool registration (decorator-driven)
• Clear separation of concerns: server-side tool logic vs. client-side invocation
d. Key technologies
• FastMCP (server framework)
• python-sdk MCP (client library)
• uv (package manager & runner)
• Python 3.12+