Merge branch 'main' into fix/hide-deactivated-prompts-tools-resources

Author: crivetimihai

.claude/skills/pr-review/SKILL.md

@@ -1,57 +1,99 @@
 ---
 name: pr-review
-description: Use when a feature branch is ready for code review, needs rebasing onto main, or before creating/updating a pull request. Also use when asked to review changes, check code quality, or verify a branch is merge-ready.
+description: >-
+  Review code changes for quality, security, correctness, and design. Use when
+  a feature branch is ready for review, before creating or updating a pull
+  request, when asked to check code quality, review changes, look at a diff,
+  or verify a branch is merge-ready. Also triggers on phrases like "review my
+  code", "what do you think of these changes", or "is this ready to merge".
 ---
 
 # PR Review
 
-Review all changes between `main` and the current branch HEAD, plus any staged
-and unstaged working-tree changes.
+A review-only skill. **Do not modify any files** — produce a report the author
+uses to make their own changes.
 
-## Setup
+## Gather context
 
-1. **Rebase** — Unless the user says otherwise, fetch `origin` and rebase onto
-   `origin/main`, resolving conflicts. If the branch has Alembic migrations,
-   run `alembic heads` after rebase — if multiple heads exist, update
-   `down_revision` to restore a single linear history.
+1. **Diff** — Collect all changes between `origin/main` and HEAD, plus any
+   staged/unstaged working-tree changes. This is the review scope. Treat
+   all of these changes as a single unit — assume everything will be
+   committed before merge. Do not report on git staging status (uncommitted,
+   unstaged, etc.) as a finding.
 
-2. **Gather context** — If a PR exists (`gh pr view`):
-   - PR description, title, review comments (`gh pr view --comments`)
-   - Linked issues (`gh issue view N`) to understand requirements
-   If no PR exists, review from the diff alone.
+2. **PR metadata** — If a PR exists (`gh pr view`), read the description,
+   review comments (`gh pr view --comments`), and linked issues
+   (`gh issue view N`) to understand requirements and prior feedback.
 
-3. **Read project docs** — Check for `AGENTS.md`, `CONTRIBUTING.md`,
-   `CLAUDE.md`. These are authoritative for test commands, linter config, and
-   conventions — use their commands exactly, not generic substitutes.
+3. **Project conventions** — Read `AGENTS.md`, `CONTRIBUTING.md`, or
+   `CLAUDE.md` if present. These are authoritative for linter commands, test
+   commands, and coding conventions — use their commands exactly.
 
 ## Review checklist
 
-Review the diff in priority order. Fix blocking issues directly when
-straightforward; flag issues that need human judgment.
+Review the diff in priority order. Report all findings for human review.
 
 | # | Category | Severity | Focus |
 |---|----------|----------|-------|
 | 1 | Security | Blocking | Injection, leaked secrets, auth gaps, OWASP top 10 |
 | 2 | Correctness | Blocking | Logic errors, edge cases, mismatch with linked issues |
-| 3 | Test coverage | Blocking | 100% differential coverage — verify changed code has tests |
-| 4 | Linter compliance | Blocking | Run project linters on touched files; resolve all findings |
+| 3 | Test coverage | Blocking | Differential coverage — verify changed code has tests |
+| 4 | Linter compliance | Blocking | Run project linters on touched files; report findings with exact commands |
 | 5 | Performance | High | N+1 queries, unnecessary allocations, bottlenecks |
-| 6 | Code quality | Medium | Redundancy, over-complexity, code smells |
-| 7 | Consistency | Medium | Follow documented conventions; suggest undocumented ones |
-| 8 | Alembic migrations | Conditional | Idempotence, reversibility, cross-DB compat, data safety, `batch_alter_table` for SQLite |
+| 6 | Redundancy | High | Duplicated logic, copy-paste patterns, shared-utility opportunities |
+| 7 | Design | High | Structural quality — see guidance below |
+| 8 | Consistency | Medium | Adherence to documented conventions |
+| 9 | Alembic migrations | Conditional | Idempotence, reversibility, cross-DB compat, `batch_alter_table` for SQLite |
+
+## Design review guidance
+
+### Structure and modularity
+
+- **Single-responsibility violations** — functions or classes doing more than
+  one thing. Name what each responsibility is and suggest how to split.
+- **God functions** — functions with >50 lines of logic or >3 levels of
+  nesting. Identify extraction points.
+- **Long parameter lists** — >5 parameters often indicate a missing config
+  object or dataclass.
+- **Tight coupling** — modules reaching into each other's internals. Suggest
+  interface boundaries.
+- **Deep nesting** — suggest early returns, guard clauses, or extracted helpers.
+
+### Object-oriented design and polymorphism
+
+This codebase tends toward long if/elif/else chains where polymorphic dispatch
+would be cleaner. **Actively look for these opportunities** in changed code and
+in code adjacent to changes:
+
+- **Type-switching conditionals** — e.g., `if transport == "sse": ... elif
+  transport == "websocket": ...`. Suggest an ABC or Protocol with concrete
+  implementations per variant.
+- **Conditional behavior by enum/string** — functions branching on a type field.
+  Suggest the Strategy or Template Method pattern.
+- **Scattered object creation** — conditionals that construct different objects
+  by type. Suggest a factory method or registry pattern.
+- **Dict-dispatch** — for simpler cases where class hierarchies are overkill,
+  `dict[key, callable]` dispatch tables are a good stepping stone.
+- **Copy-paste behavior across classes** — suggest a `Protocol` (structural
+  subtyping) or mixin.
+- **Missing abstract parents** — when classes share an interface but lack a
+  common base, suggest an `ABC` with `@abstractmethod`.
+
+### Missing abstractions
+
+- **Repeated patterns** across 3+ call sites → shared utility or base class.
+- **Data bags with scattered behavior** — pure data classes whose related logic
+  lives in other modules. The behavior should live with the data.
 
 ## Second opinions
 
-After your own review, run available second-opinion tools in parallel as
-background tasks. If a tool is missing from `$PATH` or fails, skip it and note
-reduced coverage.
+After your own review, attempt to run these tools as background tasks. If a
+tool is not installed or fails, skip it and note the reduced coverage.
 
-- **Codex**: `codex exec review --base origin/main`
-- **Bob**: Pipe the diff inline — `git diff origin/main..HEAD | bob "Review this
-  diff for correctness, security, and code quality. Be specific about
-  line-level issues."` Tailor the prompt to the PR content.
+- `codex exec review --base origin/main`
+- `git diff origin/main..HEAD | bob "Review this diff for correctness, security, and design quality. Be specific about line-level issues."`
 
-Attribute findings to their source (Claude/Codex/Bob) and resolve contradictions.
+Attribute findings to their source and resolve contradictions.
 
 ## Output format
 
@@ -62,23 +104,28 @@ Attribute findings to their source (Claude/Codex/Bob) and resolve contradictions
 [1-2 sentence overview: what changed, whether it meets PR/issue goals]
 
 ## Findings
-| # | Severity | Category | File:Line | Issue | Source |
-|---|----------|----------|-----------|-------|--------|
 
-## Fixes Applied
-[Issues fixed directly, with commit refs]
+### Blocking
+| File:Line | Category | Issue | Suggestion |
+|-----------|----------|-------|------------|
 
-## Remaining Issues
-[Issues needing human decision or outside scope]
+### High
+| File:Line | Category | Issue | Suggestion |
+|-----------|----------|-------|------------|
+
+### Medium
+| File:Line | Category | Issue | Suggestion |
+|-----------|----------|-------|------------|
 
 ## Recommendation
-Pick exactly ONE: Ready to merge | Ready after fixing remaining issues | Needs significant rework
+[Pick exactly ONE: "Ready to merge" | "Ready after addressing findings" | "Needs significant rework"]
+[1 sentence justification]
 ```
 
 ## Rules
 
-- Never mention Claude, Claude Code, or AI in commits or PR text.
-- Never push unless explicitly asked.
-- Sign commits with `git commit -s`. Verify Git author matches `gh auth status`.
-- Create new commits rather than amending existing ones when rebasing or fixing.
-- After fix-up commits, re-run linters and tests to confirm no regressions.
+- **Do not modify any files.** Report findings for the author to address.
+- Never mention Claude, Claude Code, or AI in any output.
+- Include exact linter commands and output so the author can reproduce.
+- Make suggestions concrete — name the method to extract, the class to create,
+  the interface to define. "Consider refactoring" is not actionable.

.env.example

@@ -19,7 +19,7 @@ BASIC_AUTH_PASSWORD=changeme
 
 # JWT secret used to sign tokens
 # PRODUCTION: Use a strong, unique value
-JWT_SECRET_KEY=my-test-key
+JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes
 
 # Passphrase used to encrypt stored auth secrets
 # PRODUCTION: Use a strong, unique value
@@ -731,7 +731,7 @@ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
 # Secret used to sign JWTs (required for HMAC algorithms: HS256, HS384, HS512)
 # PRODUCTION: Use a strong, random secret (minimum 32 characters)
 # Generate with: openssl rand -base64 32
-# JWT_SECRET_KEY=my-test-key
+# JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes
 
 # === RSA/ECDSA (Asymmetric) Configuration - Recommended for Production ===
 # Public and private key paths (required for asymmetric algorithms: RS*, ES*)
@@ -2707,22 +2707,121 @@ PLUGINS_CLI_MARKUP_MODE=rich
 # Copy resource attributes to span attributes (for Arize compatibility)
 # Some observability backends like Arize require certain attributes as span attributes
 # rather than resource attributes. Enable this to copy arize.project.name and model_id.
-# Direct env read (mcpgateway/observability.py)
+# Read via mcpgateway/config.py
 # OTEL_COPY_RESOURCE_ATTRS_TO_SPANS=false
 
 # Deployment environment label for observability resource attributes
-# Direct env read (mcpgateway/observability.py)
+# Read via mcpgateway/config.py
 # DEPLOYMENT_ENV=development
 
 # Jaeger exporter auth (only used when OTEL_TRACES_EXPORTER=jaeger)
-# Direct env read (mcpgateway/observability.py)
+# Read via mcpgateway/config.py
 # OTEL_EXPORTER_JAEGER_USER=
 # OTEL_EXPORTER_JAEGER_PASSWORD=
 
 # Test mode for observability (disables tracing when set to 1)
 # Direct env read (mcpgateway/observability.py)
 # MCP_TESTING=0
 
+# =============================================================================
+# Langfuse LLM Observability Integration
+# =============================================================================
+# Langfuse provides trace visualization, prompt management, evaluations,
+# cost tracking, and LLM analytics. Integrates via OTLP/HTTP.
+#
+# Quick start:  make langfuse-up
+# Access:       http://localhost:3100
+# Combined:     make langfuse-monitoring-up (Langfuse + Grafana/Tempo; gateway traces still go to Langfuse by default)
+#
+# Usage: docker compose -f docker-compose.yml -f docker-compose.with-langfuse.yml up -d
+
+# Langfuse OTLP endpoint override for the gateway.
+# Defaults to the local compose service when unset in the overlay.
+# LANGFUSE_OTEL_ENDPOINT=http://localhost:3100/api/public/otel/v1/traces
+
+# Langfuse API keys used by ContextForge to connect to Langfuse via OTLP.
+# For the local self-hosted compose overlay, unset values fall back to the
+# compose-local dev defaults `pk-lf-contextforge` / `sk-lf-contextforge`.
+# Set these when you want a different local project or when connecting to an
+# external Langfuse instance.
+# LANGFUSE_PUBLIC_KEY=pk-lf-<optional-override>
+# LANGFUSE_SECRET_KEY=sk-lf-<optional-override>
+
+# Optional OTEL auth override: base64("publicKey:secretKey")
+# When LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY are set, the gateway can
+# derive the Authorization header automatically and this override is not needed.
+# LANGFUSE_OTEL_AUTH=<base64-of-publicKey:secretKey>
+
+# Langfuse UI host port (default: 3100 to avoid Grafana conflict on 3000)
+# LANGFUSE_PORT=3100
+
+# Langfuse worker metrics port (localhost only)
+# LANGFUSE_WORKER_PORT=3130
+
+# Langfuse UI URL (used for NEXTAUTH_URL and CORS)
+# LANGFUSE_URL=http://localhost:3100
+
+# Auto-provisioned admin user override for the local self-hosted Langfuse overlay
+# LANGFUSE_INIT_USER_EMAIL=admin@example.com
+# LANGFUSE_INIT_USER_PASSWORD=<optional-override>
+
+# Auto-provisioned organization and project
+# LANGFUSE_INIT_ORG_ID=contextforge
+# LANGFUSE_INIT_ORG_NAME=ContextForge
+# LANGFUSE_INIT_PROJECT_ID=contextforge-gateway
+# LANGFUSE_INIT_PROJECT_NAME=ContextForge Gateway
+
+# Optional overrides for the local self-hosted Langfuse overlay only.
+# ContextForge does not read these. They are used only by docker-compose.with-langfuse.yml.
+# If unset, the overlay uses local-only defaults defined in that compose file.
+# LANGFUSE_POSTGRES_PASSWORD=<optional-override>
+# LANGFUSE_CLICKHOUSE_USER=clickhouse
+# LANGFUSE_CLICKHOUSE_PASSWORD=<optional-override>
+# LANGFUSE_MINIO_USER=minio
+# LANGFUSE_MINIO_PASSWORD=<optional-override>
+# LANGFUSE_REDIS_AUTH=<optional-override>
+# LANGFUSE_NEXTAUTH_SECRET=<optional-override>
+# LANGFUSE_SALT=<optional-override>
+# LANGFUSE_ENCRYPTION_KEY=<optional-override>
+
+# Langfuse optional features
+# LANGFUSE_TELEMETRY_ENABLED=true
+# LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES=false
+
+# Monitoring stack host port overrides for `make monitoring-up` and
+# `make langfuse-monitoring-up`. These are compose-only and are not read by
+# mcpgateway/config.py.
+# NGINX_PORT=8080
+# GRAFANA_PORT=3000
+# LOKI_PORT=3101
+# PROMETHEUS_PORT=9090
+# TEMPO_PORT=3200
+# TEMPO_OTLP_GRPC_PORT=4317
+# TEMPO_OTLP_HTTP_PORT=4318
+# TEMPO_IMAGE_TAG=2.10.0
+# PGADMIN_PORT=5050
+# REDIS_COMMANDER_PORT=8081
+# POSTGRES_EXPORTER_PORT=9187
+# REDIS_EXPORTER_PORT=9121
+# PGBOUNCER_EXPORTER_PORT=9127
+# NGINX_EXPORTER_PORT=9113
+# CADVISOR_PORT=8085
+
+# OTEL trace controls for Langfuse and other OTLP backends
+# Langfuse-specific attributes auto-enable when LANGFUSE_OTEL_ENDPOINT points to
+# Langfuse. Set these explicitly only when you want to override that behavior.
+# OTEL_EMIT_LANGFUSE_ATTRIBUTES=
+# OTEL_CAPTURE_IDENTITY_ATTRIBUTES=
+#
+# Payload capture is allowlist-based. By default the gateway does not capture
+# observation input or output payloads unless the relevant span names are listed.
+# The local `docker-compose.with-langfuse.yml` overlay sets a dev-friendly input
+# allowlist for `tool.invoke,prompt.render,llm.proxy,a2a.invoke`.
+# OTEL_REDACT_FIELDS=password,secret,token,api_key,authorization,credential,auth_value,access_token,refresh_token,auth_token,client_secret,cookie,set-cookie,private_key
+# OTEL_MAX_TRACE_PAYLOAD_SIZE=32768
+# OTEL_CAPTURE_INPUT_SPANS=tool.invoke,prompt.render
+# OTEL_CAPTURE_OUTPUT_SPANS=
+
 # --- Auxiliary tools and CLIs (non-gateway runtime) --------------------------
 
 # These are used by helper tools, CLIs, and SDK wrappers (not the main gateway server).

.github/CODEOWNERS

@@ -1,5 +1,6 @@
 # All files in the repo
 * @crivetimihai
+/.github/workflows/ @crivetimihai
 
 # Plugin framework
 /mcpgateway/plugins @araujof @terylt @jonpspri

.github/actionlint.yaml

@@ -0,0 +1,4 @@
+self-hosted-runner:
+  labels:
+    - ubuntu-24.04-s390x
+    - ubuntu-24.04-ppc64le

.github/workflows/alembic-upgrade-validation.yml

@@ -43,13 +43,15 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
 
       - name: Build candidate image
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
         with:
           context: .
           file: Containerfile.lite
@@ -66,7 +68,7 @@ jobs:
 
       - name: Upload upgrade validation logs
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: alembic-upgrade-validation-logs
           path: artifacts/upgrade-validation

.github/workflows/bandit.yml .github/workflows/bandit.yml.inactive.github/workflows/bandit.yml renamed to .github/workflows/bandit.yml.inactive

@@ -32,6 +32,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   bandit:
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
@@ -48,7 +51,9 @@ jobs:
       # 0️⃣  Check out the repository
       # -----------------------------------------------------------
       - name: ⬇️  Checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
 
       # -----------------------------------------------------------
       # 1️⃣  Run Bandit with custom filters