Generate MCP server.json from integration catalog entries

[neubig]

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:

• feat(integrations): unify catalog into single JSON source of truth (JS + Python) #346
• https://github.com/OpenHands/integrations-hub/pull/274
• chore: pin extensions catalog dependency agent-canvas#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.

[ajdelaguila]

Full disclosure: I maintain Data Olympus, a git-native governed knowledge-base format plus Streamable HTTP MCP server for coding agents: https://github.com/knaisoma/data-olympus

Related context from the OpenHands repo: I commented on OpenHands/OpenHands#9948 about separating raw context retrieval from governed project knowledge: OpenHands/OpenHands#9948 (comment)

This server.json generation work seems like the right place to make MCP-based knowledge/governance servers easier to discover without hand-maintaining parallel metadata.

A few field notes from Data Olympus that may be useful as a test case:

• It is self-hosted Streamable HTTP, usually local or team-internal, not a hosted SaaS integration.
• The endpoint is not the whole install story. It also needs a git-backed KB bundle path, index path, and optional remote/push configuration.
• The important user-facing category is not generic memory; it is governed project knowledge: accepted standards, decisions, workflows, supersession history, and proposal writes.
• Catalog metadata should distinguish read-only lookup from write/proposal capability. A server that can propose KB edits has different safety and credential expectations than a pure retrieval server.
• Generated metadata should preserve enough install hints for local development (http://localhost:8080 default) and production deployment, where a team may host the MCP endpoint behind auth or a proxy.

If useful, Data Olympus could be a concrete fixture for validating server.json generation for a non-SaaS MCP integration: Streamable HTTP transport, Apache-2.0, knowledge-base/governance/dev-tools categories, and setup docs at https://github.com/knaisoma/data-olympus