┌─────────────────────┐          ┌─────────────────────┐
│     MCP Client      │   stdio  │     MCP Server      │
│                     │◄────────►│                     │
│  • Rich CLI/Chat    │  JSON-   │  • FastMCP Router   │
│  • ClientSession    │  RPC 2.0 │  • 5 Registered     │
│  • Tool Discovery   │          │    Tools            │
└─────────────────────┘          └─────────────────────┘

User
 ↓
Client UI (Rich terminal)
 ↓
ClientSession.call_tool(name, arguments)
 ↓
JSON-RPC 2.0 Request (serialized)
 ↓
stdio Transport (stdin pipe to server subprocess)
 ↓
FastMCP Server (deserializes, routes by tool name)
 ↓
@mcp.tool() Function → Pydantic validation → Business logic
 ↓
JSON Response (consistent format)
 ↓
stdio Transport (stdout pipe back to client)
 ↓
ClientSession (deserializes response)
 ↓
Rich UI (pretty-prints with syntax highlighting)
 ↓
User sees the result ✅

Client                          Server
  |                               |
  |──── initialize() ───────────►|
  |◄──── capabilities ──────────|
  |                               |
  |──── list_tools() ───────────►|
  |◄──── tool schemas ──────────|
  |       (name, description,     |
  |        inputSchema)           |
  |                               |
  |  Client now knows all tools!  |

mcp-learning-project/
│
├── server/                    # MCP Server (the "backend")
│   ├── __init__.py           # Package marker
│   ├── server.py             # FastMCP setup + tool registration
│   ├── tools.py              # Pure business logic (no MCP dependency)
│   ├── models.py             # Pydantic validation models
│   └── quotes.py             # Hardcoded quote data
│
├── client/                    # MCP Client (the "frontend")
│   ├── __init__.py           # Package marker
│   ├── client.py             # Interactive CLI client
│   ├── chat.py               # Natural language chat interface
│   └── ui.py                 # Rich terminal UI helpers
│
├── diagrams/                  # Documentation
│   └── architecture.md       # Mermaid architecture diagrams
│
├── logs/                      # Generated at runtime
│   └── app.log               # Structured application logs
│
├── screenshots/               # Screenshots placeholder
│
├── README.md                  # This file
├── pyproject.toml            # Project configuration
├── uv.lock                   # Dependency lock file (auto-generated)
└── .gitignore                # Git ignore rules

# 1. Clone the repository
git clone <repository-url>
cd mcp-learning-project

# 2. Create a virtual environment and install dependencies
uv sync

# This will:
# - Create a .venv/ directory
# - Install mcp[cli], pydantic, and rich
# - Generate uv.lock for reproducibility

uv run python -m client.client

uv run python -m client.chat

uv run python -m server.server

npx -y @modelcontextprotocol/inspector uv run python -m server.server

╭─────────────────────────────────────────────╮
│ 🔌 MCP Learning Client                     │
│    Connected to MCP Server via stdio        │
╰─────────────────────────────────────────────╯

┌──────────────────────────────────────────────┐
│            📋 Available Tools                │
├────┬────────────────┬────────────────────────┤
│ #  │ Tool Name      │ Description            │
├────┼────────────────┼────────────────────────┤
│ 1  │ current_time   │ Get the current UTC    │
│    │                │ time in ISO 8601       │
├────┼────────────────┼────────────────────────┤
│ 2  │ calculator     │ Perform arithmetic     │
│    │                │ operations             │
├────┼────────────────┼────────────────────────┤
│ 3  │ random_quote   │ Get a random           │
│    │                │ inspirational quote    │
├────┼────────────────┼────────────────────────┤
│ 4  │ weather        │ Get mock weather data  │
├────┼────────────────┼────────────────────────┤
│ 5  │ uuid_generator │ Generate a random UUID │
└────┴────────────────┴────────────────────────┘

>>> 2
Enter calculator inputs:
  First number (a): 45
  Second number (b): 87
  Operation (add/subtract/multiply/divide): multiply
⏳ Calling calculator...
╭─── ✅ Success ───╮
│ {                │
│   "result": 3915 │
│ }                │
╰──────────────────╯
⏱  Completed in 0.023s

>>> info weather
📌 weather

Get mock weather data for an Indian city.

📥 Input Schema:
{
  "type": "object",
  "properties": {
    "city": { "type": "string" }
  },
  "required": ["city"]
}

>>> exit
👋 Goodbye!

🤖 MCP Chat Interface
Ask me about weather, calculations, time, quotes, or UUIDs.
Type 'exit' to quit.

You: What is the weather in Jaipur?
⏳ Calling weather tool...
╭─── 🤖 Assistant ───╮
│ 🌤️  Weather in      │
│ Jaipur: 35°C, Sunny │
╰─────────────────────╯

You: Multiply 45 and 87
⏳ Calling calculator tool...
╭─── 🤖 Assistant ───╮
│ 🔢 The answer is:   │
│ 3915.0               │
╰─────────────────────╯

You: Give me an inspirational quote
⏳ Calling random_quote tool...
╭───── 🤖 Assistant ─────╮
│ 💬 "Stay hungry, stay   │
│ foolish. — Steve Jobs"  │
╰─────────────────────────╯

2026-07-08 10:30:15 | INFO    | mcp.server | FastMCP server instance created: 'MCP Learning Server'
2026-07-08 10:30:15 | INFO    | mcp.server | Starting MCP Learning Server (stdio transport)...
2026-07-08 10:30:16 | INFO    | mcp.client | Client starting — connecting to MCP server...
2026-07-08 10:30:16 | INFO    | mcp.client | stdio transport established
2026-07-08 10:30:16 | INFO    | mcp.client | MCP session initialized
2026-07-08 10:30:16 | INFO    | mcp.client | Discovered 5 tools: ['current_time', 'calculator', ...]
2026-07-08 10:30:20 | INFO    | mcp.client | Calling tool: calculator with args: {'a': 45, 'b': 87, 'operation': 'multiply'}
2026-07-08 10:30:20 | INFO    | mcp.server | Tool called: calculator(a=45.0, b=87.0, op=multiply)
2026-07-08 10:30:20 | INFO    | mcp.server | Tool result: calculator → {'success': True, 'data': {'result': 3915.0}}
2026-07-08 10:30:20 | INFO    | mcp.client | Tool calculator completed in 0.023s

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My Server")

@mcp.tool(
    name="calculator",
    description="Perform arithmetic operations"
)
def calculator(a: float, b: float, operation: str) -> str:
    # FastMCP auto-generates a JSON Schema from the function signature:
    # {
    #   "type": "object",
    #   "properties": {
    #     "a": {"type": "number"},
    #     "b": {"type": "number"},
    #     "operation": {"type": "string"}
    #   },
    #   "required": ["a", "b", "operation"]
    # }
    ...

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# 1. Define how to launch the server
server_params = StdioServerParameters(
    command="uv",
    args=["run", "python", "-m", "server.server"]
)

# 2. Connect via stdio
async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # 3. Initialize the session (handshake)
        await session.initialize()

        # 4. Discover all tools
        tools = await session.list_tools()
        # tools.tools → list of Tool objects with name, description, inputSchema

        # 5. Call a specific tool
        result = await session.call_tool("calculator", {"a": 10, "b": 20, "operation": "add"})

// Client → Server (request)
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "calculator",
    "arguments": {"a": 10, "b": 20, "operation": "add"}
  }
}

// Server → Client (response)
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"success\": true, \"data\": {\"result\": 30.0}}"
      }
    ]
  }
}

def my_tool(input_param: str) -> dict[str, Any]:
    """Do something useful."""
    return ToolResponse.ok(result="Hello!")

class MyToolInput(BaseModel):
    input_param: str = Field(..., min_length=1)

@mcp.tool(name="my_tool", description="Does something useful")
def tool_my_tool(input_param: str) -> str:
    return json.dumps(my_tool(input_param))