ericabouaf/a2a-registry

A2A Registry

A Model Context Protocol (MCP) server providing a unified registry for agents implementing the A2A (Agent-to-Agent) protocol. The registry exposes both a REST API and MCP tools for registering, querying, and managing agent metadata.

Features

• Dual API Access: REST API and MCP server running on a single HTTP server
• Intelligent Agent Registration: Automatically fetches AgentCards from URLs using smart routing
• Multiple Storage Backends: JSON file or SQLite database
• Concurrent Access: SSE-based MCP transport allows multiple clients simultaneously
• Full CRUD Operations: Create, read, update, and delete agents
• A2A Protocol Compliant: Uses standard AgentCard model from @a2a-js/sdk

Installation

npm install
npm run build

Usage

Basic Usage

# Start with default settings (JSON store, port 3000)
npm start

# Or run directly
node dist/index.js

Configuration Options

# Use SQLite storage
node dist/index.js --store=sqlite --file=./agents.db

# Custom port
node dist/index.js --port=4000

# Custom JSON file location
node dist/index.js --store=json --file=./my-agents.json

# Combine options
node dist/index.js --store=sqlite --file=./agents.db --port=4000

CLI Options

Using PM2

# Start with PM2
pm2 start ecosystem.config.cjs

# View logs
pm2 logs a2a-registry

# Stop
pm2 stop a2a-registry

# Restart
pm2 restart a2a-registry

API Endpoints

REST API

All REST endpoints are under /agents:

List All Agents

GET /agents

Get Agent by Name

GET /agents/:name

Register New Agent

POST /agents
Content-Type: application/json

{
  "url": "https://example.com"
}

The registry will automatically:

1. Determine the AgentCard URL using intelligent routing
2. Fetch the AgentCard from the URL
3. Validate the AgentCard structure
4. Store it using the agent's name as the primary key

URL Routing Examples:

• https://example.com → Fetches from https://example.com/.well-known/agent-card.json
• https://example.com/my-agent → Fetches from https://example.com/my-agent/.well-known/agent-card.json
• https://cdn.example.com/agent.json → Fetches directly (URL ends with .json)

Update Agent

PUT /agents/:name
Content-Type: application/json

{
  "url": "https://new-url.com"  # Optional, re-fetches from existing URL if omitted
}

Delete Agent

DELETE /agents/:name

MCP Server

The MCP server is available at /mcp using SSE (Server-Sent Events) transport.

Config example

{
  "mcpServers": {
    "a2a-registry": {
      "type": "http",
      "url": "http://localhost:3005/mcp"
    }
  }
}

Available MCP Tools

1. a2a_register_agent

   • Register a new agent by URL
   • Parameters: { url: string }

2. a2a_list_agents

   • List all registered agents
   • Parameters: none

3. a2a_get_agent

   • Get agent details by name
   • Parameters: { name: string }

4. a2a_update_agent

   • Update agent by re-fetching AgentCard
   • Parameters: { name: string, url?: string }

5. a2a_delete_agent

   • Delete agent from registry
   • Parameters: { name: string }

Architecture

┌─────────────────────────────────────────┐
│     REST API        │     MCP Server    │
│   (HTTP Routes)     │   (MCP Tools)     │
├─────────────────────┴───────────────────┤
│          AgentService                   │
│  (Business Logic & Validation)          │
├─────────────────────────────────────────┤
│          Store Interface                │
│     (Storage Abstraction)               │
├─────────────────────────────────────────┤
│   JsonFileStore  │  SqliteStore         │
│   (Implementations)                     │
└─────────────────────────────────────────┘

Key Design Principles

• Service Layer Pattern: AgentService encapsulates all business logic
• No Code Duplication: REST and MCP APIs are thin adapters calling AgentService
• Intelligent Registration: Automatic AgentCard discovery and fetching
• Pluggable Storage: Easy to add new storage backends
• Concurrent Access: Stateless SSE transport for MCP

AgentCard Structure

The registry uses the standard AgentCard model from the A2A protocol. Required fields include:

• name: Agent name (used as primary key)
• description: Agent purpose and capabilities
• url: Primary A2A endpoint URL
• version: Agent version
• capabilities: Supported A2A protocol features
• defaultInputModes: Supported input MIME types
• defaultOutputModes: Supported output MIME types
• skills: Agent's distinct capabilities

See the A2A Protocol Specification for complete details.

Development

Project Structure

a2a-registry/
├── src/
│   ├── index.ts              # Main entry point
│   ├── types/                # TypeScript type definitions
│   ├── store/                # Storage implementations
│   │   ├── JsonFileStore.ts
│   │   └── SqliteStore.ts
│   ├── services/             # Business logic
│   │   └── AgentService.ts
│   ├── api/                  # REST API
│   │   └── restApi.ts
│   ├── mcp/                  # MCP server
│   │   └── mcpServer.ts
│   └── utils/                # Utilities
│       └── validation.ts
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── ecosystem.config.cjs      # PM2 configuration

Build

npm run build

Development Mode (with auto-reload)

npm run dev

Clean Build

npm run clean
npm run build

Error Handling

The registry provides clear, actionable error messages:

• 404: Agent not found
• 409: Agent already exists (use update instead)
• 400: Invalid URL, fetch failure, or validation error
• 500: Internal server error

All errors include helpful messages to guide next steps.

License

MIT

Contributing

Contributions are welcome! Please ensure:

1. Code follows the existing architecture patterns
2. All business logic is in AgentService
3. APIs are thin adapters
4. Tests pass and build succeeds

Support

For issues or questions, please open an issue on GitHub.