mcp-server-demo

A repo to start with MCP servers and clients.

References: Demo Document Assistant US Weather

To run mcp server

uv run python server/demo.py 

uv run python server/doc_assistant.py 

uv run python server/us_weather.py 

To run mcp client

uv run python client/doc_assistant_client.py 

To test end-to-end message sequence

uv --directory <path-to-your-server-directory> run demo.py

uv --directory <path-to-your-server-directory> run doc_assistant.py

uv --directory <path-to-your-server-directory> run us_weather.py

In the stdout console, type below one by one:

jsonc
CopyEdit
// 1️⃣  Client → Server  ─── initialize ──────────────────────────────────────────
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "clientInfo": { "name": "demo-client", "version": "1.0.0" },
    "capabilities": { "tools": {}, "resources": {} }
  }
}

/* 3️⃣  Client → Server  ─── initialized notification -- no id (fire-and-forget) */
{ "jsonrpc": "2.0", "method": "notifications/initialized" }

/* 4️⃣  Client → Server  ─── tools/list ───────────────────────────────────────── */
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

/* 6️⃣  Client → Server  ─── tools/call ───────────────────────────────────────── */
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "calculate_sum",
    "arguments": { "a": 4, "b": 3 }
  }
}

We should be able to see responses similar to below:

/* 2️⃣  Server → Client  ─── InitializeResult ─────────────────────────────────── */
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "serverInfo": { "name": "demo-server", "version": "1.0.0" },
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": {}
    }
  }
}

/* 5️⃣  Server → Client  ─── list result -- includes inputSchema ─────────────── */
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "calculate_sum",
        "description": "Add two numbers together",
        "inputSchema": {
          "type": "object",
          "properties": {
            "a": { "type": "number" },
            "b": { "type": "number" }
          },
          "required": ["a", "b"]
        }
      }
    ]
  }
}

/* 7️⃣  Server → [external world]  ─ (does the addition)  ─────────────────────── */

/* 8️⃣  Server → Client  ─── result -- structure per schema/2025-03-26 ───────── */
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "7" }
    ]
  }
}