bg-mcpcore 1.0.0__tar.gz

bg_mcpcore-1.0.0/.gitignore

@@ -0,0 +1,65 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+downloads/
+eggs/
+.eggs/
+sdist/
+wheels/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Type checkers / linters
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+
+# mkdocs
+/site
+
+# uv — a library is consumed across environments, so we don't pin a lockfile
+# (the project is pip-native; uv is only a local convenience). Matches the
+# NocoDB_SimpleClient blueprint.
+uv.lock
+
+# PyPI
+.pypirc
+
+# Tools
+.benchmarks/
+
+# IDE
+.vscode/
+.claude/
+.idea/

bg_mcpcore-1.0.0/CHANGELOG.md

@@ -0,0 +1,3 @@
+# CHANGELOG
+
+<!-- This file is managed by python-semantic-release. Do not hand-edit below this line. -->

bg_mcpcore-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BAUER GROUP
+
+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.

bg_mcpcore-1.0.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: bg-mcpcore
+Version: 1.0.0
+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 <info@bauer-group.com>, 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.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.14
+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 12:53:32 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:** 0.0.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
+
+```bash
+pip install bg-mcpcore                                          # lean core
+pip install "bg-mcpcore[openapi]"                               # + OpenAPI 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 inbound IdP modes |
+| `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

bg_mcpcore-1.0.0/README.MD

@@ -0,0 +1,88 @@
+<!-- AUTO-GENERATED FILE. DO NOT EDIT. Edit docs/README.template.MD instead. -->
+<!-- Generated on 2026-06-01 12:53:32 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:** 0.0.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
+
+```bash
+pip install bg-mcpcore                                          # lean core
+pip install "bg-mcpcore[openapi]"                               # + OpenAPI 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 inbound IdP modes |
+| `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

bg_mcpcore-1.0.0/docs/README.template.MD

@@ -0,0 +1,85 @@
+# {{COMPANY_NAME}} - 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:** {{VERSION}} ({{DATE}})
+- **Repository:** [{{REPO_FULL_NAME}}]({{REPO_URL}})
+- **Branch:** {{CURRENT_BRANCH}}
+- **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
+
+```bash
+pip install bg-mcpcore                                          # lean core
+pip install "bg-mcpcore[openapi]"                               # + OpenAPI 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 inbound IdP modes |
+| `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

bg_mcpcore-1.0.0/docs/SECURITY.template.MD

@@ -0,0 +1,92 @@
+# Security Policy
+
+## 🚨 Reporting Security Vulnerabilities
+
+We take the security of bg-mcpcore seriously. As the shared foundation for
+BAUER GROUP's REST-API MCP servers, a vulnerability here can affect every
+downstream server (bg-zammad-mcp, bg-shlink-mcp, …). Please report responsibly.
+
+### 🎯 Preferred Reporting Method
+
+Report via **GitHub Security Advisories** — a secure, private channel:
+
+1. 🔗 Go to the [Security tab](../../security) of this repository
+2. 🖱️ Click "Report a vulnerability"
+3. 📝 Fill out the advisory form with detailed information
+
+### 📧 Alternative
+
+- **📬 Email**: security@bauer-group.com
+- **🐛 Issues**: for non-sensitive matters only (use your discretion)
+
+### 📋 What to Include
+
+1. **📄 Description** of the vulnerability
+2. **💥 Impact** and severity assessment
+3. **🔄 Reproduction** steps
+4. **🖥️ Environment**: affected versions / configuration
+5. **🧪 Proof of Concept** (minimal example, if applicable)
+6. **🔧 Suggested Fix** (if you have one)
+
+### ⏱️ Response Timeline
+
+- **⚡ Initial Response**: within 48 hours
+- **📊 Status Updates**: weekly during investigation
+- **🎯 Resolution**: Critical 1-7d · High 1-14d · Medium 1-30d · Low 1-90d
+
+## 🔐 Supported Versions
+
+{{SUPPORTED_VERSIONS_TABLE}}
+
+We provide security updates for supported versions only.
+
+## 🛡️ Security Model (framework-specific)
+
+bg-mcpcore enforces several invariants that downstream servers inherit and
+cannot relax:
+
+- **Fail-closed auth**: `AUTH_MODE=none` is forbidden in production, and a JWT
+  signing key is mandatory for any active auth mode (`BaseMcpSettings`).
+- **Closed-set auth modes**: an unknown `AUTH_MODE` raises at boot rather than
+  silently serving an unauthenticated endpoint.
+- **Secrets never in profiles**: declarative profiles reference secrets only via
+  `value_from_env` / `${env:VAR}`; a missing variable fails closed at boot.
+- **Encrypted OAuth state at rest**: DCR/token state is Fernet-encrypted; the
+  storage key should be a dedicated `AUTH_STORAGE_ENCRYPTION_KEY` distinct from
+  the JWT signing key (a boot warning fires when they are reused).
+- **PII/secret log redaction**: a structured-logging processor masks values
+  under sensitive-looking keys; servers extend the fragment list additively.
+- **Outbound-auth fail-closed**: per-call (on-behalf-of) resolvers must raise
+  when no credential is available rather than inheriting a static default.
+
+### 🤖 Automated Scanning
+
+CI runs gitleaks/GitGuardian secret scanning and ruff; dependencies are tracked
+via Dependabot. Contributors should run `ruff`, `mypy --strict`, and `pytest`
+locally before opening a PR.
+
+## 📚 Best Practices for Operators
+
+1. **🔄 Keep updated** — pin a compatible range (`bg-mcpcore>=X,<X+1`) and let
+   Dependabot propose bumps.
+2. **🗝️ Secrets** — store credentials in a secret manager / env vars; never in
+   profiles or code. Use a dedicated `AUTH_STORAGE_ENCRYPTION_KEY`.
+3. **🌐 TLS** — keep `verify_tls` enabled against production upstreams.
+4. **🔒 Least privilege** — scope upstream API keys as narrowly as the workflow
+   allows; expose only the tools you need.
+
+## 📞 Contact
+
+- **🛡️ Security Team**: via GitHub Security Advisories
+- **📧 Primary**: security@bauer-group.com
+
+---
+
+**Current Version**: {{CURRENT_VERSION}}
+**Last Updated**: {{LAST_UPDATED}}
+**Next Review**: {{NEXT_REVIEW}}
+**Policy Version**: {{POLICY_VERSION}}
+
+---
+
+*🤝 Security is everyone's responsibility.*

bg_mcpcore-1.0.0/docs/index.md

@@ -0,0 +1,36 @@
+# bg-mcpcore
+
+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. A server is described by a **declarative JSON profile**; the genuinely
+complex parts drop down to **Python escape hatches**.
+
+## Why
+
+The first two MCP servers (Zammad, Shlink) duplicated security-sensitive
+infrastructure — encrypted OAuth-state storage, PII log redaction, rate
+limiting, the OAuth-gated bootstrap — as drifting copies. bg-mcpcore gives that
+code one audited, tested home, and turns a new REST-API MCP server into a
+~15-line profile plus a 4-line entrypoint.
+
+## Three complexity tiers
+
+| Tier | When | Effort |
+|---|---|---|
+| **1 — pure config** | backend ships a usable OpenAPI spec, standard auth | profile JSON only, no Python |
+| **2 — config + a little Python** | OpenAPI base + a few hand tools, or a custom resolver | profile + a `type: python` reference |
+| **3 — mostly Python** | no usable spec (e.g. Zammad) | `tools.source: python`; the profile still drives auth, rate-limit, identity, routes |
+
+## Design pillars
+
+- **Modular** — new auth modes / tool sources / resolvers are pip-installable
+  plugins registered via Python entry points, never core edits.
+- **Configurable** — every standard behaviour is an overridable profile default.
+- **Stable** — the mandatory core depends only on fastmcp/pydantic/httpx/
+  structlog/cryptography; volatile concerns live in optional extras.
+- **Secure** — fail-closed auth invariants are enforced in core and a profile
+  cannot switch them off.
+
+Start with the [Quickstart](quickstart.md).

bg_mcpcore-1.0.0/docs/plugins.md

@@ -0,0 +1,94 @@
+# Writing plugins
+
+bg-mcpcore is extended through Python **entry points** — a new capability is a
+pip-installable package, never a core edit. Three groups:
+
+| Group | Adds | Built-ins |
+|---|---|---|
+| `bg_mcpcore.tool_sources` | a `tools.source` value | `python`, `registry`, `openapi` |
+| `bg_mcpcore.auth_providers` | an inbound `AUTH_MODE` | `none`, `oidc` (core); `entra-single`, `entra-multi`, `google`, `auth0`, `aws-cognito`, `clerk`, `descope`, `discord`, `github`, `keycloak`, `oci`, `propelauth`, `scalekit`, `supabase`, `workos` (`[oauth-providers]`) |
+| `bg_mcpcore.auth_middleware` | post-auth gate per mode | `entra-multi` (tenant allowlist) |
+| `bg_mcpcore.auth_resolvers` | an outbound `auth.type` | `none`, `static_header`, `bearer_env`, `python` |
+| `bg_mcpcore.tools` | a named tool for `tools.source: registry` | `bg.ping`, `bg.health` |
+
+## Inbound auth providers (full FastMCP parity)
+
+`AUTH_MODE=oidc` covers any standard-OIDC IdP via discovery (Keycloak, Auth0,
+Okta, Authentik, Zitadel, Cognito, …). The dedicated modes above add first-class
+support for FastMCP's provider catalogue. `entra-*`/`google` read their config
+from settings (env); the spec-driven modes read it from the profile's
+`auth.inbound.config`, with **secrets referenced by a `<key>_env` entry** naming
+an env var (never inlined):
+
+```jsonc
+"auth": {
+  "inbound": {
+    "mode": "keycloak",                              // = AUTH_MODE
+    "config": { "realm_url": "${env:KEYCLOAK_REALM_URL}" }
+  }
+}
+// AUTH_MODE=auth0:  config: { config_url, client_id, audience, client_secret_env: "AUTH0_SECRET" }
+// AUTH_MODE=github: config: { client_id, client_secret_env: "GH_SECRET" }
+```
+
+A non-standard / proprietary IdP (e.g. Zammad-as-OAuth2, opaque tokens) is a
+custom provider registered the same way — see below.
+
+## A new tool source
+
+```python
+# my_pkg/graphql.py
+class GraphQLToolProvider:
+    def __init__(self, cfg): self._cfg = cfg
+    async def register(self, mcp, ctx) -> int:
+        # add tools to `mcp`; use `ctx.client` / `ctx.request(...)` for upstream calls
+        ...
+        return count
+
+def create_provider(cfg):   # cfg is the profile's ToolsConfig
+    return GraphQLToolProvider(cfg)
+```
+
+```toml
+# my_pkg/pyproject.toml
+[project.entry-points."bg_mcpcore.tool_sources"]
+graphql = "my_pkg.graphql:create_provider"
+```
+
+A provider implements **`ToolProvider`** (`async register(mcp, ctx) -> int`) to
+add tools to an existing instance, or **`ConstructingToolProvider`**
+(`async construct(*, name, instructions, auth, lifespan, icon_url, website_url, ctx) -> FastMCP`)
+to build the instance itself (as the OpenAPI source does via `from_openapi`).
+
+## A new auth provider / resolver
+
+```python
+def build_my_idp(settings): ...        # -> a FastMCP auth provider (or None)
+def build_my_resolver(cfg): ...        # -> an AuthHeaderSource
+```
+
+```toml
+[project.entry-points."bg_mcpcore.auth_providers"]
+my-idp = "my_pkg.auth:build_my_idp"
+
+[project.entry-points."bg_mcpcore.auth_resolvers"]
+sigv4 = "my_pkg.auth:build_my_resolver"
+```
+
+## A reusable registry tool
+
+```python
+def register(mcp, ctx) -> None:
+    @mcp.tool
+    async def my_tool() -> str: ...
+```
+
+```toml
+[project.entry-points."bg_mcpcore.tools"]
+"acme.search" = "my_pkg.tools:register"
+```
+
+!!! warning "Least privilege"
+    The OpenAPI/registry sources receive a capability-scoped `ToolContext`
+    (a `client` + logger), not the full secret-bearing settings. Only the
+    `python` escape hatch (the server's own trusted code) receives `settings`.