Metadata-Version: 2.4
Name: mcp-testclient
Version: 0.1.0
Summary: pytest-native TestClient for the MCP Python SDK Server class
Project-URL: Homepage, https://github.com/peytongreen-dev/mcp-testclient
Project-URL: Repository, https://github.com/peytongreen-dev/mcp-testclient
Project-URL: Issues, https://github.com/peytongreen-dev/mcp-testclient/issues
License: MIT
License-File: LICENSE
Keywords: ai-agents,llm,mcp,pytest,testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: anyio>=4.0.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: anyio[trio]; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# mcp-testclient

[![CI](https://github.com/peytongreen-dev/mcp-testclient/actions/workflows/ci.yml/badge.svg)](https://github.com/peytongreen-dev/mcp-testclient/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/mcp-testclient.svg)](https://pypi.org/project/mcp-testclient/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)

pytest-native TestClient for the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) `Server` class.

> **Using FastMCP?** You already have [`Client(server)`](https://gofastmcp.com/clients/client) built in. mcp-testclient targets the official `mcp.server.lowlevel.Server` class only.

## Why

The MCP Python SDK ships a `Server` class with no built-in test transport. Testing requires spawning a subprocess or standing up a real HTTP server — until now.

`mcp-testclient` wires your `Server` directly to a `ClientSession` using `anyio` memory streams. No subprocess. No network. No stdio. In-process, in a single pytest function.

```python
from mcp.server.lowlevel import Server
import mcp.types as types
from mcp_testclient import TestClient

server = Server("my-server")

@server.list_tools()
async def list_tools():
    return [types.Tool(name="add", description="Add two numbers",
                       inputSchema={"type": "object", "properties":
                           {"a": {"type": "number"}, "b": {"type": "number"}}})]

@server.call_tool()
async def call_tool(name, arguments):
    return [types.TextContent(type="text", text=str(arguments["a"] + arguments["b"]))]

def test_add():
    with TestClient(server) as client:
        tools = client.list_tools()
        assert tools[0].name == "add"

        result = client.call_tool("add", {"a": 1, "b": 2})
        assert result[0].text == "3"
```

## Install

```bash
pip install mcp-testclient
```

## API

```python
with TestClient(server) as client:
    client.list_tools()                            # → list[types.Tool]
    client.call_tool("name", {"arg": "value"})    # → list[TextContent | ...]
    client.list_resources()                        # → list[types.Resource]
    client.read_resource("resource://uri")         # → list[TextResourceContents | ...]
    client.list_prompts()                          # → list[types.Prompt]
    client.get_prompt("name", {"arg": "value"})   # → GetPromptResult
```

`call_tool` raises `RuntimeError` if the server returns `isError=True`.

## Compatibility

- Python 3.10, 3.11, 3.12
- `mcp >= 1.0.0` (tested on 1.26.0)

## Known Issues

**MCP SDK v1.9.1+: default host changed to `127.0.0.1`**

Docker containers will be unreachable externally. Explicitly set `host='0.0.0.0'` in your FastMCP or server config if deploying in a container.

**MCP SDK v1.9.4+: Streamable HTTP incompatible with Cloud Run**

If you're hitting connection errors on Cloud Run after upgrading, downgrade the SDK or use SSE transport temporarily until a fix ships upstream.

**SSE transport deprecated as of April 1, 2026** (grace period through June 30, 2026)

All SSE-based MCP servers need to migrate to Streamable HTTP by end of June. See the [MCP spec migration guide](https://modelcontextprotocol.io) for details.

## MCP Registry

```
mcp-name: io.github.peytongreen-dev/mcp-testclient
```
