更新示例 README.md，添加天气服务器和客户端的详细信息；新增 MCP 兼容的天气服务器和客户端示例

jiayuqi7813 · jiayuqi7813 · commit 8cf50a618736 · 2026-03-19T17:05:00.000+08:00
diff --git a/examples/README.md b/examples/README.md
@@ -5,8 +5,19 @@ to new users.
 
 ## Minimal
 
-- `zcp_weather_server.py`: smallest native ZCP server
-- `run_zcp_mcp_stdio_server.py`: smallest MCP-compatible stdio server
+- `weather_zcp_server.py`: smallest native ZCP weather server (`/zcp`)
+- `weather_zcp_client.py`: matching native ZCP client using a prompt-driven OpenAI-compatible tool loop
+- `weather_mcp_server.py`: smallest MCP-compatible stdio weather server
+- `weather_mcp_client.py`: matching official MCP client using a prompt-driven OpenAI-compatible tool loop
+
+If you want to run the prompt-driven client examples, install the optional dependencies first:
+
+```bash
+pip install "zero-context-protocol-sdk[mcp,openai]"
+```
+
+The client examples expect one of `OPENAI_API_KEY` or `DEEPSEEK_API_KEY`, plus optional
+`OPENAI_BASE_URL` and `OPENAI_MODEL`.
 
 ## Production-shaped
 
diff --git a/examples/weather_mcp_client.py b/examples/weather_mcp_client.py
@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Minimal prompt-driven official MCP client for the weather server example."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from typing import Any
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+SERVER_SCRIPT = ROOT / "examples" / "weather_mcp_server.py"
+
+try:
+    from mcp.client.session import ClientSession
+    from mcp.client.stdio import StdioServerParameters, stdio_client
+except ModuleNotFoundError as exc:  # pragma: no cover
+    raise RuntimeError("Install the optional MCP dependency first: pip install 'zero-context-protocol-sdk[mcp]'") from exc
+
+try:
+    from openai import OpenAI
+except ModuleNotFoundError as exc:  # pragma: no cover
+    raise RuntimeError("Install the optional OpenAI dependency first: pip install 'zero-context-protocol-sdk[openai]'") from exc
+
+
+def _model_client() -> OpenAI:
+    api_key = os.environ.get("OPENAI_API_KEY") or os.environ.get("DEEPSEEK_API_KEY")
+    if not api_key:
+        raise RuntimeError("Set OPENAI_API_KEY or DEEPSEEK_API_KEY before running this example.")
+    return OpenAI(
+        api_key=api_key,
+        base_url=os.environ.get("OPENAI_BASE_URL", "https://api.deepseek.com"),
+    )
+
+
+def _tool_spec(tool: Any) -> dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": tool.name,
+            "description": tool.description or "",
+            "parameters": tool.inputSchema,
+            "strict": True,
+        },
+    }
+
+
+async def run(query: str) -> dict[str, object]:
+    async with stdio_client(
+        StdioServerParameters(
+            command=sys.executable,
+            args=[str(SERVER_SCRIPT)],
+            cwd=str(ROOT),
+        )
+    ) as (read_stream, write_stream):
+        async with ClientSession(read_stream, write_stream) as session:
+            await session.initialize()
+            tools = await session.list_tools()
+            llm = _model_client()
+            model = os.environ.get("OPENAI_MODEL", "deepseek-chat")
+            messages: list[dict[str, Any]] = [
+                {
+                    "role": "system",
+                    "content": "You are a helpful weather assistant. Use tools when the user asks about weather. Keep the final answer concise.",
+                },
+                {
+                    "role": "user",
+                    "content": query,
+                },
+            ]
+            tool_specs = [_tool_spec(tool) for tool in tools.tools]
+            tool_log: list[dict[str, Any]] = []
+
+            for _ in range(4):
+                response = llm.chat.completions.create(
+                    model=model,
+                    messages=messages,
+                    tools=tool_specs,
+                    tool_choice="auto",
+                )
+                message = response.choices[0].message
+                assistant_payload = message.model_dump(exclude_none=True)
+                messages.append(assistant_payload)
+                tool_calls = message.tool_calls or []
+                if not tool_calls:
+                    return {
+                        "tool_names": [tool.name for tool in tools.tools],
+                        "tool_log": tool_log,
+                        "answer": message.content,
+                    }
+                for tool_call in tool_calls:
+                    arguments = json.loads(tool_call.function.arguments or "{}")
+                    result = await session.call_tool(tool_call.function.name, arguments)
+                    payload: Any = result.structured_content
+                    if payload is None and result.content:
+                        payload = {"content": [block.text for block in result.content]}
+                    tool_log.append({"name": tool_call.function.name, "arguments": arguments, "result": payload})
+                    messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": tool_call.id,
+                            "content": json.dumps(payload, ensure_ascii=False),
+                        }
+                    )
+            return {
+                "tool_names": [tool.name for tool in tools.tools],
+                "tool_log": tool_log,
+                "answer": "Model did not finish within the maximum number of tool rounds.",
+            }
+
+
+def main() -> None:
+    query = " ".join(sys.argv[1:]) or "请查询 Hangzhou 当前天气，并用一句话总结。"
+    print(json.dumps(asyncio.run(run(query)), ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/weather_mcp_server.py b/examples/weather_mcp_server.py
@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Minimal MCP-compatible weather server backed by ZCP."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+from zcp import FastZCP
+from zcp.mcp_stdio import run_mcp_stdio_server_sync
+
+
+app = FastZCP("Weather MCP Compatibility Server", version="0.1.0")
+
+
+@app.tool(
+    name="weather.get_current",
+    description="Get the current weather for a city.",
+    input_schema={
+        "type": "object",
+        "properties": {
+            "city": {"type": "string"},
+            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
+        },
+        "required": ["city"],
+        "additionalProperties": False,
+    },
+    output_schema={
+        "type": "object",
+        "properties": {
+            "city": {"type": "string"},
+            "unit": {"type": "string"},
+            "temperature": {"type": "integer"},
+            "condition": {"type": "string"},
+        },
+        "required": ["city", "unit", "temperature", "condition"],
+        "additionalProperties": False,
+    },
+    output_mode="scalar",
+    inline_ok=True,
+)
+def get_current_weather(city: str, unit: str = "celsius") -> dict[str, object]:
+    base = {
+        "hangzhou": {"temperature": 24, "condition": "Cloudy"},
+        "beijing": {"temperature": 18, "condition": "Sunny"},
+        "shanghai": {"temperature": 22, "condition": "Rainy"},
+    }
+    payload = base.get(city.strip().lower(), {"temperature": 20, "condition": "Unknown"})
+    return {"city": city, "unit": unit, **payload}
+
+
+def main() -> None:
+    run_mcp_stdio_server_sync(app)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/weather_zcp_client.py b/examples/weather_zcp_client.py
@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Minimal prompt-driven ZCP client for the native weather server example."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from typing import Any
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+from examples.weather_zcp_server import app
+from zcp import streamable_http_client, streamable_http_server
+
+try:
+    from openai import OpenAI
+except ModuleNotFoundError as exc:  # pragma: no cover
+    raise RuntimeError("Install the optional OpenAI dependency first: pip install 'zero-context-protocol-sdk[openai]'") from exc
+
+
+def _model_client() -> OpenAI:
+    api_key = os.environ.get("OPENAI_API_KEY") or os.environ.get("DEEPSEEK_API_KEY")
+    if not api_key:
+        raise RuntimeError("Set OPENAI_API_KEY or DEEPSEEK_API_KEY before running this example.")
+    return OpenAI(
+        api_key=api_key,
+        base_url=os.environ.get("OPENAI_BASE_URL", "https://api.deepseek.com"),
+    )
+
+
+def _tool_spec(tool: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": tool["name"],
+            "description": tool.get("description") or "",
+            "parameters": tool["inputSchema"],
+            "strict": True,
+        },
+    }
+
+
+async def run(query: str) -> dict[str, object]:
+    client = streamable_http_client(streamable_http_server(app, endpoint="http://127.0.0.1:8000/zcp"))
+    init = await client.initialize()
+    await client.initialized()
+    tools = await client.list_tools()
+    llm = _model_client()
+    model = os.environ.get("OPENAI_MODEL", "deepseek-chat")
+    messages: list[dict[str, Any]] = [
+        {
+            "role": "system",
+            "content": "You are a helpful weather assistant. Use tools when the user asks about weather. Keep the final answer concise.",
+        },
+        {
+            "role": "user",
+            "content": query,
+        },
+    ]
+    tool_specs = [_tool_spec(tool) for tool in tools["tools"]]
+    tool_log: list[dict[str, Any]] = []
+
+    for _ in range(4):
+        response = llm.chat.completions.create(
+            model=model,
+            messages=messages,
+            tools=tool_specs,
+            tool_choice="auto",
+        )
+        message = response.choices[0].message
+        assistant_payload = message.model_dump(exclude_none=True)
+        messages.append(assistant_payload)
+        tool_calls = message.tool_calls or []
+        if not tool_calls:
+            return {
+                "initialize": init,
+                "tool_names": [tool["name"] for tool in tools["tools"]],
+                "tool_log": tool_log,
+                "answer": message.content,
+            }
+        for tool_call in tool_calls:
+            arguments = json.loads(tool_call.function.arguments or "{}")
+            result = await client.call_tool(tool_call.function.name, arguments)
+            payload = result.get("structuredContent")
+            if payload is None:
+                payload = {"content": result.get("content", [])}
+            tool_log.append({"name": tool_call.function.name, "arguments": arguments, "result": payload})
+            messages.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": tool_call.id,
+                    "content": json.dumps(payload, ensure_ascii=False),
+                }
+            )
+    return {
+        "initialize": init,
+        "tool_names": [tool["name"] for tool in tools["tools"]],
+        "tool_log": tool_log,
+        "answer": "Model did not finish within the maximum number of tool rounds.",
+    }
+
+
+def main() -> None:
+    query = " ".join(sys.argv[1:]) or "请查询 Hangzhou 当前天气，并用一句话总结。"
+    print(json.dumps(asyncio.run(run(query)), ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/weather_zcp_server.py b/examples/weather_zcp_server.py
