# simple-testing-mcp

Minimal [FastMCP](https://gofastmcp.com/) server managed with `uv`.

## Requirements

- Python 3.12+
- [`uv`](https://docs.astral.sh/uv/)
- Docker (optional)

## Run locally (uv)

```bash
uv sync
uv run python app.py
```

The app uses MCP Streamable HTTP and listens on `0.0.0.0:8080` by default. Its
MCP endpoint is `/mcp`.

## Tools

- `hello`: returns a greeting.
- `add`: adds two numbers.
- `think`: waits for the requested non-negative number of seconds.
- `thinkSync`: waits synchronously and does not advertise MCP task support.
- `thinkWithProgress`: waits while reporting percentage completion.

`think` and `thinkWithProgress` support the preview
MCP tasks capability from protocol `2025-11-25`. Capable clients can start
either tool as a background task, poll its status, and retrieve its final result
with `io.modelcontextprotocol/related-task` metadata. Calls without task
augmentation continue to run synchronously. `thinkSync` provides an explicitly
non-task-capable baseline for testing task proxies and synchronous timeout paths.

The default `memory://` task backend is intended for this single-process sample.
For persistent or horizontally scaled deployments, set
`FASTMCP_DOCKET_URL=redis://<host>:6379/0` and configure every server and worker
to use the same backend.

### Direct task client

```python
import asyncio

from fastmcp import Client


async def main() -> None:
    async with Client("http://127.0.0.1:8080/mcp") as client:
        task = await client.call_tool(
            "thinkWithProgress",
            {"seconds": 120},
            task=True,
        )
        print(f"Started task {task.task_id}")
        print(await task.result())


asyncio.run(main())
```

### Microsoft Foundry

Foundry long-running operations are a preview feature. Use a supported model,
call the Responses API with `background=True`, and poll the response until it
reaches a terminal state. Foundry recognizes the task reference returned by the
MCP server and polls the MCP task instead of keeping one tool request open for
the full wait duration.

```python
import time

response = openai.responses.create(
    input="Use thinkWithProgress to wait for 120 seconds.",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
    background=True,
)

while response.status in {"queued", "in_progress"}:
    time.sleep(2)
    response = openai.responses.retrieve(response.id)

print(response.output_text)
```

Health check:

```bash
curl -sS http://127.0.0.1:8080/health
```

## Docker

Build image:

```bash
docker build -t simple-testing-mcp .
```

Run container:

```bash
docker run --rm -p 8080:8080 simple-testing-mcp
```

Pushes to `main` publish multi-architecture images to
`ghcr.io/<owner>/<repository>` with `latest`, `main`, and commit SHA tags. The
workflow can also be run manually from the Actions tab.

Health check:

```bash
curl -sS http://127.0.0.1:8080/health
```