Add mcp-vs-api-calls: sample code for MCP vs API Calls tutorial (#816)

* Tool: Add function to get package info from PyPI

This function retrieves package information from PyPI, including the name, version, and summary.

* MCP vs API Calls Python LLM Apps Materials

Materials attached to the "MCP vs API Calls: Which Should You Use for Python LLM Apps?" tutorial

* Create README.md for MCP vs API Calls tutorial

Add README for MCP vs API Calls tutorial with setup instructions and example usage.

---------

Co-authored-by: stephengruppetta <51741022+stephengruppetta@users.noreply.github.com>

Author: leriomaggio

mcp-vs-api-calls/README.md

@@ -0,0 +1,44 @@
+# MCP vs API Calls: Which Should You Use for Python LLM Apps?
+
+This folder contains the sample code for the Real Python tutorial [MCP vs API Calls: Which Should You Use for Python LLM Apps?](https://realpython.com/mcp-vs-api-calls/).
+
+## Files
+
+- `tool.py`: the PyPI lookup function that both approaches share, written with the standard library only.
+- `client_api.py`: the direct API calls integration, which declares the tool schema by hand.
+- `server.py`: the MCP server, which exposes the tool through the `mcp` SDK.
+- `client.py`: the MCP client, which discovers and calls the tool through the server.
+
+## Setup
+
+Create a virtual environment and install the dependencies:
+
+```console
+$ python -m venv tools-venv
+$ source tools-venv/bin/activate
+(tools-venv) $ python -m pip install anthropic "mcp>=2,<3"
+```
+
+The examples use the Anthropic client, which requires an API key. Create a key in the [Anthropic Console](https://console.anthropic.com/), scope it to a single workspace, and export it:
+
+```console
+(tools-venv) $ export ANTHROPIC_API_KEY="your-api-key-here"
+```
+
+## Running the examples
+
+Run the direct API calls version:
+
+```console
+(tools-venv) $ python client_api.py
+The latest version of the Jinja2 package is 3.1.6.
+```
+
+Run the MCP version:
+
+```console
+(tools-venv) $ python client.py
+The latest version of the Jinja2 package is 3.1.6.
+```
+
+You only run `client.py`. It launches `server.py` as a subprocess and talks to it over standard I/O, so you never start the server yourself.

mcp-vs-api-calls/client.py

@@ -0,0 +1,82 @@
+import asyncio
+import sys
+
+import anthropic
+from anthropic.types import Message, ToolUseBlock
+from mcp import Client, StdioServerParameters
+
+MODEL = "claude-sonnet-5"
+QUESTION = (
+    "What is the latest version of the Jinja2 package? "
+    "Answer in one short plain-text sentence."
+)
+
+
+async def discover_tools(client: Client) -> list[dict]:
+    discovered = await client.list_tools()
+    return [
+        {
+            "name": tool.name,
+            "description": tool.description,
+            "input_schema": tool.input_schema,
+        }
+        for tool in discovered.tools
+    ]
+
+
+def ask_model(
+    client: anthropic.Anthropic,
+    messages: list[dict],
+    tools: list[dict],
+    model: str = MODEL,
+) -> Message:
+    return client.messages.create(
+        model=model,
+        max_tokens=1024,
+        tools=tools,
+        messages=messages,
+    )
+
+
+async def run_tool(client: Client, block: ToolUseBlock) -> str:
+    result = await client.call_tool(block.name, block.input)
+    return result.content[0].text
+
+
+def tool_result(block: ToolUseBlock, output: str) -> dict:
+    return {
+        "role": "user",
+        "content": [
+            {
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": output,
+            },
+        ],
+    }
+
+
+async def main(server: StdioServerParameters) -> None:
+    async with Client(server) as mcp:
+        tools = await discover_tools(mcp)
+
+        client = anthropic.Anthropic()
+        messages = [{"role": "user", "content": QUESTION}]
+        response = ask_model(client, messages, tools)
+        for block in response.content:
+            if block.type == "tool_use":
+                messages.append(
+                    {"role": "assistant", "content": response.content}
+                )
+                output = await run_tool(mcp, block)
+                messages.append(tool_result(block, output))
+        final = ask_model(client, messages, tools)
+        print(final.content[0].text)
+
+
+if __name__ == "__main__":
+    server = StdioServerParameters(
+        command=sys.executable,
+        args=["server.py"],
+    )
+    asyncio.run(main(server))

mcp-vs-api-calls/client_api.py

@@ -0,0 +1,82 @@
+import json
+
+import anthropic
+from anthropic.types import Message, ToolUseBlock
+
+from tool import get_package_info
+
+MODEL = "claude-sonnet-5"
+QUESTION = (
+    "What is the latest version of the Jinja2 package? "
+    "Answer in one short plain-text sentence."
+)
+
+TOOLS = [
+    {
+        "name": "get_package_info",
+        "description": (
+            "Look up a package on PyPI and return its "
+            "latest version and summary."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "package_name": {
+                    "type": "string",
+                    "description": "The package name on PyPI.",
+                },
+            },
+            "required": ["package_name"],
+        },
+    },
+]
+
+
+def ask_model(
+    client: anthropic.Anthropic,
+    messages: list[dict],
+    tools: list[dict],
+    model: str = MODEL,
+) -> Message:
+    return client.messages.create(
+        model=model,
+        max_tokens=1024,
+        tools=tools,
+        messages=messages,
+    )
+
+
+def run_tool(block: ToolUseBlock) -> str:
+    result = get_package_info(**block.input)
+    return json.dumps(result)
+
+
+def tool_result(block: ToolUseBlock, output: str) -> dict:
+    return {
+        "role": "user",
+        "content": [
+            {
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": output,
+            },
+        ],
+    }
+
+
+def main() -> None:
+    client = anthropic.Anthropic()
+    messages = [{"role": "user", "content": QUESTION}]
+    response = ask_model(client, messages, TOOLS)
+    for block in response.content:
+        if block.type == "tool_use":
+            messages.append(
+                {"role": "assistant", "content": response.content},
+            )
+            messages.append(tool_result(block, run_tool(block)))
+    final = ask_model(client, messages, TOOLS)
+    print(final.content[0].text)
+
+
+if __name__ == "__main__":
+    main()

mcp-vs-api-calls/server.py

@@ -0,0 +1,8 @@
+from mcp.server import MCPServer
+from tool import get_package_info
+
+mcp = MCPServer("pypi-tools")
+mcp.add_tool(get_package_info)
+
+if __name__ == "__main__":
+    mcp.run()

mcp-vs-api-calls/tool.py

@@ -0,0 +1,18 @@
+import json
+import urllib.request
+
+
+def get_package_info(package_name: str) -> dict:
+    """
+    Look up a package on PyPI
+    and return its latest version and summary.
+    """
+    url = f"https://pypi.org/pypi/{package_name}/json"
+    with urllib.request.urlopen(url) as response:
+        data = json.load(response)
+    info = data["info"]
+    return {
+        "name": info["name"],
+        "version": info["version"],
+        "summary": info["summary"],
+    }