Agent Discovery Infrastructure

{
  "version": "1.0",
  "name": "Hotel Search API",
  "description": "Search and book hotels worldwide",
  "url": "https://hotels.example.com",
  "tools": [
    {
      "name": "search_hotels",
      "description": "Search hotels by location, dates, and guests",
      "endpoint": "/api/hotels/search",
      "method": "POST",
      "parameters": {
        "type": "object",
        "properties": {
          "location": { "type": "string", "description": "City or region" },
          "checkin":  { "type": "string", "description": "ISO 8601 check-in date" },
          "checkout": { "type": "string", "description": "ISO 8601 check-out date" },
          "guests":   { "type": "number", "description": "Number of guests", "default": 2 }
        },
        "required": ["location", "checkin", "checkout"]
      }
    },
    {
      "name": "book_hotel",
      "description": "Create a hotel reservation",
      "endpoint": "/api/hotels/book",
      "method": "POST",
      "auth_required": true,
      "rate_limit": "100/hour"
    }
  ],
  "auth": {
    "type": "oauth2",
    "oauth2": {
      "token_url": "https://auth.example.com/token",
      "scopes": ["hotels:read", "bookings:write"]
    }
  },
  "tool_format": "jsonschema",
  "verticals": ["travel"],
  "bridge": {
    "mcp": "https://hotels.example.com/mcp",
    "ocp": "https://hotels.example.com/.well-known/ocp.json"
  }
}

npm install @opencommerceprotocol/agent-discovery

import { Hono } from 'hono';
import { serve } from '@hono/node-server';
import { agentDiscoveryMiddleware } from '@opencommerceprotocol/agent-discovery';

const app = new Hono();

// Mount discovery endpoints — serves /.well-known/agent.json automatically
agentDiscoveryMiddleware(app, {
  name: 'My Hotel API',
  description: 'Search and book hotels worldwide',
  url: 'https://hotels.example.com',
  verticals: ['travel'],
  tools: [
    {
      name: 'search_hotels',
      description: 'Search hotels by location and dates',
      endpoint: '/api/hotels/search',
      method: 'POST',
      parameters: {
        type: 'object',
        properties: {
          location: { type: 'string', description: 'City or region' },
          checkin:  { type: 'string', description: 'ISO 8601 check-in date' },
        },
        required: ['location'],
      },
    },
  ],
  auth: {
    type: 'oauth2',
    oauth2: { token_url: 'https://auth.example.com/token', scopes: ['hotels:read'] },
  },
  bridge: { ocp: '/.well-known/ocp.json' },
});

// Your actual API routes
app.post('/api/hotels/search', async (c) => {
  const { location } = await c.req.json();
  // ... implementation
  return c.json({ hotels: [] });
});

serve({ fetch: app.fetch, port: 3000 });

import { registerAgentTools } from '@opencommerceprotocol/agent-discovery';

const { manifest, toJSON } = registerAgentTools({
  name: 'My API',
  tools: [{ name: 'search', endpoint: '/api/search' }],
});

// Write to disk
import { writeFileSync } from 'fs';
writeFileSync('.well-known/agent.json', toJSON());

import { discoverAgent, discoverTools } from '@opencommerceprotocol/agent-discovery/client';

// Full discovery result
const result = await discoverAgent('https://hotels.example.com');

if (result.found) {
  console.log(result.mode);            // 'direct' | 'browser_fallback'
  console.log(result.manifest_url);    // Where the manifest was found
  console.log(result.manifest.tools);  // AgentTool[]
}

// Convenience: just get the tools
const tools = await discoverTools('https://hotels.example.com');
// → AgentTool[]

import {
  toMCPTools,      // → MCP tool definitions (Claude, Cursor)
  toOpenAITools,   // → OpenAI function calling format
  toA2ATools,      // → Google A2A tool definitions
  toA2AAgentCard,  // → Google A2A agent card
  toOpenAPISpec,   // → OpenAPI 3.0 specification
} from '@opencommerceprotocol/agent-discovery';

import { discoverAgent } from '@opencommerceprotocol/agent-discovery/client';

const { manifest } = await discoverAgent('https://hotels.example.com');

// Use with Claude / Cursor (MCP)
const mcpTools = toMCPTools(manifest);
// [{ name, description, inputSchema: { type: 'object', properties, required } }]

// Use with GPT-4o tool calling
const openaiTools = toOpenAITools(manifest);
// [{ type: 'function', function: { name, description, parameters } }]

// Generate OpenAPI spec for documentation or OpenAPI-aware agents
const spec = toOpenAPISpec(manifest);
// { openapi: '3.0.0', info, paths, components }

// Build Google A2A agent card
const card = toA2AAgentCard(manifest);

import { signRequest, verifySignature } from '@opencommerceprotocol/agent-discovery';

// Agent: sign outgoing requests
const headers = await signRequest(
  'POST',
  '/api/hotels/search',
  JSON.stringify({ location: 'Lisbon' }),
  process.env.AGENT_SECRET!,
);
// { 'X-Agent-Signature': 'v1=...', 'X-Agent-Timestamp': '...', 'X-Agent-Nonce': '...' }

// Server: verify incoming signed requests
const valid = await verifySignature(
  'POST', '/api/hotels/search',
  JSON.stringify({ location: 'Lisbon' }),
  process.env.AGENT_SECRET!,
  incomingHeaders,
  300, // max age in seconds (default: 5 minutes)
);

import { generateDomainVerificationTokens, verifyDomainOwnership } from '@opencommerceprotocol/agent-discovery';

// Registry: generate token for a domain to prove ownership
const tokens = generateDomainVerificationTokens('hotels.example.com');
// tokens.file_token  → place at /.well-known/agent-verify.txt
// tokens.dns_token   → add as DNS TXT record: ocp-site-verification=<token>

// Later: verify ownership
const verified = await verifyDomainOwnership('hotels.example.com', tokens.file_token);

import { fetchOAuth2Token } from '@opencommerceprotocol/agent-discovery';

// Fetch a client_credentials access token before calling an auth-required tool
const token = await fetchOAuth2Token({
  client_id: process.env.CLIENT_ID!,
  client_secret: process.env.CLIENT_SECRET!,
  token_url: 'https://auth.example.com/token',
  scopes: ['hotels:read', 'bookings:write'],
});

// Use in subsequent requests
const res = await fetch('https://hotels.example.com/api/hotels/book', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
  body: JSON.stringify({ hotel_id: 'h123' }),
});

# Start the registry server (port 3200 by default)
OCP_REGISTRY_PORT=3200 npx tsx packages/registry/src/index.ts

# Or import and use programmatically
import { createApp } from '@opencommerceprotocol/registry';
const { app } = createApp('./registry.db');

# Auto-fetches /.well-known/agent.json from the URL
curl -X POST https://agents.directory/v1/register \
  -H 'Content-Type: application/json' \
  -d '{ "url": "https://hotels.example.com" }'

# Response:
{
  "success": true,
  "id": "abc123",
  "message": "Site registered successfully",
  "entry": {
    "id": "abc123",
    "url": "https://hotels.example.com",
    "name": "Hotel Search API",
    "tools_count": 4,
    "verticals": ["travel"],
    "auth_type": "oauth2"
  }
}

# Text search with filters
GET /v1/search?q=restaurants+lisbon&vertical=food
GET /v1/search?vertical=commerce&ships_to=PT&payment_method=stripe
GET /v1/search?category=electronics&price_tier=mid

# Natural-language intent routing
GET /v1/route?intent=coffee+merchants+shipping+to+PT+accepting+stripe

# Response:
{
  "results": [...],
  "total": 42,
  "limit": 20,
  "offset": 0,
  "query": "restaurants lisbon"
}