rh-fastmcp-server-commons 0.3.1__tar.gz

rh_fastmcp_server_commons-0.3.1/LICENSE

@@ -0,0 +1,204 @@
+Copyright 2026 Red Hat, Inc.
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

rh_fastmcp_server_commons-0.3.1/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: rh-fastmcp-server-commons
+Version: 0.3.1
+Summary: Shared FastMCP scaffolding for Red Hat MCP servers.
+License: Apache-2.0
+License-File: LICENSE
+Author: Red Hat Lightforge MCP
+Author-email: lightforge-mcp-eng@redhat.com
+Maintainer: Red Hat Lightforge MCP
+Maintainer-email: lightforge-mcp-eng@redhat.com
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: certifi (>=2024.0.0)
+Requires-Dist: fastmcp (>=3.4.4,<4.0.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc (>=1.20.0,<2.0.0)
+Requires-Dist: opentelemetry-sdk (>=1.20.0,<2.0.0)
+Requires-Dist: pydantic (>=2.0,<3.0)
+Description-Content-Type: text/markdown
+
+# rh-fastmcp-server-commons
+
+Shared FastMCP scaffolding for Red Hat MCP servers: MCP Authorization spec compliant setup, correct scopes step-up handling and per-tool scopes restriction, tool pipeline, GraphQL operations, HTTP/TLS helpers, search client, and observability setup.
+
+Developed by **Red Hat** as part of the **Lightforge** MCP initiative.
+
+Source will be open-sourced later. The package is public on PyPI now, the VCS is not public yet.
+
+## Install
+
+```bash
+pip install rh-fastmcp-server-commons
+```
+
+```python
+import rh_fastmcp_server_commons
+from rh_fastmcp_server_commons.auth import build_auth_provider, build_http_app
+```
+
+## Documentation
+
+Library usage docs ship with the installed package under `rh_fastmcp_server_commons/docs/`:
+
+- `configuration.md`
+- `authentication.md`
+- `graphql.md`
+- `http-client.md`
+- `observability.md`
+- `search.md`
+
+## License
+
+Apache-2.0. See the `LICENSE` file included in the distribution.
+

rh_fastmcp_server_commons-0.3.1/README.pypi.md

@@ -0,0 +1,33 @@
+# rh-fastmcp-server-commons
+
+Shared FastMCP scaffolding for Red Hat MCP servers: MCP Authorization spec compliant setup, correct scopes step-up handling and per-tool scopes restriction, tool pipeline, GraphQL operations, HTTP/TLS helpers, search client, and observability setup.
+
+Developed by **Red Hat** as part of the **Lightforge** MCP initiative.
+
+Source will be open-sourced later. The package is public on PyPI now, the VCS is not public yet.
+
+## Install
+
+```bash
+pip install rh-fastmcp-server-commons
+```
+
+```python
+import rh_fastmcp_server_commons
+from rh_fastmcp_server_commons.auth import build_auth_provider, build_http_app
+```
+
+## Documentation
+
+Library usage docs ship with the installed package under `rh_fastmcp_server_commons/docs/`:
+
+- `configuration.md`
+- `authentication.md`
+- `graphql.md`
+- `http-client.md`
+- `observability.md`
+- `search.md`
+
+## License
+
+Apache-2.0. See the `LICENSE` file included in the distribution.

rh_fastmcp_server_commons-0.3.1/docs/__init__.py

@@ -0,0 +1 @@
+"""Packaging marker so Poetry can ship this tree as ``rh_fastmcp_server_commons.docs``."""

rh_fastmcp_server_commons-0.3.1/docs/authentication.md

@@ -0,0 +1,190 @@
+# Authentication and authorization
+
+Wire two layers together:
+
+1. **`build_auth_provider()`** - OAuth/JWT validation and FastMCP's global gate (`RequireAuthMiddleware`)
+2. **`build_http_app(mcp)`** - `ScopeEnforcementMiddleware` for RFC 6750 `scope=` on 401/403 and optional per-tool scope step-up
+
+## Wire an authenticated MCP server
+
+```python
+from fastmcp import FastMCP
+from rh_fastmcp_server_commons.auth import (
+    build_auth_provider,
+    build_http_app,
+    require_tool_scopes,
+)
+
+mcp = FastMCP("my-server", auth=build_auth_provider())
+
+@mcp.tool
+@require_tool_scopes("api.security")  # optional; under @mcp.tool
+async def search_advisories(...):
+    ...
+
+@mcp.tool
+@require_tool_scopes("api.security", "api.write")  # AND: need both
+async def update_advisory(...):
+    ...
+
+@mcp.tool
+async def list_products(...):  # global AUTH_REQUIRED_SCOPES only
+    ...
+
+app = build_http_app(mcp)  # not mcp.http_app() / bare mcp.run()
+```
+
+Register all tools before `build_http_app`. Decorator order: `@require_tool_scopes` under `@mcp.tool` (reverse raises `TypeError`).
+
+### Request middleware order
+
+```text
+RequestContextMiddleware
+  -> AuthenticationMiddleware      # JWT -> scope["user"]
+    -> AuthContextMiddleware
+      -> ScopeEnforcementMiddleware  # ours: scope= on 401/403, per-tool 403 step-up
+        -> RequireAuthMiddleware     # FastMCP: global AUTH_REQUIRED_SCOPES
+          -> MCP JSON-RPC handler
+```
+
+`ScopeEnforcementMiddleware` does not re-check global scopes; it advertises the same `mcp.auth.required_scopes` list that `RequireAuthMiddleware` enforces.
+
+### `build_http_app` API
+
+```python
+def build_http_app(
+    mcp: FastMCP,
+    *,
+    middleware: list[Middleware] | None = None,
+    tool_scopes: dict[str, list[str]] | None = None,
+    **kwargs: Any,
+) -> StarletteWithLifespan: ...
+```
+
+| Argument | Meaning |
+|----------|---------|
+| `mcp` | Tools must already be registered |
+| `middleware` | Extra middleware after scope enforcement; must not include `ScopeEnforcementMiddleware` |
+| `tool_scopes` | Merge/override of per-tool scopes (explicit wins). Keys must be registered tool names |
+| `**kwargs` | Passed to `mcp.http_app()` (`path=`, `json_response=`, …) |
+
+No `global_scopes=` kwarg (use `AUTH_REQUIRED_SCOPES`). Prepends `ScopeEnforcementMiddleware` when global and/or per-tool scopes exist; otherwise installs nothing.
+
+For a fully custom stack without `build_http_app`, use `build_scope_enforcement_middleware(mcp)` + `mcp.http_app(middleware=[scope_mw, ...])`.
+
+`FastMCP.http_app` / `mcp.run()` raise if scope middleware is required but missing (`required_scopes` and/or `@require_tool_scopes`), or if per-tool scopes are set without `mcp.auth`. Also rejected: empty `@require_tool_scopes()` / empty meta scopes, meta vs decorator conflict, unknown `tool_scopes=` keys, wrong decorator order, duplicate scope middleware in `build_http_app(..., middleware=...)`.
+
+## Authenticate callers (OAuth / JWT)
+
+`build_auth_provider()` enables:
+
+1. **Protected Resource Metadata (RFC 9728)** at `/.well-known/oauth-protected-resource/mcp` when the MCP path is `/mcp` (`resource` from `AUTH_RESOURCE` / `MCP_BASE_URL`, `authorization_servers` from `AUTH_SERVER`, `scopes_supported` from `AUTH_REQUIRED_SCOPES`, `bearer_methods_supported: ["header"]`). `AUTH_AUDIENCE` and `AUTH_ISSUER` are JWT checks only; they do not appear in PRM.
+2. **JWT validation**: signature (JWKS), `exp`, optional `iss` / `aud`
+
+### Environment variables
+
+Full catalog and bootstrap order: [configuration](configuration.md). Auth-critical vars:
+
+| Variable | Role |
+|----------|------|
+| `AUTH_SERVER` | Required. MCP Auth IdP/SSO URL (OAuth/DCR, metadata, PRM `authorization_servers`). Raises if unset in `build_auth_provider()`. |
+| `AUTH_ISSUER` | Optional expected JWT `iss` (unset skips check) |
+| `AUTH_JWKS_URI` | Optional JWKS override; else discovered from `AUTH_SERVER` |
+| `AUTH_AUDIENCE` | Optional expected `aud` (comma-separated). Unset skips + warns |
+| `AUTH_REQUIRED_SCOPES` | Optional global scopes (also PRM `scopes_supported`) |
+| `AUTH_RESOURCE` | Optional public MCP resource URL for PRM; else local/deploy fallback via `LIGHTRAIL_ROUTE_*` |
+
+JWKS fetch uses the shared async httpx client; authorization-server metadata uses a short-lived sync client with the same TLS settings ([HTTP client](http-client.md)).
+
+### Example configuration
+
+```bash
+AUTH_SERVER=https://auth.example.com
+AUTH_ISSUER=
+AUTH_AUDIENCE=mcp.read
+AUTH_REQUIRED_SCOPES=mcp.read
+AUTH_RESOURCE=https://mcp.example.com/mcp
+```
+
+## Authorize every tool with global scopes
+
+Set `AUTH_REQUIRED_SCOPES` (via `build_auth_provider()` → `mcp.auth.required_scopes`). FastMCP `RequireAuthMiddleware` rejects tokens that lack those scopes.
+
+With `build_http_app(mcp)`, failed global checks get `WWW-Authenticate` with RFC 6750 `scope=` listing those global scopes (upstream FastMCP/SDK often omit `scope=`). That enables client step-up for the baseline server requirements.
+
+Global scopes apply to all tools. Tools with no per-tool marks still need only this set (for example `mcp.read`).
+
+## Enforce extra scopes per tool
+
+Use `@require_tool_scopes` (or `meta["required_scopes"]`) when a tool needs scopes beyond the global set. Missing scopes → HTTP 403 with `WWW-Authenticate` and `scope=` = **union** of global + tool scopes (required set for that call, not only missing ones).
+
+```python
+@mcp.tool
+@require_tool_scopes("api.security")
+async def search_advisories(...):
+    ...
+```
+
+Or override / merge at app build time:
+
+```python
+app = build_http_app(
+    mcp,
+    tool_scopes={"dynamic_tool": ["admin"]},  # tool must already exist on mcp
+    middleware=[my_custom_middleware],
+    path="/mcp",
+)
+```
+
+### Step-up when a tool needs more scopes
+
+1. Token has `mcp.read` but not `api.security` → global gate passes
+2. Per-tool check fails → HTTP 403 with `scope="mcp.read api.security"`
+3. Client re-authorizes with those scopes and retries
+
+This is **not** FastMCP `auth=require_scopes(...)` (that hides tools and returns JSON-RPC "not found" on HTTP 200). Ours keeps tools listed and returns HTTP 403 + `WWW-Authenticate` for OAuth step-up. Both are valid; only ours is the Auth step-up path (see [compliance](#meet-mcp-authorization-requirements)).
+
+### Cost of per-tool checks
+
+- **No per-tool scopes**: response interception only (no body read); still patches `scope=` on global 401/403
+- **Per-tool scopes**: buffer POST for `tools/call`; reject over `MAX_BODY_SIZE` (256 KB) with HTTP 413 and `Connection: close` (mid-stream rejects also drain a bounded amount of leftover body). Still set reverse-proxy limits (`client_max_body_size 256k` / ingress equivalent)
+- **Streamable HTTP**: full step-up support. **SSE**: middleware runs; 403 on POST is unreliable for clients (protocol limitation). **STDIO**: N/A
+
+## Use the access token in tools
+
+```python
+from fastmcp.server.dependencies import get_access_token
+
+access_token = get_access_token()
+if access_token:
+    raw_jwt = access_token.token
+    claims = access_token.claims
+    scopes = access_token.scopes
+```
+
+Bearer string only: `await resolve_bearer_token()` from `rh_fastmcp_server_commons.services.graphql`.
+
+GraphQL forwarding (do not hit `GRAPHQL_ENDPOINT` with raw httpx if you need the MCP bearer):
+
+- `execute_graphql(...)` / `run_operation(...)` / `ops, run_operation_fn = bind_operations(...)` / `GraphQLHandler`
+
+GraphQL-backed MCP tools are still Python `@mcp.tool` wrappers. Per-tool scopes go on that Python tool. See [GraphQL tools](graphql.md).
+
+## Meet MCP Authorization requirements
+
+With `auth=build_auth_provider()` and `build_http_app(mcp)`:
+
+| Feature | Spec / RFC | Status |
+|---------|------------|--------|
+| Protected Resource Metadata | RFC 9728 / MCP Auth | Yes (`build_auth_provider`) |
+| Bearer + JWT sig/exp | MCP Auth / RFC 6750 | Yes |
+| Global required scopes + PRM `scopes_supported` | MCP Auth | Yes (`AUTH_REQUIRED_SCOPES`) |
+| `WWW-Authenticate` + `scope=` on 401/403 | RFC 6750 / MCP step-up | Yes via `build_http_app` (upstream FastMCP/SDK omit `scope=`) |
+| Per-tool HTTP 403 step-up | MCP step-up / RFC 6750 | Yes via `@require_tool_scopes` (not via FastMCP `auth=require_scopes`) |
+| Challenge `scope=` = required scopes for the operation | RFC 6750 / MCP Auth | Yes (global ∪ per-tool) |
+| Audience binding | MCP Auth MUST (RFC 8707 intent) | **Configure `AUTH_AUDIENCE`**. Some IdPs put scopes in `aud`, not the resource URL. Unset = skipped + warning (violation) |
+| Optional `iss` check | Defense in depth | Optional `AUTH_ISSUER` |
+
+FastMCP `auth=require_scopes(...)` (hide tool / JSON-RPC not-found) is allowed and orthogonal; it is not the MCP Auth step-up challenge. Prefer `@require_tool_scopes` when clients must re-authorize.
+
+Upstream: if FastMCP/SDK grow native `scope=` ([#4513](https://github.com/PrefectHQ/fastmcp/issues/4513)) or per-tool HTTP scopes ([#4334](https://github.com/PrefectHQ/fastmcp/issues/4334)), our middleware pass-through / thin-alias paths apply.

rh_fastmcp_server_commons-0.3.1/docs/configuration.md

@@ -0,0 +1,46 @@
+# Configuration
+
+Shared environment variables live in `rh_fastmcp_server_commons.env`. Most values are read at **import time**, so servers must set defaults before importing consumers.
+
+## Bootstrap order
+
+1. `app/env_config.py` sets defaults on `os.environ`
+2. Call `configure_telemetry()` before importing FastMCP (see [observability](observability.md))
+3. Import auth, tools, and other modules that pull in `rh_fastmcp_server_commons.env`
+4. Register tools, then `build_http_app(mcp)` (see [authentication](authentication.md))
+
+## Resource URL resolution
+
+`AUTH_RESOURCE` (also exported as `MCP_RESOURCE`) is the public MCP resource URL for OAuth PRM:
+
+1. Use `AUTH_RESOURCE` if set
+2. Else `LIGHTRAIL_ROUTE_SCHEME` (default `http`) + `LIGHTRAIL_ROUTE_HOSTNAME` (default `localhost:8080`) → `{scheme}://{host}/mcp`
+
+`MCP_BASE_URL` is derived from that resource: strip a trailing `/mcp`, or use `scheme://netloc` when the path is not `/mcp`.
+
+## Environment catalog
+
+| Variable | Role | Details |
+|----------|------|---------|
+| `GRAPHQL_ENDPOINT` | Upstream GraphQL URL | [GraphQL tools](graphql.md) |
+| `CLIENT_NAME` | `apollographql-client-name` header | [GraphQL tools](graphql.md) |
+| `GRAPH_REF` | Optional Apollo graph ref (server use) | server-specific |
+| `AUTH_SERVER` | MCP Auth IdP / SSO base URL | [Authentication](authentication.md) |
+| `AUTH_ISSUER` | Optional expected JWT `iss` | [Authentication](authentication.md) |
+| `AUTH_JWKS_URI` | Optional JWKS URL override | [Authentication](authentication.md) |
+| `AUTH_AUDIENCE` | Optional expected JWT `aud` (comma-separated) | [Authentication](authentication.md) |
+| `AUTH_REQUIRED_SCOPES` | Global required scopes (comma-separated) | [Authentication](authentication.md) |
+| `AUTH_RESOURCE` | Public MCP resource URL for PRM | [Authentication](authentication.md), above |
+| `LIGHTRAIL_ROUTE_SCHEME` / `LIGHTRAIL_ROUTE_HOSTNAME` | Local fallback for `AUTH_RESOURCE` | above |
+| `LOGGING_LEVEL` | Root log level (default `info`) | [Observability](observability.md) |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Enables OTLP export when set | [Observability](observability.md) |
+| `OTEL_SERVICE_NAME` | OTEL `service.name` | [Observability](observability.md) |
+| `OTEL_RESOURCE_ATTRIBUTES` | Extra OTEL resource attrs (`k=v,k=v`); typically `deployment.environment=...` | [Observability](observability.md) |
+| `OTEL_EXPORTER_OTLP_INSECURE` | Force insecure OTLP gRPC | [Observability](observability.md) |
+| `SSL_VERIFY` | TLS verify for httpx (default `true`) | [HTTP client](http-client.md) |
+| `EXTRA_CA_CERTS` / `SSL_CERT_FILE` | Optional extra CA bundle | [HTTP client](http-client.md) |
+| `SEARCH_ENDPOINT` | Solr search URL | [Search](search.md) |
+| `SEARCH_CLIENT_ID` | Parameter for search API call | [Search](search.md) |
+| `LIGHTRAIL_CMDB_CODE` | Optional CMDB field on request logs | [Observability](observability.md) |
+
+Missing `GRAPHQL_ENDPOINT` or `AUTH_SERVER` is logged as an error when `rh_fastmcp_server_commons.env` is imported; `build_auth_provider()` still raises if `AUTH_SERVER` is unset.

rh_fastmcp_server_commons-0.3.1/docs/graphql.md

@@ -0,0 +1,132 @@
+# GraphQL tools
+
+Load named operations from `*.graphql`, POST them to `GRAPHQL_ENDPOINT` with the MCP bearer, and run them through a handler pipeline. MCP **tools** are Python `@mcp.tool` wrappers in each server repo. Domain queries, descriptions, and output schemas stay in the server (not this package). `.graphql` files are not tool definitions and carry no auth scopes.
+
+## Server layout and flow
+
+| Path | Role |
+|------|------|
+| `app/tools/operations/*.graphql` | Query + operation name (`bind_operations`) |
+| `app/tools/descriptions/<tool>.md` | Tool description (`load_tool_description`) |
+| `app/tools/__init__.py` | `OPERATIONS_DIR`, `DESCRIPTIONS_DIR` |
+| `app/tools/pipeline_handlers/defaults.py` | `bind_operations` → shared handlers (`GRAPHQL_HANDLER`, …) |
+| `app/tools/<tool>.py` | `OPERATION`, `HANDLERS`, `register(mcp)` |
+| `app/tools/tools.py` | `register_tools(mcp)` |
+| `app/tools/_common.py` | Shim: one-arg `load_tool_description`; re-exports `run_tool` / `output_schema` |
+
+```text
+operations/*.graphql
+  -> bind_operations(OPERATIONS_DIR) -> (OPS, run_operation)
+  -> defaults.py: GRAPHQL_HANDLER = GraphQLHandler(run_operation_fn=run_operation)
+  -> <tool>.py: register(mcp) / run_tool(..., HANDLERS)
+       -> optional pre-handlers (e.g. coerce search input)
+       -> GraphQLHandler fills ctx.raw
+       -> optional TransformHandler: ctx.raw -> ctx.payload
+       -> model_validate(ctx.payload or ctx.raw)
+```
+
+## Environment
+
+Full catalog and bootstrap order: [configuration](configuration.md). GraphQL-critical vars:
+
+| Variable | Role |
+|----------|------|
+| `GRAPHQL_ENDPOINT` | Upstream URL. Missing → `execute_graphql` returns `GraphQLResult` with `status_code=0` |
+| `CLIENT_NAME` | `apollographql-client-name` (default `mcp-server`) |
+
+Inbound MCP auth (`AUTH_*`) and the same bearer forwarded outbound: [authentication](authentication.md). TLS / httpx verify: [HTTP client](http-client.md).
+
+## Operations (`*.graphql`)
+
+```python
+# defaults.py
+from rh_fastmcp_server_commons.pipeline.handlers.graphql import GraphQLHandler
+from rh_fastmcp_server_commons.services.graphql.operations import bind_operations
+
+from app.tools import OPERATIONS_DIR
+
+OPS, run_operation = bind_operations(OPERATIONS_DIR)
+GRAPHQL_HANDLER = GraphQLHandler(run_operation_fn=run_operation)
+# plus server-specific handlers as needed
+```
+
+Rules:
+
+- One operation per file; name from `query operation_name` (not the filename)
+- Duplicate names or an empty directory raise `ValueError`
+- Stored as `GraphQLOperation(name, query)` only
+
+Convention: same snake_case for file stem, GraphQL op, and MCP tool (e.g. `search_advisories`).
+
+```graphql
+query search_advisories($input: ErrataSearchInput!) {
+  # ...
+}
+```
+
+## Transport
+
+| API | Behavior |
+|-----|----------|
+| `resolve_bearer_token()` | FastMCP access token string, or `None` (logs error) |
+| `execute_graphql(...)` | POST to `GRAPHQL_ENDPOINT` with bearer (explicit or resolved). Always calls `inject(headers)` for W3C context (useful when an active span exists; see [observability](observability.md)). TLS via `httpx_verify_setting()` ([HTTP client](http-client.md)). Returns `GraphQLResult(data, errors, status_code)` without raising. Config/token/network failures use `status_code=0` |
+| `run_operation(ops, name, vars)` | Drops `None` vars, calls `execute_graphql`, returns `data` or raises `GraphQLToolError` (errors, missing data, or HTTP `>= 400`) |
+
+Do not call `GRAPHQL_ENDPOINT` with raw httpx if you need the MCP bearer forwarded.
+
+## Tool pipeline
+
+`ToolContext`: `operation`, `tool_args`, `variables`, `model_type`, optional `raw` / `payload`.
+
+| Handler | Role |
+|---------|------|
+| `GraphQLHandler` | Sets `ctx.raw` via `run_operation_fn`; maps `GraphQLToolError` → `ToolChainError` |
+| `TransformHandler(fn)` | After GraphQL: requires `ctx.raw`; sets `ctx.payload = fn(ctx.raw, ctx.tool_args)` |
+| Server-specific | Before and/or after GraphQL (e.g. coerce search `input`) |
+
+`run_tool` → `run_tool_chain`: run handlers in order; validate `ctx.payload` or `ctx.raw` with `model_type`; on `ToolChainError` return FastMCP `ToolResult` (`is_error=True`, structured `ToolErrorResponse`). `run_tool` is generic over the output model (`T | ToolResult`), so servers do not need to cast the return type.
+
+Commons helpers: `load_tool_description(name, dir)`, `output_schema(model)` (`model_json_schema()`), generic `run_tool`. Servers usually call them through `_common.py` (one-arg description loader plus re-exports).
+
+## Defining a tool
+
+```python
+from fastmcp import FastMCP
+from fastmcp.tools.base import ToolResult
+from rh_fastmcp_server_commons.pipeline.handlers.transform import TransformHandler
+
+from app.schemas.tool_outputs import GetProductIdOutput
+from app.tools._common import load_tool_description, output_schema, run_tool
+from app.tools.pipeline_handlers.defaults import GRAPHQL_HANDLER
+from app.transformers.get_product_id import transform_get_product_id
+
+OPERATION = "get_product_id"
+HANDLERS = (
+    GRAPHQL_HANDLER,
+    TransformHandler(transform_get_product_id),  # fn(raw, tool_args) -> dict for model_validate
+)
+# Optional: put server-specific handlers before GraphQL (e.g. SEARCH_INPUT_HANDLER)
+# Omit TransformHandler when the GraphQL shape already matches the output model
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool(
+        name=OPERATION,
+        description=load_tool_description(OPERATION),
+        output_schema=output_schema(GetProductIdOutput),
+    )
+    async def get_product_id(name: str | None = None) -> GetProductIdOutput | ToolResult:
+        return await run_tool(
+            OPERATION, {"name": name}, GetProductIdOutput, HANDLERS
+        )
+```
+
+```python
+def register_tools(mcp: FastMCP) -> None:
+    for tool in TOOLS:
+        tool.register(mcp)
+```
+
+`run_tool`'s operation name must match the `query` identifier. `name=OPERATION` keeps MCP tool name and GraphQL op aligned when they share that string.
+
+Per-tool OAuth scopes (if any) go on the Python `@mcp.tool`, not in `.graphql` or description files. Details: [authentication](authentication.md).