# Calculator MCP Server

A minimal [MCP](https://modelcontextprotocol.io) server exposing four tools —
`add`, `subtract`, `multiply`, `divide` — in two versions:

- **`calculator_server.py`** — built with the Python `mcp` SDK (`FastMCP`).
  `@mcp.tool()` derives the JSON schema from type hints/docstrings and
  handles the JSON-RPC protocol for you.
- **`calculator_server_raw.py`** — the same server implemented from scratch
  with only the standard library (`json` + `sys`), no `mcp` dependency. It
  hand-rolls the JSON-RPC 2.0 message handling to show what FastMCP is doing
  underneath: read a newline-delimited JSON request from stdin, dispatch on
  `method` (`initialize`, `tools/list`, `tools/call`, `ping`), write a
  JSON-RPC response to stdout. See the file's top-of-file docstring for the
  framing details (no LSP-style headers, just one JSON object per line).

## Setup

```powershell
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
```

## Run it directly (stdio)

MCP servers talk over stdio (or HTTP), not a normal CLI — you don't "run and
see output," a client connects to it. Two ways to try it:

**1. MCP Inspector (visual, interactive)** — requires Node.js/npx:

```powershell
.venv\Scripts\mcp dev calculator_server.py
```

Opens a browser UI where you can call `add`, `multiply`, etc. by hand.

If the page loads but says "Connect to an MCP server to start inspecting" and
there's no Tools tab, the sidebar didn't pick up the command automatically
(can happen if a stale/previous session config is cached). Fill in the
sidebar manually and click **Connect**:

- **Transport Type**: `STDIO`
- **Command**: `C:\Users\simon\mcpserversample\.venv\Scripts\python.exe`
- **Arguments**: `C:\Users\simon\mcpserversample\calculator_server.py`

Once connected, a **Tools** tab appears in the top nav where you can click
"List Tools" and run each one.

**2. `test_client.py`** — a scripted client included in this repo that
connects, lists tools, and calls each one. Defaults to `calculator_server.py`,
or pass a path to test the other version:

```powershell
.venv\Scripts\python test_client.py
.venv\Scripts\python test_client.py calculator_server_raw.py
```

## Wiring it into Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "calculator": {
      "command": "C:\\Users\\simon\\mcpserversample\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\simon\\mcpserversample\\calculator_server.py"]
    }
  }
}
```

## How it works

- `calculator_server.py` creates a `FastMCP` server and registers each Python
  function as a tool via the `@mcp.tool()` decorator. The function's type
  hints and docstring become the tool's JSON schema and description, which is
  what the calling client (Claude, the Inspector, or `test_client.py`) sees.
- `mcp.run()` starts the server listening on stdin/stdout using the MCP
  stdio transport — the standard way a client launches and talks to a local
  MCP server as a subprocess.
- A client connects, calls `list_tools()` to discover what's available, then
  `call_tool(name, args)` to invoke one and get the result back.