[Feature Request]: Configuration Validation & Schema Enforcement using Pydantic V2 models, config validator cli flag

[crivetimihai]

🧭 Epic — Configuration Validation & Schema Enforcement using Pydantic V2 models

Field	Value
Title	Gateway-wide Configuration Validation & Schema Enforcement
Goal	Fail fast on any malformed setting, API payload, or DB row by validating against explicit schemas at every layer (startup, ingress, persistence).
Why now	Multi-tenant RBAC, LDAP sync, and soon-to-be-public app-templates dramatically raise the blast-radius of bad configs. Early rejection prevents privilege-escalation, data leakage, and “half-up” nodes.
Depends on	RBAC Multi-Tenancy epic (scope columns), LDAP Integration epic (user/group tables).

Use Pydantic V2 for validation and models.

Adds a configuration validator tool to the mcpgateway CLI.

See also: helm values.schema.json

---

🧭 Type of Feature

• Security hardening
• Reliability / DX
• Developer tooling

---

🙋‍♂️ User Stories

#	Persona & Need	Acceptance Criteria (summarised)
1	Platform engineer — “Start-up must fail if env vars are bad.”	• Launch with BAD_PORT=99999 exits ≠ 0 with stack-trace & clear message. • Systemd Restart= sees non-zero exit.
2	API client — “Get precise error when sending invalid payload.”	• POST /tools with bad JSONSchema returns 422 ➜ {"loc":["body","input_schema"],"msg":"Unexpected keyword"}.
3	DBA / Security — “Direct DB writes can’t bypass checks.”	• INSERT INTO tools … name='bad name' raises CHECK constraint failed.
4	DevOps — “Validate config files before deploy.”	• make validate-config CONFIG=tool.yml exits 0 only when YAML matches central JSONSchema.

---

📐 Validation Pipeline

flowchart LR
    Start["Startup (config.py<br/>Pydantic Settings)"]
    API["Ingress (FastAPI + Pydantic models)"]
    DBHook["SQLAlchemy<br/>before_insert/update"]
    DB

    Start --> GatewayReady
    API --> DBHook --> DB

    style Start fill:#B7E4C7,stroke:#333
    style API  fill:#B6D7FF,stroke:#333
    style DBHook fill:#FFD6A5,stroke:#333

Loading

Green = process dies on failure • Blue = 4xx to caller • Orange = transaction rolled back

---

🔄 Roll-out Plan

Phase	Flag	Deliverable
0	–	Schema inventory of every model & env var (living in /schemas/).
1	EXPERIMENTAL_SCHEMA_STARTUP	Pydantic BaseSettings for all env vars; node crashes on invalid.
2	EXPERIMENTAL_SCHEMA_INGRESS	All POST/PUT payloads upgraded to strict Pydantic models.
3	EXPERIMENTAL_SCHEMA_DB	SQLAlchemy listeners + DB CHECK/JSON_VALID constraints.
4	on	Remove flags, block legacy lenient paths, publish docs.

---

🔧 Task Break-down

1. Model & Spec Inventory

   • Enumerate tools, prompts, servers, gateways JSONSchemas (semver tag).
   • Store in schemas/ with CI diff-checker.

2. Startup Validators

   • Replace ad-hoc os.getenv with Pydantic BaseSettings.
   • Add regex/enum validators for URLs, lists, ports.

3. Ingress Validators

   • Promote all schemas.py models to Config(strict=True).
   • Custom validators: validate_json, validate_cron, merge_auth_fields.

4. Persistence Guards

   • SQLAlchemy before_insert / before_update hooks call jsonschema.validate.
   • Postgres CHECK (jsonb_valid(...)) on input_schema, headers, etc.
   • Regex check on name columns.

5. CLI / CI Tooling

   • scripts/validate_config.py (accepts YAML/JSON, prints error path).
   • GitHub Action fails PR if schema changes lack semver bump.

6. Fuzz & Property Tests

   • Hypothesis tests feed random invalid payloads → expect 422.
   • Load 10 k valid rows → ensure no slow-down > 5 %.

7. Docs & Samples

   • “Writing a Tool JSONSchema” guide + playground link.
   • Redoc/OpenAPI auto-regenerated nightly.

8. Monitoring

   • Counter config_validation_fail_total{stage=startup|ingress|db}.
   • Alert if ingress errors spike > 1 % in 5 min.

---

🔄 Alternatives Considered

Option	Pros	Cons	Decision
Rely only on ingress validation	Simpler code	DB back-doors stay open	❌
Use SCIM 2.0 external schema registry	Standards-based	Overkill / new infra	🔄 Future
“Trust clients” (no validation)	Zero dev effort	High risk	❌

---

📓 Additional Context

• Startup settings already partially use Pydantic; this formalises & extends.
• JSONSchema draft-2020-12 chosen for forward compatibility (AJV & VS Code have good plug-ins).
• Roll-back: disable flags + truncate validator_errors log table.

---

Delivering this epic means: every config mistake surfaces immediately, with a tight error message, before it can threaten tenant isolation or bring a node up in an undefined state.

[crivetimihai]

mcpgateway --validate-config (or similar)

Goals

• Provide operators with machine-readable config metadata derived from mcpgateway.config.Settings.
• Enforce stronger runtime validation for .env inputs (types, enums, ranges), surfacing actionable errors early.
• Wire schema and validation tooling into existing developer workflows (make check-env, CI) without breaking current env files.

Work Breakdown

1. Export a JSON Schema for Settings

• Add a helper to mcpgateway/config.py:

  def generate_settings_schema() -> dict:
      """Return the JSON Schema describing Settings."""
      return Settings.model_json_schema(mode="validation")

• Extend mcpgateway/cli.py with a new command or flag:

  @app.command()
  def config_schema(output: Annotated[Optional[Path], typer.Option()] = None) -> None:
      """Emit the Settings JSON schema."""
      schema = generate_settings_schema()
      data = json.dumps(schema, indent=2, sort_keys=True)
      if output:
          output.write_text(data)
      else:
          typer.echo(data)

• Document usage in docs/ (e.g. python -m mcpgateway.config --schema > docs/docs/config.schema.json—any path is fine) so platform teams can validate their own env files.

2. Tighten Field Definitions

• Replace str fields that have a finite option set with Literal (e.g. log_format, cache_type, transport_type).
• Use richer pydantic types where appropriate:
  • AnyUrl / HttpUrl for URL-based fields (APP_DOMAIN, FEDERATION_PEERS, SSO issuers).
  • conint, PositiveInt, PositiveFloat for numeric ranges (PORT, retry settings, timeouts).
  • SecretStr for sensitive values to avoid accidental logging.
  • Json[list[str]] or custom validators for list-like envs instead of raw strings.
• Keep defaults aligned with .env.example; update comments there to reflect new constraints (e.g. lowercase booleans, valid URIs).
• Make sure new validators raise ValueError with clear messages so misconfigured envs stop booting early.

3. Provide a Dedicated Env Validation CLI

• Create mcpgateway/scripts/validate_env.py:

  from pathlib import Path
  import sys
  
  from mcpgateway.config import Settings
  from pydantic import ValidationError
  
  def main(path: str = ".env") -> None:
      try:
          Settings(_env_file=path)
      except ValidationError as exc:
          print(f"Invalid configuration in {path}\n{exc}", file=sys.stderr)
          raise SystemExit(1)
  
  if __name__ == "__main__":
      main(sys.argv[1] if len(sys.argv) > 1 else ".env")

• Update Makefile check-env target to run python -m mcpgateway.scripts.validate_env .env.example.
• Optionally emit success message or collected warnings (reuse get_security_warnings).

4. Testing & Documentation

• Add unit coverage for the new CLI hook and validators (e.g. parametrize invalid literals, malformed URLs).
• Provide a short how-to in docs/docs/operations/config-validation.md covering:
  1. Generating the schema.
  2. Validating environments during deployment pipelines.
• Mention the new command in release notes once shipped.

Open Questions

• _normalize_env_list_vars() mutates certain env vars (e.g. SSO_TRUSTED_DOMAINS=corp.example,partner.example) into JSON (["corp.example", "partner.example"]) at import time so Pydantic receives a list. Do we keep that pre-processing, or move to typed fields (Json[list[str]], Literal[...]) so validation happens on the raw value without rewriting os.environ?