Generate MCP server.json from integration catalog entries

Summary

Add a generated MCP server.json export for integration catalog entries that describe MCP servers, while keeping integrations/catalog/*.json as the only hand-authored source of truth.

This follows the same principle as the integration catalog unification work: one manually maintained integration JSON per service, with derived artifacts generated from it.

Motivation

The MCP ecosystem has an official server.json format for describing MCP servers. For OpenHands catalog entries that already represent MCP servers, we should align with that standard instead of maintaining only a bespoke catalog shape.

This should make OpenHands integrations easier to compare with, publish to, or consume alongside the MCP registry, while still preserving OpenHands-specific UX metadata such as credential labels, install hints, default connection choices, and Integration Hub / Agent Canvas behavior.

Proposed approach

• Keep integrations/catalog/*.json as the only hand-edited source of truth.
• Add a generator, likely under scripts/, that emits server.json-compatible files for catalog entries with MCP connection options.
• Generate only for MCP entries; HTTP/OpenAPI-only integrations can remain OpenHands-specific.
• Map remote MCP transports:
  • transport.kind: "shttp" -> remotes[].type: "streamable-http"
  • transport.kind: "sse" -> remotes[].type: "sse"
• For stdio MCP entries, infer package metadata where possible, e.g. npx -y @modelcontextprotocol/server-* -> npm package with stdio transport.
• Put OpenHands-specific metadata under a namespaced _meta field, e.g. dev.openhands or another agreed reverse-DNS namespace.
• Validate generated files against the current MCP server.schema.json.
• Mark generated files clearly as auto-generated and document the regeneration command.

Non-goals

• Do not make generated server.json files the source of truth.
• Do not require all integrations to become MCP registry entries.
• Do not convert HTTP/OpenAPI integrations without an applicable standard.
• Do not block the current catalog unification PRs on this migration.

Acceptance criteria

• A command can generate MCP server.json artifacts from the current integration catalog.
• Generated artifacts validate against the MCP server schema for supported entries.
• OpenHands-specific fields are preserved in namespaced metadata or remain in the source catalog.
• Documentation explains that integrations/catalog/*.json remains the manual source of truth.

Related context

Follow-up to the integration catalog unification PRs:

• https://github.com/OpenHands/extensions/pull/346
• https://github.com/OpenHands/integrations-hub/pull/274
• https://github.com/OpenHands/agent-canvas/pull/1451

This issue was created by an AI agent (OpenHands) on behalf of Graham Neubig.

PR evidence acceptance criteria

• Current main evidence: On current main, attempt to generate MCP server.json artifacts from the catalog and show that no schema-valid generator/output contract exists.
• PR branch evidence: On the PR branch, modify one source catalog entry, regenerate, and verify deterministic schema-valid artifacts only for MCP entries, correct shttp/SSE/stdio mappings, preserved namespaced OpenHands metadata, and no hand edits to generated files.
• Required evidence package: The PR records both commit SHAs and exact environment/setup. Run the full relevant backend, service, infrastructure, or data pipeline live with PR code and attach commands plus output/logs; a movie or video is not a substitute for this live run. Attach generator/validation commands, schema version, representative diffs, and a clean regeneration check.

Inspect integrations/catalog/*.json and the proposed scripts/ generator location first, then review the current MCP server.schema.json. Done means a deterministic command generates artifacts only for MCP entries, maps shttp, SSE, and stdio correctly, preserves namespaced OpenHands metadata, validates outputs, and documents regeneration without hand-editing generated files.