Metadata-Version: 2.4
Name: bg-mcpcore
Version: 1.1.1
Summary: BAUER GROUP MCP framework — config-driven, pluggable REST-API MCP servers on FastMCP
Project-URL: Homepage, https://github.com/bauer-group/LIB-BG-MCPCore
Project-URL: Source, https://github.com/bauer-group/LIB-BG-MCPCore
Project-URL: Issues, https://github.com/bauer-group/LIB-BG-MCPCore/issues
Project-URL: Changelog, https://github.com/bauer-group/LIB-BG-MCPCore/blob/main/CHANGELOG.md
Author-email: "BAUER GROUP (Karl Bauer)" <karl.bauer@bauer-group.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,fastmcp,framework,mcp,oauth,openapi,rest
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: cryptography<49.0.0,>=43.0.0
Requires-Dist: fastmcp<4.0.0,>=3.0.0
Requires-Dist: httpx<1.0.0,>=0.28.1
Requires-Dist: py-key-value-aio[disk]<1.0.0,>=0.4.4
Requires-Dist: pydantic-settings<3.0.0,>=2.14.1
Requires-Dist: pydantic<3.0.0,>=2.10.0
Requires-Dist: rich<15.0.0,>=13.7.0
Requires-Dist: structlog<26.0.0,>=24.4.0
Requires-Dist: typer<1.0.0,>=0.15.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0.0,>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov<8.0.0,>=6.0.0; extra == 'dev'
Requires-Dist: pytest-httpx<1.0.0,>=0.35.0; extra == 'dev'
Requires-Dist: pytest<10.0.0,>=8.3.0; extra == 'dev'
Requires-Dist: python-semantic-release>=9.0.0; extra == 'dev'
Requires-Dist: respx<1.0.0,>=0.22.0; extra == 'dev'
Requires-Dist: ruff>=0.7.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26.0; extra == 'docs'
Provides-Extra: oauth-providers
Provides-Extra: openapi
Requires-Dist: pyyaml<7.0.0,>=6.0.0; extra == 'openapi'
Provides-Extra: redis
Requires-Dist: py-key-value-aio[redis]<1.0.0,>=0.4.4; extra == 'redis'
Provides-Extra: tasks
Requires-Dist: fastmcp[tasks]<4.0.0,>=3.0.0; extra == 'tasks'
Provides-Extra: testkit
Requires-Dist: pytest-asyncio<2.0.0,>=0.24.0; extra == 'testkit'
Requires-Dist: pytest<10.0.0,>=8.3.0; extra == 'testkit'
Requires-Dist: respx<1.0.0,>=0.22.0; extra == 'testkit'
Description-Content-Type: text/markdown

<!-- AUTO-GENERATED FILE. DO NOT EDIT. Edit docs/README.template.MD instead. -->
<!-- Generated on 2026-06-01 13:26:49 UTC -->

# BAUER GROUP - BG-MCPCore

[![PyPI Version](https://badge.fury.io/py/bg-mcpcore.svg)](https://pypi.org/project/bg-mcpcore/)
[![Python Support](https://img.shields.io/pypi/pyversions/bg-mcpcore.svg)](https://pypi.org/project/bg-mcpcore/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![🧪 Tests](https://github.com/bauer-group/LIB-BG-MCPCore/actions/workflows/tests.yml/badge.svg)](https://github.com/bauer-group/LIB-BG-MCPCore/actions/workflows/tests.yml)

> **BAUER GROUP MCP framework** — config-driven, pluggable REST-API MCP servers on [FastMCP](https://github.com/jlowin/fastmcp).

`bg-mcpcore` is the shared foundation for BAUER GROUP's fleet of
[Model Context Protocol](https://modelcontextprotocol.io) servers that bridge
REST APIs (Zammad, Shlink, and more). It turns "stand up a secure, OAuth-gated
MCP server for an API" from a multi-day clone-and-edit job into a short
declarative profile.

**Repository Information:**

- **Version:** v1.1.0 (2026-06-01)
- **Repository:** [bauer-group/LIB-BG-MCPCore](https://github.com/bauer-group/LIB-BG-MCPCore)
- **Branch:** main
- **Architecture:** Config-driven, pluggable, secure-by-default

## The idea: config for the standard, code for the complex

A server is described by a **declarative JSON profile**. Standard behaviour —
identity, backend connection, inbound/outbound auth, rate limiting,
observability, health/branding routes, and OpenAPI-derived tools — needs **no
Python**. The genuinely complex parts (hand-written tools, per-user
on-behalf-of token flows) drop down to **Python escape hatches** the profile
points at.

```jsonc
// profiles/mautic.json — a whole server, no Python
{
  "id": "mautic",
  "display_name": "BAUER GROUP Mautic",
  "backend": { "base_url": "${env:MAUTIC_URL}", "api_base_path": "/api" },
  "auth": {
    "inbound":  { "mode": "oidc" },
    "outbound": { "type": "bearer_env", "value_from_env": "MAUTIC_TOKEN" }
  },
  "tools": { "source": "openapi", "spec": { "source": "${env:MAUTIC_OPENAPI_URL}" } }
}
```

```python
# src/main.py — the entire entrypoint
from bg_mcpcore import load_profile, make_cli

app = make_cli(load_profile("profiles/mautic.json"))
if __name__ == "__main__":
    app()
```

## Install

Requires **Python 3.12, 3.13, or 3.14**.

### From PyPI

```bash
pip install bg-mcpcore
```

### Directly from GitHub

```bash
# Latest from main
pip install git+https://github.com/bauer-group/LIB-BG-MCPCore.git@main

# A specific released version/tag
pip install git+https://github.com/bauer-group/LIB-BG-MCPCore.git@vv1.1.0

# With extras (any install method)
pip install "bg-mcpcore[openapi] @ git+https://github.com/bauer-group/LIB-BG-MCPCore.git@main"
```

### Optional extras

```bash
pip install "bg-mcpcore[openapi]"                               # + OpenAPI-derived tools
pip install "bg-mcpcore[openapi,redis,tasks,oauth-providers]"   # full Shlink-shaped server
```

| Extra | Adds |
|---|---|
| `openapi` | `tools.source: "openapi"` — generate the tool surface from an OpenAPI spec |
| `redis` | Redis-backed encrypted OAuth-state store (multi-replica deployments) |
| `oauth-providers` | Entra / Google + the spec-driven IdP modes (Auth0, Keycloak, GitHub, AWS Cognito, WorkOS, …) |
| `tasks` | long-running task execution (bulk exports) |
| `testkit` | reusable pytest fixtures + stubs (pytest11 plugin) |

## Architecture

- **Pluggable via Python entry points** — new `auth_providers`, `tool_sources`,
  `auth_resolvers` are pip-installable plugins, never core edits.
- **Central tool registry** — reusable tools (`bg.health`, …) referenced by name
  from any profile (`tools.source: "registry"`).
- **Fail-closed by design** — `AUTH_MODE=none` forbidden in production; the JWT
  signing key mandatory for any active mode; invariants live in core.

See the [documentation](docs/) for the profile schema reference, plugin
authoring guide, and security model.

## License

MIT © BAUER GROUP
