@agenticprimitives/surface-catalog

One declaration for every HTTP route, A2A skill, and MCP tool — and the generators that derive the rest.

Instead of hand-writing an A2A Agent Card here, MCP declareTool calls there, an OpenAPI doc somewhere else, and rate-limit profiles in a fourth place — declare each capability once as a SurfaceDescriptor, then generate every downstream artifact from the catalog. Generic and transport-agnostic: it carries no hostnames, no white-label/vertical content, and no chain types.

See spec 288 §3 for the full design.

The descriptor

import { defineSurface, type SurfaceDescriptor } from '@agenticprimitives/surface-catalog';

const getPii: SurfaceDescriptor = {
  id: 'get_pii',
  protocol: 'mcp',
  description: "Read the principal's PII record",
  inputSchema: { type: 'object', properties: { fields: { type: 'array', items: { type: 'string' } } } },
  authorization: {
    mode: 'agentic-delegation',
    riskTier: 'high',
    entitlement: { resource: 'person.pii', action: 'read', classification: 'pii.sensitive' },
  },
  operations: {
    rateLimitProfile: 'sensitive-read-v1',
    maxBodyBytes: 16_384,
    timeoutMs: 10_000,
    idempotency: 'safe',
    cache: 'no-store',
  },
};

const registry = defineSurface([getPii]);

The authorization block references the existing decision engines — riskTier/requiredEnforcers map onto the tool-policy taxonomy, and entitlement onto the entitlements matcher. The registry is a catalog that points at them; it never makes the authorization decision.

Generators

import {
  toMcpToolDeclaration,   // { name, classification } for tool-policy.declareTool
  toMcpToolClassification,// the @sa-* object
  toA2aSkill,             // an A2A card skill entry
  toOpenApiDocument,      // OpenAPI 3.0 (what Cloudflare API Shield accepts)
} from '@agenticprimitives/surface-catalog';

const decl = toMcpToolDeclaration(getPii);
// → { name: 'get_pii', classification: { '@sa-tool': 'delegation-verified', '@sa-auth': 'session-token',
//      '@sa-risk-tier': 'high', '@sa-rate-limit': 'sensitive-read-v1' } }

const openapi = toOpenApiDocument(registry, { title: 'Demo MCP', version: '1.0.0' });

Outputs are structurally typed (not hard-imported from tool-policy/a2a) so this package stays dependency-light; you feed the result to declareTool, your A2A card, or your OpenAPI host.

Deployment preflight

import { runDeploymentPreflight, assertDeploymentPreflight, findCoverageGaps } from '@agenticprimitives/surface-catalog';

assertDeploymentPreflight(registry);          // throws on any error finding
runDeploymentPreflight(registry);             // → PreflightFinding[] (errors + warnings)
findCoverageGaps(registry, liveMcpToolNames); // → ids with no descriptor

Preflight catches a mis-declared capability before it ships — e.g. an agentic-delegation capability with no rate-limit profile, a critical capability that doesn't require on-chain acceptance, or a public capability marked high/critical risk.

License

MIT