Merge branch 'main' into feat/oidc-fallback

Author: LucaButBoring

.github/ISSUE_TEMPLATE/config.yaml

@@ -1 +1 @@
-blank_issues_enabled: true
+blank_issues_enabled: false

CONTRIBUTING.md

@@ -14,6 +14,12 @@ Thank you for your interest in contributing to the MCP Python SDK! This document
 uv sync --frozen --all-extras --dev
 ```
 
+6. Set up pre-commit hooks:
+
+```bash
+uv tool install pre-commit --with pre-commit-uv --force-reinstall
+```
+
 ## Development Workflow
 
 1. Choose the correct branch for your changes:
@@ -50,7 +56,13 @@ uv run ruff format .
 uv run scripts/update_readme_snippets.py
 ```
 
-8. Submit a pull request to the same branch you branched from
+8. (Optional) Run pre-commit hooks on all files:
+
+```bash
+pre-commit run --all-files
+```
+
+9. Submit a pull request to the same branch you branched from
 
 ## Code Style
 

README.md

@@ -44,6 +44,7 @@
   - [Advanced Usage](#advanced-usage)
     - [Low-Level Server](#low-level-server)
     - [Writing MCP Clients](#writing-mcp-clients)
+    - [Parsing Tool Results](#parsing-tool-results)
     - [MCP Primitives](#mcp-primitives)
     - [Server Capabilities](#server-capabilities)
   - [Documentation](#documentation)
@@ -1605,6 +1606,75 @@ async def main():
 
 For a complete working example, see [`examples/clients/simple-auth-client/`](examples/clients/simple-auth-client/).
 
+### Parsing Tool Results
+
+When calling tools through MCP, the `CallToolResult` object contains the tool's response in a structured format. Understanding how to parse this result is essential for properly handling tool outputs.
+
+```python
+"""examples/snippets/clients/parsing_tool_results.py"""
+
+import asyncio
+
+from mcp import ClientSession, StdioServerParameters, types
+from mcp.client.stdio import stdio_client
+
+
+async def parse_tool_results():
+    """Demonstrates how to parse different types of content in CallToolResult."""
+    server_params = StdioServerParameters(
+        command="python", args=["path/to/mcp_server.py"]
+    )
+
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            # Example 1: Parsing text content
+            result = await session.call_tool("get_data", {"format": "text"})
+            for content in result.content:
+                if isinstance(content, types.TextContent):
+                    print(f"Text: {content.text}")
+
+            # Example 2: Parsing structured content from JSON tools
+            result = await session.call_tool("get_user", {"id": "123"})
+            if hasattr(result, "structuredContent") and result.structuredContent:
+                # Access structured data directly
+                user_data = result.structuredContent
+                print(f"User: {user_data.get('name')}, Age: {user_data.get('age')}")
+
+            # Example 3: Parsing embedded resources
+            result = await session.call_tool("read_config", {})
+            for content in result.content:
+                if isinstance(content, types.EmbeddedResource):
+                    resource = content.resource
+                    if isinstance(resource, types.TextResourceContents):
+                        print(f"Config from {resource.uri}: {resource.text}")
+                    elif isinstance(resource, types.BlobResourceContents):
+                        print(f"Binary data from {resource.uri}")
+
+            # Example 4: Parsing image content
+            result = await session.call_tool("generate_chart", {"data": [1, 2, 3]})
+            for content in result.content:
+                if isinstance(content, types.ImageContent):
+                    print(f"Image ({content.mimeType}): {len(content.data)} bytes")
+
+            # Example 5: Handling errors
+            result = await session.call_tool("failing_tool", {})
+            if result.isError:
+                print("Tool execution failed!")
+                for content in result.content:
+                    if isinstance(content, types.TextContent):
+                        print(f"Error: {content.text}")
+
+
+async def main():
+    await parse_tool_results()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
 ### MCP Primitives
 
 The MCP protocol defines three core primitives that servers can implement:

examples/snippets/clients/parsing_tool_results.py

@@ -0,0 +1,60 @@
+"""examples/snippets/clients/parsing_tool_results.py"""
+
+import asyncio
+
+from mcp import ClientSession, StdioServerParameters, types
+from mcp.client.stdio import stdio_client
+
+
+async def parse_tool_results():
+    """Demonstrates how to parse different types of content in CallToolResult."""
+    server_params = StdioServerParameters(command="python", args=["path/to/mcp_server.py"])
+
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            # Example 1: Parsing text content
+            result = await session.call_tool("get_data", {"format": "text"})
+            for content in result.content:
+                if isinstance(content, types.TextContent):
+                    print(f"Text: {content.text}")
+
+            # Example 2: Parsing structured content from JSON tools
+            result = await session.call_tool("get_user", {"id": "123"})
+            if hasattr(result, "structuredContent") and result.structuredContent:
+                # Access structured data directly
+                user_data = result.structuredContent
+                print(f"User: {user_data.get('name')}, Age: {user_data.get('age')}")
+
+            # Example 3: Parsing embedded resources
+            result = await session.call_tool("read_config", {})
+            for content in result.content:
+                if isinstance(content, types.EmbeddedResource):
+                    resource = content.resource
+                    if isinstance(resource, types.TextResourceContents):
+                        print(f"Config from {resource.uri}: {resource.text}")
+                    elif isinstance(resource, types.BlobResourceContents):
+                        print(f"Binary data from {resource.uri}")
+
+            # Example 4: Parsing image content
+            result = await session.call_tool("generate_chart", {"data": [1, 2, 3]})
+            for content in result.content:
+                if isinstance(content, types.ImageContent):
+                    print(f"Image ({content.mimeType}): {len(content.data)} bytes")
+
+            # Example 5: Handling errors
+            result = await session.call_tool("failing_tool", {})
+            if result.isError:
+                print("Tool execution failed!")
+                for content in result.content:
+                    if isinstance(content, types.TextContent):
+                        print(f"Error: {content.text}")
+
+
+async def main():
+    await parse_tool_results()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

tests/cli/__init__.py

@@ -0,0 +1,100 @@
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from mcp.cli.cli import _build_uv_command, _get_npx_command, _parse_file_path
+
+
+@pytest.mark.parametrize(
+    "spec, expected_obj",
+    [
+        ("server.py", None),
+        ("foo.py:srv_obj", "srv_obj"),
+    ],
+)
+def test_parse_file_path_accepts_valid_specs(tmp_path, spec, expected_obj):
+    """Should accept valid file specs."""
+    file = tmp_path / spec.split(":")[0]
+    file.write_text("x = 1")
+    path, obj = _parse_file_path(f"{file}:{expected_obj}" if ":" in spec else str(file))
+    assert path == file.resolve()
+    assert obj == expected_obj
+
+
+def test_parse_file_path_missing(tmp_path):
+    """Should system exit if a file is missing."""
+    with pytest.raises(SystemExit):
+        _parse_file_path(str(tmp_path / "missing.py"))
+
+
+def test_parse_file_exit_on_dir(tmp_path):
+    """Should system exit if a directory is passed"""
+    dir_path = tmp_path / "dir"
+    dir_path.mkdir()
+    with pytest.raises(SystemExit):
+        _parse_file_path(str(dir_path))
+
+
+def test_build_uv_command_minimal():
+    """Should emit core command when no extras specified."""
+    cmd = _build_uv_command("foo.py")
+    assert cmd == ["uv", "run", "--with", "mcp", "mcp", "run", "foo.py"]
+
+
+def test_build_uv_command_adds_editable_and_packages():
+    """Should include --with-editable and every --with pkg in correct order."""
+    test_path = Path("/pkg")
+    cmd = _build_uv_command(
+        "foo.py",
+        with_editable=test_path,
+        with_packages=["package1", "package2"],
+    )
+    assert cmd == [
+        "uv",
+        "run",
+        "--with",
+        "mcp",
+        "--with-editable",
+        str(test_path),  # Use str() to match what the function does
+        "--with",
+        "package1",
+        "--with",
+        "package2",
+        "mcp",
+        "run",
+        "foo.py",
+    ]
+
+
+def test_get_npx_unix_like(monkeypatch):
+    """Should return "npx" on unix-like systems."""
+    monkeypatch.setattr(sys, "platform", "linux")
+    assert _get_npx_command() == "npx"
+
+
+def test_get_npx_windows(monkeypatch):
+    """Should return one of the npx candidates on Windows."""
+    candidates = ["npx.cmd", "npx.exe", "npx"]
+
+    def fake_run(cmd, **kw):
+        if cmd[0] in candidates:
+            return subprocess.CompletedProcess(cmd, 0)
+        else:
+            raise subprocess.CalledProcessError(1, cmd[0])
+
+    monkeypatch.setattr(sys, "platform", "win32")
+    monkeypatch.setattr(subprocess, "run", fake_run)
+    assert _get_npx_command() in candidates
+
+
+def test_get_npx_returns_none_when_npx_missing(monkeypatch):
+    """Should give None if every candidate fails."""
+    monkeypatch.setattr(sys, "platform", "win32", raising=False)
+
+    def always_fail(*args, **kwargs):
+        raise subprocess.CalledProcessError(1, args[0])
+
+    monkeypatch.setattr(subprocess, "run", always_fail)
+    assert _get_npx_command() is None