Metadata-Version: 2.4
Name: calculator-mcp-rubens
Version: 0.4.0
Summary: A calculator MCP server
License-Expression: MIT
License-File: LICENSE
Keywords: math,calculator,utility
Author: Rubens Gomes
Author-email: rubens.s.gomes@gmail.com
Requires-Python: >=3.14.0,<4.0.0
Classifier: Programming Language :: Python :: 3
Requires-Dist: calculator-lib-rubens (>=0.2.0)
Requires-Dist: fastmcp (>=4.0.3,<5.0.0)
Requires-Dist: py-key-value-aio[disk] (>=0.4.5,<0.5.0)
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Project-URL: Documentation, https://github.com/rubensgomes/calculator-mcp/README.md
Project-URL: Homepage, https://github.com/rubensgomes/calculator-mcp/
Project-URL: Repository, https://github.com/rubensgomes/calculator-mcp/
Description-Content-Type: text/markdown

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![AI Assisted](https://img.shields.io/badge/AI--Assisted-Development-007ACC?logo=openai&logoColor=white)](./AI_DISCLAIMER.md)

# Calculator MCP Server

calculator-mcp is a small MCP server that exposes 16 arithmetic operations as
callable tools for an LLM. It contains no math of its own — every tool is a thin
synchronous wrapper that logs its arguments and delegates to a shared Calculator
instance from the external calculator-lib-rubens package.

## Features

16 calculator tools available via MCP:

**Two-operand operations**: `add`, `subtract`, `multiply`, `divide`, `power`,
`nth_root`, `modulo`, `floor_divide`

**Single-operand operations**: `sqrt`, `absolute`, `floor`, `ceil`, `log10`,
`ln`, `exp`

**Rounding**: `round_number` (with configurable decimal places)

## Prerequisites

- Python 3.14+
- [Poetry](https://python-poetry.org/) for dependency management
- Docker 23+ with the buildx and compose plugins (optional, for running the
  server in a container)

## AI Disclaimer

This project includes code and documentation created with the assistance of AI
tools. For details on usage, limits, and review practices, please see
the [AI Disclaimer](./AI_DISCLAIMER.md).

## Installation

- Install the project and dependencies locally in virtualenv outside the repo

    ```bash
    poetry install
    ```

## Configuration

The server ships with a default `config.yaml` bundled inside the package. To
override it, set the `CALCULATOR_MCP_CONFIG` environment variable to the
absolute path of your custom configuration file:

```bash
export CALCULATOR_MCP_CONFIG=/path/to/your/config.yaml
```

When `CALCULATOR_MCP_CONFIG` is not set, the bundled default is used
automatically.

The configuration file has three sections:

```yaml
server:
    transport: "http"     # "stdio" or "http"
    host: "0.0.0.0"       # Host for HTTP transport (0.0.0.0 = all interfaces)
    port: 9000            # Port for HTTP transport
    timeout: 10           # Tool execution timeout in seconds

client:
    is_oauth: true                         # Enable OAuth authentication
    url: "https://rubens-calculator-mcp.fastmcp.app/mcp"  # Server URL
    token_dir: "~/.fastmcp"       # OAuth token storage directory
    callback_port: 10000                   # OAuth callback server port
```

The `logging` section controls Python logging via `dictConfig`. The default
configuration logs `calculator_mcp` messages at `DEBUG` level to stderr.

## Running the Server

There are three ways to start the server:

1. **Console script** (installed by Poetry):

    ```bash
    # requires poetry to be installed
    poetry install # only needed once
    poetry run calculator-mcp
    ```

2. **As a Python module:**

    ```bash
    # requires poetry to be installed
    poetry install # only needed once
    eval $(poetry env activate)
    python -m calculator_mcp
    deactivate
    ```

3. **With a custom configuration:**

    ```bash
    # requires poetry to be installed
    poetry install # only needed once
    export CALCULATOR_MCP_CONFIG=/path/to/your/config.yaml
    poetry run calculator-mcp
    ```

## Running the Server with Docker

The server can also run as a container. See [DOCKER.md](./docs/DOCKER.md) for the full
reference.

- **Build the image:**

    ```bash
    # requires Docker to be installed and running
    docker build --build-arg VERSION="$(poetry version -s)" \
        -t "calculator-mcp:$(poetry version -s)" -t calculator-mcp:latest .
    ```

- **Run the container:**

    ```bash
    docker run -d --name calculator-mcp -p 9000:9000 \
        --restart unless-stopped "calculator-mcp:$(poetry version -s)"
    ```

- **Verify it is up:**

    ```bash
    curl http://127.0.0.1:9000/health     # -> OK
    ```

- To stop the running container:

    ```bash
    docker stop calculator-mcp
    docker rm calculator-mcp
    ```

- **With Docker Compose:**

    ```bash
    docker compose up --build -d
    docker compose logs -f calculator-mcp
    docker compose down
    ```

Notes:

- The container listens on `0.0.0.0:9000`, per the bundled `config.yaml`.
- The MCP endpoint is `http://127.0.0.1:9000/mcp`.
- The server runs as a non-root user (`uid=1001`).
- To use a custom configuration, mount it and set `CALCULATOR_MCP_CONFIG`
  to the mounted path.

## Running the Client

A sample integration test client is provided in `tests/integration/client.py`
to demonstrate the MCP protocol with the server. It lists all available tools
and calls each one with sample arguments.

**Important:** The server must be running before you start the client. See
[Running the Server](#running-the-server) above.

- **Run the client:** to hit this MCP server previously deployed at 
<https://rubens-calculator-mcp.fastmcp.app/mcp>

    ```bash
    # requires poetry to be installed
    poetry install # only needed once
    eval $(poetry env activate)
    python tests/integration/client.py
    deactivate
    ```

## Add MCP Server to Claude Code

- Add the MCP server to Claude Code using project scope. The file `.mcp.json` is
  added to the project root folder:

    ```bash
    # It is assumed that the MCP server is running on http://127.0.0.1:9000
    cd $(git rev-parse --show-toplevel) || exit
    claude mcp add \
        --scope project \
        --transport http \
        calculator-mcp http://127.0.0.1:9000/mcp
    ```

## MCP Protocol

For further information about `MCP` refer to [MCP Protocol](./docs/MCP.md).

## Authorship

This project was originally created and is maintained by
[Rubens Gomes](https://rubensgomes.com).

The original public repository is available at:

- <https://github.com/rubensgomes-org/calculator-mcp>

This repository is a derivative copy maintained for experimentation, learning,
and development purposes.

## License

The project is licensed under the [MIT License](./LICENSE).

---
Author:  [Rubens Gomes](https://rubensgomes.com/)

