# Simple MCP Server

A deliberately small, production-clean learning project built with Python 3.12 and the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk). It exposes three tools over the recommended Streamable HTTP transport, runs locally or in Docker, and publishes a multi-architecture image plus a GitHub Release after tests pass. A separate LangChain/LangGraph console agent demonstrates guarded use of the Dockerized server.

The current 2.x SDK renamed its high-level `FastMCP` class to `MCPServer`. This project uses that current API rather than the legacy v1 import.

## What this server exposes

| Tool | Inputs | Result |
| --- | --- | --- |
| `hello` | `name: string` | A greeting such as `Hello Rahul!` |
| `get_current_time` | None | ISO 8601 date/time and configured timezone |
| `calculate` | `a`, `b`, and `operation` | Inputs, operation, and numeric result |

Supported calculator operations are `add`, `subtract`, `multiply`, and `divide`. Invalid operations and division by zero become clear MCP tool errors rather than server crashes.

The endpoints are:

- MCP: `http://localhost:8000/mcp`
- Health: `http://localhost:8000/health`
- Swagger UI: `http://localhost:8000/docs`
- OpenAPI document: `http://localhost:8000/openapi.json`

Swagger UI documents HTTP adapters over the same functions used by the MCP
tools. This makes browser-based exploration and conventional HTTP integration
easy without changing the native MCP endpoint:

| HTTP method | Path | Equivalent MCP tool |
| --- | --- | --- |
| `POST` | `/api/tools/hello` | `hello` |
| `GET` | `/api/tools/get-current-time` | `get_current_time` |
| `POST` | `/api/tools/calculate` | `calculate` |

Open `http://localhost:8000/docs` and select **Try it out** to execute an
adapter. Swagger UI assets are loaded from the pinned `swagger-ui-dist` 5.33.0
CDN release; `/openapi.json` and every API operation are served locally.

## How MCP works

MCP (Model Context Protocol) is a standard way for an AI application to discover and call capabilities exposed by another process or service.

```text
User
 |
 v
AI / MCP Client
 |
 | asks what tools are available
 v
MCP Server
 |
 +-- hello()
 |
 +-- get_current_time()
 |
 +-- calculate()
 |
 v
Tool result
 |
 v
AI
 |
 v
User
```

### Core concepts

**MCP client:** The MCP-speaking part of an application or model host. It connects to a server, discovers capabilities, sends calls, and receives results.

**MCP server:** The service in this repository. It advertises capabilities and executes valid requests.

**Tool:** A function the model may choose to call, such as `calculate`.

**Tool schema:** The machine-readable description of a tool's parameters and return shape. The SDK generates it from the Python type hints and docstring.

**Tool call:** A client's request to execute a named tool with specific arguments.

**Tool result:** The text or structured data returned to the client after execution.

### Tool discovery

When a client connects, it asks the server what it can do:

```text
Client
   |
   | Connect
   v
MCP Server
   |
   | Advertise tools
   v
hello
get_current_time
calculate
```

For the user question `What is 25 * 12?`, a model may choose this call:

```text
calculate(a=25, b=12, operation="multiply")
```

The MCP result includes:

```json
{
  "a": 25,
  "b": 12,
  "operation": "multiply",
  "result": 300
}
```

The model can then answer: `25 × 12 = 300`.

## Project structure

```text
simple-mcp-server/
├── .github/
│   └── workflows/
│       └── docker-publish.yml
├── app/
│   ├── __init__.py
│   └── server.py
├── examples/
│   └── langgraph-console-agent/
│       ├── agent_app/
│       ├── tests/
│       ├── .env.example
│       ├── README.md
│       └── requirements.txt
├── tests/
│   ├── integration/
│   │   ├── test_http_server.py
│   │   └── test_mcp_in_process.py
│   └── unit/
│       ├── test_config.py
│       └── test_tools.py
├── .dockerignore
├── .env.example
├── .gitignore
├── Dockerfile
├── LICENSE
├── README.md
├── docker-compose.yml
├── requirements-dev.txt
└── requirements.txt
```

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `TZ` | `Asia/Kolkata` | IANA timezone used by `get_current_time` |
| `MCP_HOST` | `0.0.0.0` | HTTP bind address |
| `MCP_PORT` | `8000` | HTTP listen port |
| `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL` |

Copy the example when using Docker's `--env-file` or Docker Compose:

```bash
cp .env.example .env
```

PowerShell equivalent:

```powershell
Copy-Item .env.example .env
```

The application has safe defaults, so an `.env` file is not required. Python does not automatically load `.env`; export or set variables in the shell if changing them for a non-Docker run.

## Run locally with Python

Python 3.12 is recommended.

Linux or macOS:

```bash
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
pytest
python -m app.server
```

Windows PowerShell:

```powershell
py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
pytest
python -m app.server
```

The logs show startup, host, port, tool calls, and major errors in the console. Stop the server with `Ctrl+C`.

## Connecting an MCP Client

For a local server, connect a Streamable HTTP compatible MCP client to:

```text
http://localhost:8000/mcp
```

A remote deployment behind TLS and a reverse proxy might use:

```text
https://mcp.example.com/mcp
```

The `/mcp` path is the actual default exposed by the official SDK. It is a protocol endpoint, not a normal webpage; opening it directly in a browser may show a method or protocol error.

This minimal Python client discovers and calls the tools:

```python
import asyncio

from mcp import Client


async def main() -> None:
    async with Client("http://localhost:8000/mcp") as client:
        tools = await client.list_tools()
        print([tool.name for tool in tools.tools])

        result = await client.call_tool(
            "calculate",
            {"a": 25, "b": 12, "operation": "multiply"},
        )
        if result.is_error:
            print(result.content)
        else:
            print(result.structured_content)


asyncio.run(main())
```

Expected tool list:

```text
['hello', 'get_current_time', 'calculate']
```

## Tests

Install development dependencies and run:

```bash
pytest
```

Run only fast unit tests:

```bash
pytest tests/unit
```

Run only integration tests:

```bash
pytest -m integration
```

The unit suite covers greeting validation, all calculator operations and errors, timezone behavior, and environment configuration. The integration suite checks generated tool schemas, in-memory MCP discovery and calls, expected MCP error results, the ASGI health route, and a real Streamable HTTP server subprocess on a temporary port. The GitHub workflow runs the complete suite before the image publishing job can start.

The console-agent tests use their own environment because the current LangChain MCP adapter and this MCP 2.x server intentionally have different Python dependency sets. See [the agent example](examples/langgraph-console-agent/README.md) for its no-cost unit-test command.

## LangGraph console agent example

The production-oriented sample in [`examples/langgraph-console-agent`](examples/langgraph-console-agent/README.md) is a standalone console app. It discovers this server's tools from the Docker container over Streamable HTTP and adds an explicit tool allowlist, PII controls, prompt-injection checks, bounded retries, model fallback, execution limits, durable SQLite checkpoints, context summarization, structured logs, and optional human approval.

Quick start:

```bash
docker compose up -d
cd examples/langgraph-console-agent
python -m venv .venv
# Activate .venv, then:
python -m pip install -r requirements-dev.txt
cp .env.example .env
# Add OPENAI_API_KEY to .env
python -m agent_app
```

The server stays in Docker; the agent runs locally in its own Python environment. The example README includes PowerShell commands, configuration, threat-model boundaries, privacy guidance, tests, and production-hardening notes.

## Docker

### Build and run locally

```bash
docker build -t simple-mcp-server .
docker run --rm \
  --name simple-mcp-server \
  -p 8000:8000 \
  --env-file .env \
  simple-mcp-server
```

PowerShell uses backticks for multiline commands, or run the same `docker run` command on one line.

The image uses `python:3.12-slim`, installs runtime dependencies only, and runs as the unprivileged user `appuser`. Python output is unbuffered so logs appear immediately.

Check health:

```bash
curl http://localhost:8000/health
```

Expected response:

```json
{"status":"ok"}
```

Open the interactive API documentation:

```text
http://localhost:8000/docs
```

Follow logs:

```bash
docker logs -f simple-mcp-server
```

### Docker Compose

Docker Compose automatically reads a local `.env` file when present. Without one, the documented defaults are used.

```bash
docker compose up -d
docker compose logs -f
docker compose restart
docker compose down
```

The Compose service maps port `8000`, restarts unless stopped, and builds the local image as `local/simple-mcp-server:latest` unless `DOCKERHUB_USERNAME` is set.

## Pull from Docker Hub

After the workflow publishes the image:

```bash
docker pull <username>/simple-mcp-server:latest
```

Run it:

```bash
docker run -d \
  --name simple-mcp-server \
  --restart unless-stopped \
  -p 8000:8000 \
  -e TZ=Asia/Kolkata \
  <username>/simple-mcp-server:latest
```

Both `linux/amd64` and `linux/arm64` images are published in one multi-architecture manifest.

## Automatic Docker Hub and GitHub Release publishing

The workflow at `.github/workflows/docker-publish.yml` runs for a push or merge to `main`, can be started manually, and also supports tags shaped like `v1.0.0`.

```text
Commit / Merge to main
          ↓
GitHub Action starts
          ↓
Server and agent tests
          ↓
Docker Buildx
          ↓
Docker Hub Login
          ↓
Multi-architecture image push
          ↓
Docker Hub image available
          ↓
GitHub Release with source archive and checksum
```

Every successful `main` build publishes:

```text
<username>/simple-mcp-server:latest
<username>/simple-mcp-server:sha-<short-commit-sha>
```

A tag such as `v1.2.3` additionally publishes semantic tags such as `1.2.3` and `1.2`. The image includes provenance and an SBOM. If either test suite fails, the dependent publish job does not run.

After the image push succeeds, the same job creates a GitHub Release. A `v1.2.3` push uses that release tag; a `main` or manual build uses `build-<short-commit-sha>`. Each release contains a Git source archive and `SHA256SUMS.txt`, and its notes list the exact Docker image tags. Re-running the workflow for the same commit updates the existing build release and replaces its assets, so it does not create duplicates.

### Required GitHub secrets

Create these repository secrets:

- `DOCKERHUB_USERNAME`: your Docker Hub username
- `DOCKERHUB_TOKEN`: a Docker Hub access token, not your account password

In GitHub, go to:

```text
Repository
→ Settings
→ Secrets and variables
→ Actions
→ New repository secret
```

Create a Docker Hub repository named `simple-mcp-server` under the same account. Verify workflow runs at:

```text
GitHub
→ Repository
→ Actions
→ Docker Publish
```

## First deployment checklist

1. Create a GitHub repository.
2. Create the Docker Hub repository `simple-mcp-server`.
3. Create a Docker Hub access token with permission to write to that repository.
4. Add `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` as GitHub Actions repository secrets.
5. Clone the GitHub repository and copy these project files into it, or add the desired Git remote to this repository.
6. Commit the code.
7. Push the `main` branch.
8. Open GitHub Actions and select **Docker Publish**.
9. Confirm both the server and console-agent test jobs pass.
10. Confirm the multi-architecture build and publish job passes.
11. Confirm `latest` and `sha-...` appear in Docker Hub.
12. Confirm a `build-<short-commit-sha>` release appears on the GitHub Releases page with its archive and checksum.
13. Pull with `docker pull USERNAME/simple-mcp-server:latest`.
14. Run the container and confirm `http://localhost:8000/health` returns `{"status":"ok"}`.
15. Connect an MCP client or the sample console agent to `http://localhost:8000/mcp`.

Typical first push commands:

```bash
git add .
git commit -m "Add simple MCP server"
git push origin main
```

## Security notes

This is a learning server and intentionally has no authentication. Do not expose it directly to the public internet in this form.

- For a local-only Docker deployment, publish only on loopback: `-p 127.0.0.1:8000:8000`.
- Put remote deployments behind HTTPS, authentication, request limits, and appropriate network controls.
- The tools do not execute shell commands, access arbitrary files, or return environment variables.
- Inputs are type-checked through MCP schemas, and expected failures are returned as tool errors.
- Logs identify tool calls but do not record secrets.
- `/health` is intentionally public and contains no private data.
- `/docs`, `/openapi.json`, and the REST tool adapters have no authentication,
  just like `/mcp`; protect all of them before an internet-facing deployment.

Authentication and authorization are sensible future additions, but are omitted here so the MCP fundamentals remain easy to study.

## Troubleshooting

**The port is already in use:** Choose another port consistently, for example `MCP_PORT=8001`, and map that port in Docker. With Compose, setting `MCP_PORT=8001` updates both sides of the mapping.

**PowerShell blocks virtual-environment activation:** Run `Set-ExecutionPolicy -Scope Process Bypass`, then retry `.venv\Scripts\Activate.ps1`, or use `.venv\Scripts\python.exe` directly.

**The server is running but `/mcp` looks broken in a browser:** That path expects MCP protocol requests. Test `/health` with `curl` or `Invoke-RestMethod`, then connect with an MCP client.

**Swagger UI is blank but `/openapi.json` works:** The UI loads its pinned
JavaScript and CSS from `cdn.jsdelivr.net`. Allow that host in the browser or
consume the OpenAPI document directly in an API client.

**A tool call fails:** Check `result.is_error` in the client and read the returned content. Check server logs with `docker logs -f simple-mcp-server` or `docker compose logs -f`.

**The container is unhealthy:** Run `docker inspect simple-mcp-server`, check the health log, and verify that `MCP_PORT` is a valid port. Then inspect application logs.

**Docker Hub login fails in GitHub Actions:** Confirm both secret names are exact, the username owns the target repository, and the token has write permission. Use an access token rather than the Docker Hub password.

**The image is not published:** Open the **Docker Publish** workflow. The publish job waits for tests; a failed test or build intentionally prevents a push.

**A remote hostname returns an MCP connection error:** Terminate TLS at a correctly configured reverse proxy, forward requests to the container, and add authentication before exposing the service. Verify the final client URL ends in `/mcp` and does not redirect to a different origin.

## License

MIT