Skip to content

README.md

Latest commit

 

History

History
80 lines (65 loc) · 3.97 KB

README.md

File metadata and controls

80 lines (65 loc) · 3.97 KB
Raw

Integration catalog

This directory contains curated integration metadata for OpenHands clients. Most current entries are MCP-backed, but the schema also supports HTTP/OpenAPI integrations so clients can consume one source of truth.

  • catalog/<id>.json is the hand-authored source of truth. Add or edit an integration by changing exactly one file in that directory.
  • catalog-index.js is generated from catalog/*.json so the JavaScript package can statically import every individual JSON file without an aggregate catalog JSON asset.
  • The Python package includes the same individual catalog/*.json files and reads them directly.
  • index.js derives the supportsMcp/supportsOauth filters from the canonical connection options at read time.
  • index.d.ts contains the public TypeScript shape.

Each integration carries its OAuth/MCP connection data directly. Do not add a separate provider catalog or per-language provider data.

Every entry must include docsUrl. Marketplace input fields must explicitly declare both their type and whether they are required, rather than relying on client defaults. When connection metadata includes an identityMapping, it must also identify the external principal. These requirements keep catalogs actionable and prevent clients from guessing security- or UX-relevant defaults.

Connection options may also carry an optional connectionModel. This metadata lets consumers distinguish the authenticated principal from the external resource the credential can reach:

  • principalType describes who or what authenticated.
  • credentialScope describes the provider boundary enforced by the credential.
  • resourceType and resourceCardinality describe whether the grant represents one workspace/site/tenant or can enumerate several.
  • selectionMode tells clients whether the resource is known during auth, selected immediately after auth, or supplied at runtime.
  • identityMapping contains constrained dot paths for identity values returned by OAuth, access-token claims, or a provider identity endpoint.
  • resourceDiscovery describes a read-only endpoint used to enumerate resources when one grant covers several of them.

These fields are descriptive; they never broaden the scopes enforced by the provider credential. Consumers must not claim resource-level isolation when a provider token is only account- or tenant-scoped.

Consumers should use the read functions exported by the package:

import {
  getIntegrationCatalogEntry,
  listIntegrationCatalog,
} from "@openhands/extensions/integrations";

const catalog = listIntegrationCatalog();
const entry = getIntegrationCatalogEntry(catalog[0].id);

Migration from the MCP catalog

This catalog replaces the experimental @openhands/extensions/mcps export. The MCP-only mcps/ directory has been renamed to integrations/, and the old package exports were removed rather than kept as aliases.

  • Import INTEGRATION_CATALOG from @openhands/extensions/integrations instead of MCP_CATALOG from @openhands/extensions/mcps.
  • Read serializable logo metadata from each IntegrationCatalogEntry (logoUrl, iconBg, and iconColor) instead of importing React-specific logo maps.
  • Use IntegrationCatalogEntry instead of McpCatalogEntry.
  • Read MCP configuration from entry.connectionOptions[]. Direct MCP entries have provider: "mcp" and a transport; entries may expose multiple options such as id: "oauth" for a hosted OAuth MCP endpoint and id: "api" for an API-key or stdio fallback. The first option is the preferred default.
  • Automation catalog entries now use requiredIntegrationIds instead of requiredMcpIds.

The mcps API was intentionally broken because it was pre-release and had not been adopted as a stable public surface.

The catalog intentionally stores only serializable data, including language-agnostic logo URLs and optional presentation colors. Client applications can render those fields directly while keeping any purely UI-specific styling local.