Metadata-Version: 2.4
Name: bss-mcp
Version: 0.2.1
Summary: MCP server for the Basic Supply Service (BSS) — read-only debug tools
Author-email: Hochfrequenz Unternehmensberatung GmbH <info+pip@hochfrequenz.de>
License: MIT
Keywords: basicsupply,bss,mcp
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
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: bssclient>=0.1
Requires-Dist: fastmcp>=3.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic-settings>=2.7
Requires-Dist: python-dotenv>=1.0
Provides-Extra: coverage
Requires-Dist: coverage>=7; extra == 'coverage'
Provides-Extra: dev
Requires-Dist: pip-tools; extra == 'dev'
Provides-Extra: formatting
Requires-Dist: black>=25; extra == 'formatting'
Requires-Dist: isort>=5; extra == 'formatting'
Provides-Extra: linting
Requires-Dist: pylint>=4; extra == 'linting'
Provides-Extra: packaging
Requires-Dist: build>=1; extra == 'packaging'
Requires-Dist: twine>=6; extra == 'packaging'
Provides-Extra: spell-check
Requires-Dist: codespell>=2; extra == 'spell-check'
Provides-Extra: tests
Requires-Dist: pytest-asyncio>=0.24; extra == 'tests'
Requires-Dist: pytest-mock>=3; extra == 'tests'
Requires-Dist: pytest>=9; extra == 'tests'
Provides-Extra: type-check
Requires-Dist: mypy>=1.10; extra == 'type-check'
Description-Content-Type: text/markdown

# bss-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
![Python Versions (officially) supported](https://img.shields.io/pypi/pyversions/bss-mcp.svg)
![Pypi status badge](https://img.shields.io/pypi/v/bss-mcp)
![Unittests status badge](https://github.com/Hochfrequenz/bss-mcp/workflows/Unittests/badge.svg)
![Coverage status badge](https://github.com/Hochfrequenz/bss-mcp/workflows/Coverage/badge.svg)
![Linting status badge](https://github.com/Hochfrequenz/bss-mcp/workflows/Linting/badge.svg)
![Black status badge](https://github.com/Hochfrequenz/bss-mcp/workflows/Formatting/badge.svg)

An [MCP](https://modelcontextprotocol.io/) server wrapping [`bssclient`](https://github.com/Hochfrequenz/bssclient.py), exposing read-only BSS investigation-order data to AI assistants (e.g. Claude Desktop) for debugging.

Requires **Python 3.11+**.

## Tools

| Tool | Description |
|---|---|
| `get_ermittlungsauftraege` | List investigation orders (`limit`, `offset`; `limit=0` uses the server default) |
| `get_ermittlungsauftraege_by_malo` | Investigation orders for a Marktlokation ID |
| `get_aufgabe_stats` | Task status statistics across all Aufgaben types |
| `get_all_ermittlungsauftraege` | Fetches all investigation orders by iterating pages (`package_size` controls page size, default 100) |

## Installation

```bash
pip install bss-mcp
```

For use with [Claude Desktop](https://claude.ai/download) or another MCP client, `pipx` installs the server as a standalone executable:

```bash
pipx install bss-mcp
```

## Configuration

Set environment variables or place them in a `.env` file in the working directory from which the MCP server is launched (for Claude Desktop this is typically the user's home directory):

| Variable | Required | Description |
|---|---|---|
| `BSS_URL` | Yes | Base URL of the BSS server, e.g. `https://basicsupply.example.de/` |
| `BSS_AUTH_TYPE` | No (default: `basic`) | `basic` or `oauth` |
| `BSS_USER` | If basic auth | Username |
| `BSS_PASSWORD` | If basic auth | Password |
| `BSS_CLIENT_ID` | If OAuth | OAuth client ID |
| `BSS_CLIENT_SECRET` | If OAuth | OAuth client secret |
| `BSS_TOKEN_URL` | If OAuth | Token endpoint URL |

## Usage

Run the server directly:

```bash
bss-mcp
```

Or add to your MCP client config (e.g. Claude Desktop). Use the full path to the executable if `bss-mcp` is not on the PATH seen by the client:

```json
{
  "mcpServers": {
    "bss": {
      "command": "bss-mcp",
      "env": {
        "BSS_URL": "https://basicsupply.example.de/",
        "BSS_AUTH_TYPE": "basic",
        "BSS_USER": "...",
        "BSS_PASSWORD": "..."
      }
    }
  }
}
```

## Development

This project follows the [Hochfrequenz Python template](https://github.com/Hochfrequenz/python_template_repository) — see it for general setup instructions (tox, CI, PyPI publishing).

```bash
tox -e tests       # run tests
tox -e type_check  # mypy --strict
tox -e linting     # pylint
tox -e coverage    # coverage ≥ 80 %
tox -e formatting  # black + isort
```
