# hello-mcp-python

[![ci](https://github.com/kuldeepcodes/hello-mcp-python/actions/workflows/ci.yml/badge.svg)](https://github.com/kuldeepcodes/hello-mcp-python/actions/workflows/ci.yml)
[![Python 3.14](https://img.shields.io/badge/Python-3.14-3776AB)](https://www.python.org/downloads/)
[![licence: MIT](https://img.shields.io/badge/licence-MIT-green.svg)](LICENSE)

A **hello-world [Model Context Protocol](https://modelcontextprotocol.io) server in Python**, plus
a console chat client that drives its tools with a **small local LLM**.

It is deliberately small, but it is not a toy. It uses the official Python MCP SDK, serves both
transports (stdio and streamable HTTP), is covered by **29 automated tests** including real
protocol round-trips over a real pipe, and handles the things that actually break MCP servers in
practice.

> **New to MCP?** Start with **[GETTING-STARTED.md](GETTING-STARTED.md)** — it builds this entire
> project from an empty directory, one step at a time, explaining every dependency and every file.

## Quick start

**Prerequisites:** Python 3.14 or newer.

```bash
git clone https://github.com/kuldeepcodes/hello-mcp-python.git
cd hello-mcp-python

python -m venv .venv
source .venv/bin/activate        # Windows: .\.venv\Scripts\Activate.ps1

python -m pip install -e ".[dev]"
python -m pytest                 # 29 tests

# Works with no model at all, using deterministic keyword routing
python -m hello_mcp.chat --provider none --ask "hello Kuldeep"
```

For real conversation, install [Ollama](https://ollama.com) and pull a small model:

```bash
ollama pull phi3          # ~2.2 GB, works with the prompt planner
python -m hello_mcp.chat --ask "what is 17.5 plus 24.25?"
```

## Server tools

| Tool | Description |
| --- | --- |
| `say_hello` | Greets someone by name in 10 languages: `en`, `es`, `fr`, `de`, `it`, `pt`, `hi`, `ja`, `zh`, `ar`. |
| `echo` | Returns a message verbatim; useful for connection checks. |
| `get_server_time` | Returns structured `utc`, `local`, `timeZone`, `utcOffset` and `human` fields. |
| `add` | Adds two numbers with decimal formatting, so `0.1 + 0.2` is `0.3`. |

The server also exposes prompts (`friendly_greeting`, `summarize_capabilities`) and resources (`hello://server/info`, plus templated `hello://greetings/{language}`).

## Running the server

```powershell
# stdio, for local MCP clients
.\.venv\Scripts\python.exe -m hello_mcp.server

# streamable HTTP, endpoint /mcp and liveness /healthz
.\.venv\Scripts\python.exe -m hello_mcp.server --http --port 5099
```

In stdio mode, stdout is reserved for JSON-RPC. All logging is deliberately sent to stderr.

## MCP client configuration

VS Code or Claude Desktop-style stdio config. Use **absolute paths** — the client does not run
from your project directory:

```json
{
  "mcpServers": {
    "hello-mcp-python": {
      "command": "/absolute/path/to/hello-mcp-python/.venv/bin/python",
      "args": ["-m", "hello_mcp.server"],
      "cwd": "/absolute/path/to/hello-mcp-python"
    }
  }
}
```

On Windows the interpreter is `...\\.venv\\Scripts\\python.exe`, and backslashes must be escaped
in JSON.

HTTP clients can connect to `http://127.0.0.1:5099/mcp` after starting the server with `--http`.

## Chat strategies

| Strategy | When chosen | How it works |
| --- | --- | --- |
| Native tool calling | The model accepts a probe request with a `tools` array. | The model emits tool calls directly. |
| Prompt planner | The model is reachable but rejects tools, as `phi3` does in Ollama. | The app shows tool names, descriptions, and JSON schemas, asks for one JSON decision, executes it, then asks the model to phrase the result. |
| Offline routing | No model is reachable, or `--provider none` is used. | Deterministic keyword rules support `hello NAME`, `what time is it`, `add 2 and 3`, and `echo ...`. |

The selected strategy and reason are printed at startup.

## Real transcript

```text
  hello-mcp-chat v1.0.0
  a Model Context Protocol client for Python

Connected to hello-mcp-server (4 tools)
Model strategy: prompt planner - Ollama says this model does not support tools

  [tool] add {"a": 17.5, "b": 24.25} -> 41.75
bot> The sum of 17.5 and 24.25 is 41.75.
```

## Tests and linting

```powershell
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m pytest
```

The integration tests spawn the real server over stdio, perform a real MCP handshake, list tools, call tools, list prompts, read resources, and assert stdout contains only JSON-RPC.

## Limitations

- The prompt planner is intentionally conservative and less reliable than native tool calling.
- HTTP transport has no authentication; this is a local teaching project.
- Windows needs the `tzdata` package for IANA time zones such as `Asia/Kolkata`.

## Built with

- `mcp==2.0.0` — official Python MCP SDK. In this version the ergonomic API is `mcp.server.mcpserver.MCPServer`; older examples may call this style `FastMCP`.
- `httpx` — Ollama and OpenAI-compatible HTTP calls.
- `pytest` — unit and integration tests.
- `ruff` — linting and formatting.

## The same project in other languages

This is one of three parallel implementations, same tools, same behaviour, same lessons:

- **[hello-mcp-dotnet](https://github.com/kuldeepcodes/hello-mcp-dotnet)** — C# / .NET 10
- **[hello-mcp-java](https://github.com/kuldeepcodes/hello-mcp-java)** — Java 17 / Spring Boot
- **hello-mcp-python** — Python 3.14+ *(you are here)*

## Licence

MIT — see [LICENSE](LICENSE).