Metadata-Version: 2.4
Name: calcing-mcp
Version: 0.1.0
Summary: MCP server exposing calcing engineering calculation apps (DIN/ISO/VDI, FEA) as tools for AI clients like Claude Desktop and Claude Code.
Project-URL: Homepage, https://calcing.de
Project-URL: Documentation, https://github.com/calcing/calcing-mcp#readme
Project-URL: Repository, https://github.com/calcing/calcing-mcp
Project-URL: Issues, https://github.com/calcing/calcing-mcp/issues
Author-email: calcing <hello@calcing.de>
License-Expression: MIT
License-File: LICENSE
Keywords: calcing,claude,din,engineering,fea,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# calcing-mcp

An [MCP](https://modelcontextprotocol.io) server that exposes the
[calcing](https://saas.calcing.de) engineering calculation apps as tools for
external AI clients (Claude Desktop, Claude Code, and other MCP-capable hosts).

Each calcing app becomes two MCP tools:

- `calcing_solve_<app>` — run the calculation,
- `calcing_validate_<app>` — validate inputs without solving.

Plus one discovery tool:

- `calcing_list_apps` — list all available apps with short descriptions.

Under the hood every tool call is a single HTTPS request to the calcing
**Agent API**:

```
POST https://saas.calcing.de/api/elements/<app>/agent/solve
X-Agent-Token: <your token>
Content-Type: application/json

{ "input": { ... app-specific inputs ... } }
```

## Available apps

| Tool                                   | App                                       |
| -------------------------------------- | ----------------------------------------- |
| `calcing_solve_shaft_strength_din`     | Wellenfestigkeit / Shaft strength (DIN 743) |
| `calcing_solve_bearing`                | Waelzlager / Rolling bearing (ISO 281)    |
| `calcing_solve_passungen`              | Passungen / Fits (ISO 286)                |
| `calcing_solve_waelzkontakte`          | Waelzkontakte / Rolling contacts (Hertz)  |
| `calcing_solve_vawt`                   | Vertikalachsen-Windturbine (IEC 61400-2)  |
| `calcing_solve_screw`                  | Schraubenverbindung / Bolted joint (VDI 2230) |
| `calcing_solve_passfeder`              | Passfeder / Parallel key (DIN 6892)       |
| `calcing_solve_hawt`                   | Horizontalachsen-Windturbine (HAWT)       |
| `calcing_solve_pressverband`           | Pressverband / Interference fit (DIN 7190)|
| `calcing_solve_axial_fan`              | Axialventilator / Axial fan               |
| `calcing_solve_bearing_contacts`       | Waelzlager-Kontakte / Bearing contacts    |
| `calcing_solve_bearing_shaft_system`   | Welle-Lager-System / Shaft-bearing system |

Call `calcing_list_apps` at any time for the live list plus descriptions.

## Installation

Requires Python **>= 3.10**.

### From PyPI

Once published, install from PyPI with your tool of choice:

```bash
pip install calcing-mcp        # into the current environment
pipx install calcing-mcp       # isolated global CLI (recommended)
uvx calcing-mcp                # run without installing (uv)
```

### From source with pipx (global CLI)

```bash
pipx install /path/to/clients/calcing-mcp
```

### With pip (editable, for development)

```bash
cd clients/calcing-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
```

Either way you get a `calcing-mcp` console command that runs the server over
**stdio**.

## Create an agent token

1. Sign in at **accounts.calcing.de**.
2. Go to **Billing → Tokens** (`accounts.calcing.de/billing/tokens`).
3. Create a new **agent token**:
   - **Audience (`aud`)**: `saas`
   - **Scopes**: select the apps you want to expose (each solve tool needs the
     matching app scope). Grant only what you need.
4. Copy the token — it is shown only once.

Export it in the environment where the MCP server runs:

```bash
export CALCING_AGENT_TOKEN="cai_agent_...."
```

### Environment variables

| Variable              | Required | Default                        | Purpose                          |
| --------------------- | -------- | ------------------------------ | -------------------------------- |
| `CALCING_AGENT_TOKEN` | yes      | —                              | Agent token (`aud=saas`)         |
| `CALCING_API_BASE`    | no       | `https://saas.calcing.de/api`  | Override the API base URL        |
| `CALCING_TIMEOUT`     | no       | `120`                          | HTTP timeout in seconds          |

## Claude Desktop configuration

Add the server to your `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "calcing": {
      "command": "calcing-mcp",
      "args": [],
      "env": {
        "CALCING_AGENT_TOKEN": "cai_agent_....",
        "CALCING_API_BASE": "https://saas.calcing.de/api"
      }
    }
  }
}
```

If `calcing-mcp` is not on Claude Desktop's `PATH` (e.g. it lives in a venv),
use an absolute path or run it through the interpreter:

```json
{
  "mcpServers": {
    "calcing": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "calcing_mcp.server"],
      "env": { "CALCING_AGENT_TOKEN": "cai_agent_...." }
    }
  }
}
```

Restart Claude Desktop; the `calcing_*` tools then appear in the tools list.

## Claude Code configuration

```bash
claude mcp add calcing --env CALCING_AGENT_TOKEN=cai_agent_.... -- calcing-mcp
```

## Usage

Ask your AI client to call a tool, e.g. *"Use `calcing_list_apps` to see what's
available, then solve a DIN 743 shaft with `calcing_solve_shaft_strength_din`."*

The `input` argument holds the app-specific payload as a JSON object (a JSON
string is also accepted). Use `calcing_validate_<app>` first if you want the app
to check the payload before running the full calculation.

Errors are surfaced explicitly (no silent fallbacks):

- **401** — token missing/expired,
- **403** — token lacks the app scope, or plan/quota does not allow it,
- **422** — the `input` payload failed validation,
- **429** — rate limit / quota exceeded.

## Privacy & quota

Every tool call sends your `input` payload to `saas.calcing.de` and is
authenticated with your agent token. Calls count against your account's plan
**quota** and are attributable to your token. Do not put secrets in `input`,
and revoke the token in the billing panel if it is ever exposed.

## Publishing (maintainers)

The package is built with [hatchling](https://hatch.pypa.io/) and published to
PyPI. **Publishing requires maintainer credentials** — either a configured PyPI
[Trusted Publisher](https://docs.pypi.org/trusted-publishers/) for this
repository, or a PyPI API token. Contributors without those cannot publish.

### Automated (GitHub Actions)

`.github/workflows/publish.yml` runs on every push/PR (CI: install + import on
Python 3.10–3.13, then `python -m build` + `twine check`). On a **GitHub Release**
or a **`v*` tag** push it additionally uploads to PyPI via
`pypa/gh-action-pypi-publish`.

By default it uses **Trusted Publishing** (OIDC, `id-token: write`, no secret
needed once the project is registered as a Trusted Publisher on PyPI). To use a
token instead, set a `PYPI_API_TOKEN` repository secret and switch the publish
step to `with: password: ${{ secrets.PYPI_API_TOKEN }}` (see the comment in the
workflow).

Cutting a release:

```bash
# bump version in pyproject.toml and calcing_mcp/__init__.py, update CHANGELOG.md
git tag v0.1.0 && git push origin v0.1.0
# or create a GitHub Release for the tag — either triggers the publish job.
```

> This workflow lives under `clients/calcing-mcp/` because the MCP package is
> published independently of the monorepo. It is written as if this folder were
> the repository root; when calcing-mcp is split into its own repo, this folder
> becomes the root and the workflow works unchanged.

### Manual (local)

```bash
cd clients/calcing-mcp
python -m pip install --upgrade build twine
python -m build                 # -> dist/*.whl and dist/*.tar.gz
python -m twine check dist/*
python -m twine upload dist/*    # prompts for PyPI credentials / token
```

## License

MIT — see [LICENSE](./LICENSE).
