# Hello World MCP FastAPI Endpoint

This project exposes a minimal [Model Context Protocol](https://modelcontextprotocol.io/) server backed by FastAPI. It registers both a resource and a tool that respond with a “Hello World” message so you can validate your MCP client integration end-to-end.

## Setup

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Running the server

```bash
uvicorn app:app --reload --port 8080
```

The readiness probe is available at `http://127.0.0.1:8080/`, the health endpoint at `http://127.0.0.1:8080/healthz`, and the MCP streamable HTTP endpoint is mounted at `http://127.0.0.1:8080/mcp`.

### Trying it from an MCP client

Point your MCP-compatible LLM or SDK at `http://127.0.0.1:8080/mcp`. You should see:

- `resource://hello` returning `"Hello from the Model Context Protocol!"`
- `say_hello` tool returning a greeting.

These serve as a starting point for wiring up richer resources and tools.

## Run with Docker (single command)

```bash
docker compose up --build
```

The server will be reachable on `http://127.0.0.1:8080/` (and `/healthz`) after the build completes.

## MCP (Streamable HTTP)

- Endpoint: `https://<service>/mcp`
- CORS: Exposes `Mcp-Session-Id` header for browser clients (Agent Builder).

### Tools
- `ping() -> "pong"`
- `server_time(fmt?: string) -> string` (UTC)
- `echo(text: string) -> string`

### Quick checks

```bash
# 1) Handshake (should return Mcp-Session-Id)
curl -i https://<service>/mcp

# 2) List tools (replace $SID with header from step 1)
SID=<paste-session-id>
curl -s -H "Content-Type: application/json" -H "Mcp-Session-Id: $SID" \
  -X POST --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://<service>/mcp
```

### Agent Builder
- MCP node URL: `https://<service>/mcp`
- Auth: None
- After connect, tools `ping`, `server_time`, `echo` should be selectable.

## MCP (Streamable HTTP)

Endpoint: `https://<service>/mcp`  (no trailing slash required)

### Tools
- ping() -> "pong"
- server_time(fmt?: string) -> string (UTC)
- echo(text: string) -> string
- date_math(expr: string) -> string (UTC). Examples: "+2h", "-15m", "+1d 30m"

### Verify via curl

```bash
# 1) Handshake — should return Mcp-Session-Id header
curl -i https://<service>/mcp

# 2) Save session id and list tools
SID=$(curl -sI https://<service>/mcp | awk -F': ' '/^Mcp-Session-Id:/ {print $2}' | tr -d '\r')

curl -s -H "Content-Type: application/json" -H "Mcp-Session-Id: $SID" \
  -X POST --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://<service>/mcp | jq .

# 3) Call a tool
curl -s -H "Content-Type: application/json" -H "Mcp-Session-Id: $SID" \
  -X POST --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"date_math","arguments":{"expr":"+2h"}}}' \
  https://<service>/mcp | jq .
```

### Agent Builder
- Node type: MCP
- URL: `https://<service>/mcp`
- Transport: Streamable HTTP
- Auth: None
- Click Connect → tools should list: ping, server_time, echo, date_math