chore: prep Docker MCP Registry submission (roadmap 21.1)

[devopam]

Summary

Prep work for submitting MCPg to docker/mcp-registry — the registry backing Docker Desktop's MCP Toolkit / docker mcp CLI. This PR is submission prep only (roadmap 21.1); the actual fork + PR into docker/mcp-registry is a separate, outward-facing step (roadmap 21.2) pending explicit go-ahead, since it's a third-party public repo.

Eligibility check (2026-08-14): no existing general-purpose PostgreSQL entry in their registry (only prisma-postgres, which is Prisma-specific). MCPg clears every eligibility bar in their CONTRIBUTING.md: MIT license, root Dockerfile, and a live-verified stdio transport override.

What's added

• packaging/docker-mcp-registry/server.yaml — draft registry entry (category database, MCPG_DATABASE_URL as the sole required secret, MCPG_ACCESS_MODE exposed read-only-default, run.env forces MCPG_TRANSPORT: stdio).
• packaging/docker-mcp-registry/generate_tools_json.py — generates the registry's tools.json bypass file from tests/contract/tool_surface.snapshot.json. MCPg requires a live MCPG_DATABASE_URL to start, so Docker's build sandbox can't run the container to auto-discover tools the normal way; their CONTRIBUTING.md documents tools.json as the bypass. Confirmed the real shape ({name, description, arguments: [{name, type, desc}]} — not MCP-native inputSchema) against live registry entries (servers/database-server, servers/context7) before generating, rather than guessing.
• tests/contract/test_docker_mcp_registry_tools_json.py — drift guard, per this repo's "generated beats hand-maintained" rule.

Verification

• Built the image locally from the current root Dockerfile and ran a real initialize + tools/list JSON-RPC exchange over stdio against a throwaway Postgres container, with -e MCPG_TRANSPORT=stdio — confirms run.env: MCPG_TRANSPORT: stdio cleanly overrides the image's baked-in streamable-http default. No Dockerfile changes needed.
• python packaging/docker-mcp-registry/generate_tools_json.py produces all 254 entries; spot-checked simple and complex (nested object/array/anyOf-typed) tool schemas.
• pytest tests/contract/ — 49 passed.
• pytest tests/unit — 2856 passed, 3 skipped.
• ruff check / ruff format --check / mypy src/mcpg — clean.

Known gap (flagged, not blocking)

254 tools is unusually large for a single catalog entry; MCPg has no bucket/tool-filter env var today to ship a slimmer default surface (checked — doesn't exist). Tracked as roadmap 21.3; will address proactively in the actual registry PR description.

Advances roadmap row: 21.1

Summary by Sourcery

Prepare MCPg for submission to Docker’s MCP Registry by adding registry packaging metadata and a generated tools bypass file tied to the existing contract snapshot.

New Features:

• Add Docker MCP Registry server definition for MCPg, including catalog metadata, secrets, and configuration parameters.
• Introduce a generator script that derives the registry-compatible tools.json bypass file from the contract tool-surface snapshot.

Enhancements:

• Document the Docker MCP Registry submission roadmap and current prep work in the feature shortlist and changelog.
• Add a drift-guard test ensuring the checked-in tools.json stays in sync with the generator and the authoritative tool-surface snapshot.

Tests:

• Add contract tests that validate tools.json matches the generated output and fully covers all registered tools.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• The JSON Schema → flat type mapping in _resolve_type is intentionally narrow (only type and anyOf); consider failing loudly or logging when encountering unexpected shapes (e.g., oneOf, nested arrays/objects) so future schema changes don’t silently downgrade to the fallback string type.
• The generator logic is embedded in a script and imported via importlib.util in the test; consider extracting the core functions (_resolve_type, _flatten_arguments, main generation routine) into a small importable module so both the script entrypoint and tests can use stable, public APIs instead of depending on a script path and private functions.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The JSON Schema → flat type mapping in `_resolve_type` is intentionally narrow (only `type` and `anyOf`); consider failing loudly or logging when encountering unexpected shapes (e.g., `oneOf`, nested arrays/objects) so future schema changes don’t silently downgrade to the fallback `string` type.
- The generator logic is embedded in a script and imported via `importlib.util` in the test; consider extracting the core functions (`_resolve_type`, `_flatten_arguments`, main generation routine) into a small importable module so both the script entrypoint and tests can use stable, public APIs instead of depending on a script path and private functions.

## Individual Comments

### Comment 1
<location path="packaging/docker-mcp-registry/generate_tools_json.py" line_range="67-68" />
<code_context>
+    ``[{"type": "string"}, {"type": "null"}]`` — the first non-null branch
+    wins), and schemas missing ``type`` entirely (Any-typed params).
+    """
+    if "type" in prop_schema:
+        return str(prop_schema["type"])
+    if "anyOf" in prop_schema:
+        for branch in prop_schema["anyOf"]:
</code_context>
<issue_to_address>
**issue (bug_risk):** Handle list-valued JSON Schema `type` more robustly.

When `type` is an array (e.g. `['string', 'null']`), `str(prop_schema['type'])` returns the list representation, which won’t match the registry’s expected simple type strings. Please special‑case list-valued `type` and select the first non-`null` entry, consistent with your `anyOf` handling, so optional fields still resolve to a usable single type.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}