calc-mcp-server 0.1.0__tar.gz

calc_mcp_server-0.1.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  # Python dependencies (managed via uv / uv.lock)
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+
+  # GitHub Actions used in workflows
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

calc_mcp_server-0.1.0/.github/workflows/auto-release.yml

@@ -0,0 +1,90 @@
+name: Auto Release (Dependabot)
+
+on:
+  pull_request:
+    types: [closed]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release, e.g. v0.3.0. Leave empty to bump the patch.'
+        required: false
+        type: string
+
+jobs:
+  tag:
+    # Runs for a manual dispatch, or for a merged Dependabot PR from the uv
+    # (Python dependency) ecosystem — those change the published package.
+    # github-actions bumps do not, so they merge without cutting a release.
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.pull_request.merged == true &&
+      github.event.pull_request.user.login == 'dependabot[bot]' &&
+      startsWith(github.event.pull_request.head.ref, 'dependabot/uv/'))
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.GH_ACTION_APP_ID }}
+          private-key: ${{ secrets.GH_ACTION_APP_PRIVATE_KEY }}
+      - uses: actions/checkout@v7
+        with:
+          ref: main
+          fetch-depth: 0 # need all tags + the merge commit
+          token: ${{ steps.app-token.outputs.token }}
+      - name: Resolve release version
+        id: ver
+        env:
+          REQUESTED: ${{ inputs.version }}
+        run: |
+          if [ -n "$REQUESTED" ]; then
+            if ! printf '%s' "$REQUESTED" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
+              echo "::error::version input '$REQUESTED' must look like v1.2.3"
+              exit 1
+            fi
+            next="$REQUESTED"
+            echo "Releasing requested version: $next"
+          else
+            latest=$(git tag -l 'v*' --sort=-v:refname | head -n1)
+            latest=${latest:-v0.0.0}
+            IFS=. read -r major minor patch <<< "${latest#v}"
+            next="v${major}.${minor}.$((patch + 1))"
+            echo "Releasing next patch: $next (from ${latest})"
+          fi
+          if git rev-parse -q --verify "refs/tags/$next" >/dev/null; then
+            echo "::error::tag $next already exists"
+            exit 1
+          fi
+          echo "next=$next" >> "$GITHUB_OUTPUT"
+
+      # Files the release section under the version being cut, so no published
+      # version can end up without one. Stdlib-only, so no project install.
+      - name: Prepare CHANGELOG
+        env:
+          NEXT: ${{ steps.ver.outputs.next }}
+        run: python3 scripts/changelog_release.py --version "$NEXT"
+
+      - name: Commit, tag and push
+        env:
+          NEXT: ${{ steps.ver.outputs.next }}
+          REASON: ${{ github.event_name == 'workflow_dispatch' && 'manual dispatch' || format('Dependabot PR {0}', github.event.pull_request.number) }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          # The script is a no-op when the section already exists (a human may
+          # have written it in the release PR), and committing nothing would
+          # fail and abort an otherwise valid release.
+          if git diff --quiet -- CHANGELOG.md; then
+            echo "CHANGELOG.md already had a $NEXT section; nothing to commit."
+          else
+            git add CHANGELOG.md
+            git commit -m "docs: changelog for $NEXT ($REASON)"
+            git push origin HEAD:main
+          fi
+
+          # Tag AFTER the commit so the tagged tree contains its own changelog
+          # section; tagging first would ship every release without one.
+          git tag -a "$NEXT" -m "Automated release $NEXT ($REASON)"
+          git push origin "$NEXT"

calc_mcp_server-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,90 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # hatch-vcs needs full history + tags to derive the version
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Verify tag matches built version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          BUILT=$(ls dist/calc_mcp_server-*.tar.gz | sed -E 's|.*/calc_mcp_server-(.*)\.tar\.gz|\1|')
+          echo "tag=$TAG_VERSION built=$BUILT"
+          if [ "$TAG_VERSION" != "$BUILT" ]; then
+            echo "::error::Tag $TAG_VERSION does not match built version $BUILT"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  pypi-publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC for PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: pypi-publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --repo "$GITHUB_REPOSITORY" \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes \
+            dist/*
+
+  mcp-registry:
+    name: Publish to MCP Registry
+    needs: pypi-publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # OIDC proves ownership of the io.github.<owner> namespace
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set server.json version from tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          jq --arg v "$VERSION" '.version = $v | .packages[0].version = $v' \
+            server.json > server.tmp && mv server.tmp server.json
+          cat server.json
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - name: Authenticate to MCP Registry
+        run: ./mcp-publisher login github-oidc
+      - name: Publish to MCP Registry
+        run: ./mcp-publisher publish

calc_mcp_server-0.1.0/.github/workflows/validate.yml

@@ -0,0 +1,89 @@
+name: Validate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ruff:
+    name: Ruff (lint + format)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      # ruff comes from the dev group in the committed uv.lock, so CI lints with
+      # the exact version used locally. `pip install ruff` was unpinned, meaning
+      # a ruff release could fail the build without any change to this repo.
+      # --only-group keeps the project itself out of the env (linting does not
+      # need it installed); --no-sync then stops `uv run` from putting it back,
+      # which would build via hatch-vcs and so need the full git history.
+      - run: uv sync --locked --only-group dev
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync ruff format . --check
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # hatch-vcs derives the version from git history + tags
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      # --locked installs the committed uv.lock exactly and fails if it has
+      # drifted from pyproject.toml, so dependency bumps are actually tested.
+      - run: uv sync --locked
+      # The whole suite runs here: unlike the sibling servers this one contacts
+      # nothing external, so there is no `integration` marker to deselect. That
+      # includes the stdio round trip, which is the check that would have caught
+      # the import break this repo exists to prevent.
+      - run: uv run pytest tests/ -v
+
+  # Advisory only. Deliberately absent from `gate`'s needs so it can never block
+  # a merge — the goal is to surface a forgotten entry while it is still cheap to
+  # add, not to add ceremony to dependency bumps or docs-only PRs.
+  changelog:
+    name: Changelog reminder
+    if: >-
+      github.event_name == 'pull_request' &&
+      github.event.pull_request.user.login != 'dependabot[bot]' &&
+      !contains(github.event.pull_request.labels.*.name, 'no-changelog')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # need the base ref to diff against
+      - name: Warn when src changed without a changelog entry
+        env:
+          BASE: ${{ github.event.pull_request.base.sha }}
+          HEAD: ${{ github.event.pull_request.head.sha }}
+        run: |
+          changed=$(git diff --name-only "$BASE" "$HEAD")
+          if grep -q '^src/' <<< "$changed" && ! grep -qx 'CHANGELOG.md' <<< "$changed"; then
+            echo "::warning::This PR changes src/ but not CHANGELOG.md. Add an entry under '## Unreleased', or label the PR 'no-changelog'."
+          else
+            echo "Changelog check satisfied."
+          fi
+
+  gate:
+    name: gate
+    needs: [ruff, test]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check validation results
+        run: |
+          if [[ "${{ needs.ruff.result }}" == "success" && \
+                "${{ needs.test.result }}" == "success" ]]; then
+            echo "All checks passed"
+            exit 0
+          else
+            echo "One or more checks failed"
+            exit 1
+          fi

calc_mcp_server-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+_version.py
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Environment
+.venv/
+
+# macOS
+.DS_Store
+._*
+
+# IDE
+.vscode/
+.idea/

calc_mcp_server-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

calc_mcp_server-0.1.0/AGENTS.md

@@ -0,0 +1,80 @@
+# Calculator MCP Server
+> MCP server for exact arithmetic, usable by LLMs via the Model Context Protocol. One `calculate` tool over a hand-rolled AST allowlist — no `eval()`, no unbounded dependencies.
+
+> **Editing this guide:** `AGENTS.md` is the single source of truth for project context, read by all AI
+> coding agents and humans. Keep it concise — put detail in `docs/` and link it. When you change code that
+> alters documented behavior, update the matching `docs/` file in the **same PR** (CodeRabbit enforces
+> this — see [docs/README.md](docs/README.md)).
+
+## Quick Reference
+- **Lint**: `ruff check .`
+- **Format**: `ruff format .`
+- **Test**: `pytest tests/ -v`
+- **Run server**: `uvx --from . calc-mcp-server` or `python -m calc_mcp_server.server`
+- **Validate (CI)**: Ruff + pytest (all must pass via the `gate` job)
+- **Release**: run the Auto Release workflow; the version comes from the git tag -- see [RELEASING.md](docs/tech/RELEASING.md)
+
+## Where to Find Things
+| I need to... | Read |
+|--------------|------|
+| Understand the architecture | [ARCHITECTURE.md](docs/tech/ARCHITECTURE.md) |
+| Change the allowlist, a cap, or anything security-relevant | [SAFE-EVALUATION.md](docs/tech/SAFE-EVALUATION.md) |
+| Write code that fits conventions | [CONVENTIONS.md](docs/tech/CONVENTIONS.md) |
+| Know the tech stack | [TECH-STACK.md](docs/tech/TECH-STACK.md) |
+| Write or run tests | [TESTING.md](docs/tech/TESTING.md) |
+| Cut a release, or add a changelog entry | [RELEASING.md](docs/tech/RELEASING.md) |
+| Understand the domain and why this repo exists | [OVERVIEW.md](docs/domain/OVERVIEW.md) |
+
+## Architecture Overview
+MCP presentation layer over a pure, dependency-free evaluator. Purely functional — no classes outside
+the `MCPServer` instance and the exception hierarchy. All code lives in `src/calc_mcp_server/`.
+
+- `server.py` -- MCPServer tool registration (1 tool), stdio entry point, turns `CalculatorError` into an `Error:` line
+- `evaluator.py` -- parses, walks the AST against the allowlist, enforces the caps, renders the result
+- `const.py` -- operator aliases, name/function allowlists, the four caps, float precision
+
+Data flow: MCP tool call -> `server.py:calculate` -> `evaluator.evaluate()` (normalize aliases ->
+`ast.parse` -> allowlist walk) -> `evaluator.format_result()` -> string.
+
+See [Architecture](docs/tech/ARCHITECTURE.md) for module boundaries and data flow detail.
+
+## Tech Stack
+- Python 3.12+, `from __future__ import annotations` in every file
+- `mcp[cli]` (`mcp.server.MCPServer`) for MCP server framework -- v2 line, pinned `>=2,<3`
+- **Exactly one runtime dependency**, upper-bounded. This is the point of the repo -- see Structural Risks
+- `ruff` for linting/formatting, `pytest` + `pytest-asyncio` for testing
+- `uv` for environment management, `hatchling` + `hatch-vcs` build backend
+- GitHub Actions CI (validate on push/PR)
+
+See [Tech Stack](docs/tech/TECH-STACK.md) for full detail.
+
+## Core Conventions
+- Constants centralized in `const.py` -- no inline magic values, and the allowlists are written out rather than derived from `math`'s contents
+- Logger: `_LOGGER = logging.getLogger(__name__)` with `%s` formatting (not f-strings)
+- Import order: `__future__` -> stdlib -> third-party -> local
+- `evaluator.py` raises typed `CalculatorError` subclasses; `server.py` catches them and returns a short `Error:` line -- the tool never raises
+- Never coerce integers to float
+
+See [Conventions](docs/tech/CONVENTIONS.md) for naming tables and full rules.
+
+## Business Domain
+A calculator MCP server for LLM voice agents, replacing the abandoned and broken
+`mcp-server-calculator`. One tool, `calculate`, taking an expression string. Integer results are exact
+at any size; floats render at 12 significant digits. Evaluation is guarded against both code execution
+and resource exhaustion.
+
+See [Domain Overview](docs/domain/OVERVIEW.md) for the tool contract, the supported expression surface,
+and why this repo exists.
+
+## Structural Risks
+- **The server key `calculator` and the tool name `calculate` are load-bearing.** Home Assistant agent prompts route to `calculator__calculate` and an existing HA config entry points at `/servers/calculator/sse`. Renaming either breaks live voice agents -- see [OVERVIEW.md](docs/domain/OVERVIEW.md)
+- **Never let a dependency go unbounded.** An unbounded `mcp>=1.4.1` in the package this replaces is what caused the outage this repo exists to prevent; `uv.lock` must be regenerated in the same commit as any `pyproject.toml` dependency change or `uv sync --locked` fails CI
+- Widening `ALLOWED_FUNCTIONS` widens the attack surface -- any addition needs a cap review, since `factorial` needed one and `pow` needed another
+- The caps in `const.py` are tuned to CPython's 4300-digit int-to-string limit; a runtime that changes that limit makes `MAX_RESULT_DIGITS` arbitrary rather than principled
+- `MathError` wraps the stdlib's own message, whose wording differs between Python versions (3.12 says "math domain error", 3.14 says "expected a nonnegative input") -- tests assert the type, not the text
+- Tool functions are called directly in tests, which relies on `@mcp.tool()` returning the function undecorated. That held across the v1 -> v2 migration; a future SDK returning a wrapper breaks the tests loudly rather than silently
+
+## Detailed Guides
+- [Technical Context](docs/tech/README.md) -- architecture, safe evaluation, tech stack, conventions, testing
+- [Domain Context](docs/domain/README.md) -- tool contract, expression surface, why this exists
+- [Documentation Guide](docs/README.md) -- how to maintain these docs

calc_mcp_server-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+The version of a release is derived from its git tag by `hatch-vcs`; there is no version string in the
+source tree. Add entries under `## Unreleased` as you go — the release workflow moves them under the
+version being cut, so you never rename that heading by hand. See
+[docs/tech/RELEASING.md](docs/tech/RELEASING.md).
+
+## Unreleased
+
+## 0.1.0 - 2026-07-30
+
+- Added: initial release. A single `calculate` tool evaluating arithmetic expressions against a
+  hand-rolled AST allowlist, replacing the abandoned `mcp-server-calculator` (last commit 2025-05-10),
+  whose unbounded `mcp>=1.4.1` made `uvx …@latest` resolve the v2 SDK, crash on the removed
+  `mcp.server.fastmcp`, and take the whole MCP proxy down with it.
+- Added: resource caps the incumbent lacked — expression length, AST nesting depth, exponentiation
+  result size and factorial argument. `9**9**9` hangs the incumbent for over five seconds; here it is
+  rejected before any bignum work, from an estimate on the operands. See
+  [SAFE-EVALUATION.md](docs/tech/SAFE-EVALUATION.md).
+- Added: integer results stay exact at any size. The only actively-maintained alternative (the npm
+  `@cyanheads/calculator-mcp-server`) computes in float64 and returns `121932631112635260` for
+  `123456789 * 987654321` — off by 9, in a tool that exists so the model does not have to approximate.
+- Added: an end-to-end stdio round-trip test that spawns the real entry point and speaks JSON-RPC to it.
+  A unit-tested evaluator behind broken MCP wiring is precisely the failure that motivated this repo.
+- Changed: floats render at 12 significant digits, so `0.1 + 0.2` reads `0.3` rather than
+  `0.30000000000000004`. Whole floats keep their `.0`, so `8 / 2` stays visibly distinct from `4`.
+- Fixed: the CI test step no longer passes `-m "not integration"`. This repo contacts nothing external
+  and so defines no `integration` marker, and the flag disagreed with the `pytest tests/ -v` documented
+  in `AGENTS.md` and `TESTING.md` — the kind of drift that makes CI look like it covers more than it
+  does.
+

calc_mcp_server-0.1.0/CLAUDE.md

@@ -0,0 +1,3 @@
+@AGENTS.md
+
+Only update @AGENTS.md. Never edit @CLAUDE.md

calc_mcp_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefan Lettmayer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

calc_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: calc-mcp-server
+Version: 0.1.0
+Summary: MCP server for exact arithmetic: a single safe calculator tool over an AST allowlist, with no unbounded dependencies.
+Project-URL: Homepage, https://github.com/slettmayer/calc-mcp-server
+Project-URL: Repository, https://github.com/slettmayer/calc-mcp-server
+Project-URL: Issues, https://github.com/slettmayer/calc-mcp-server/issues
+Project-URL: Changelog, https://github.com/slettmayer/calc-mcp-server/blob/main/CHANGELOG.md
+Author: Stefan Lettmayer
+License-Expression: MIT
+License-File: LICENSE
+Keywords: arithmetic,calculator,home-assistant,math,mcp,model-context-protocol,safe-eval
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: mcp[cli]<3,>=2
+Description-Content-Type: text/markdown
+
+# Calculator MCP Server
+
+An MCP server that does arithmetic, exactly — so an LLM does not have to do it mentally.
+
+One tool, `calculate`, evaluating expressions against a hand-rolled AST allowlist. No `eval()`, no
+`sympy`, no unbounded dependencies.
+
+```
+2 + 3 * (4 - 1) / 2 ** 2   ->  4.25
+sqrt(16) + sin(pi/2)       ->  5.0
+123456789 * 987654321      ->  121932631112635269
+```
+
+## Why this exists
+
+The widely-used `mcp-server-calculator` package is abandoned (last commit May 2025) and declares
+`mcp>=1.4.1` with no upper bound. When the MCP Python SDK released v2 and removed
+`mcp.server.fastmcp`, every `uvx …@latest` install of it started crashing on import — which took down
+the entire MCP proxy hosting it, and every other server alongside it.
+
+No maintained Python replacement exists. The one actively-maintained npm calculator computes in
+float64, so `123456789 * 987654321` comes back as `121932631112635260` — off by 9. That is a poor
+trait in a tool whose whole purpose is that the model should not be doing the arithmetic itself.
+
+So this server:
+
+- **bounds its one dependency** (`mcp[cli]>=2,<3`) — the failure above cannot recur here;
+- **keeps integers exact** at any size, never coercing to float;
+- **bounds resource use**, not just code execution — see below.
+
+## Safety
+
+Two problems, and most calculator servers only solve the first.
+
+**Code execution.** Expressions are parsed with `ast.parse` and walked against an explicit allowlist of
+node types. `Attribute` is not on it, so `(1).__class__.__bases__` is rejected. A `Call` is only
+evaluated when its target is a bare name in the function allowlist, so `__import__('os').system(…)` is
+rejected before any argument is even evaluated.
+
+**Resource exhaustion.** An allowlist alone still lets `9**9**9` occupy the process for minutes on
+unbounded bignum exponentiation — the incumbent hangs for over five seconds on it. Four caps close
+that: expression length (500 chars), nesting depth (32), result size (4300 digits, checked on the
+operands *before* exponentiating), and factorial argument (1000).
+
+Full detail in [docs/tech/SAFE-EVALUATION.md](docs/tech/SAFE-EVALUATION.md).
+
+## Install
+
+```bash
+uvx calc-mcp-server
+```
+
+Pin it. Do not add `@latest` — that is how the package this replaces broke.
+
+## Configure
+
+As a stdio MCP server:
+
+```json
+{
+  "mcpServers": {
+    "calculator": {
+      "command": "uvx",
+      "args": ["calc-mcp-server"]
+    }
+  }
+}
+```
+
+## The `calculate` tool
+
+| Argument | Type | Description |
+|---|---|---|
+| `expression` | `str` | The expression to evaluate |
+
+Returns the result as a string, or a line starting with `Error: ` explaining why the expression was
+rejected. The tool never raises, so a bad expression is an answer the agent can read back rather than a
+tool-call failure.
+
+**Operators** — `+` `-` `*` `/` `//` `%` `**`, parentheses, unary `+`/`-`. `^` is accepted as a power
+operator, and `×` `·` `÷` `−` are accepted as their ASCII equivalents (speech-to-text produces them).
+
+**Constants** — `pi`, `e`, `tau`.
+
+**Functions** — `abs` `round` `min` `max` `sqrt` `exp` `log` `log2` `log10` `sin` `cos` `tan` `asin`
+`acos` `atan` `atan2` `degrees` `radians` `hypot` `floor` `ceil` `factorial` `gcd` `lcm`.
+
+**Results** — integer arithmetic returns an exact integer of any size. Floats are rendered at 12
+significant digits, which removes IEEE-754 representation noise (`0.1 + 0.2` reads `0.3`, not
+`0.30000000000000004`) while keeping far more precision than a calculator result is used at. A whole
+float keeps its `.0`, so `8 / 2` reads `4.0` and stays distinct from the exact integer `4`.
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests/ -v
+uv run ruff check .
+uv run ruff format .
+```
+
+See [AGENTS.md](AGENTS.md) for the project guide and [docs/](docs/README.md) for the full
+documentation set.
+
+## License
+
+MIT — see [LICENSE](LICENSE).