Content
# 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
```bash
npm install
npm run build
```
## Usage
### Basic Usage
```bash
# Start with default settings (JSON store, port 3000)
npm start
# Or run directly
node dist/index.js
```
### Configuration Options
```bash
# 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
| Flag | Values | Description | Default |
|------|--------|-------------|---------|
| `--store` | `json`, `sqlite` | Storage backend | `json` |
| `--file` | path | Database or JSON file path | `a2a-registry.json` or `a2a-registry.db` |
| `--port` | number | HTTP server port | `3000` |
| `--help` | - | Show help message | - |
### Using PM2
```bash
# 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
```bash
GET /agents
```
#### Get Agent by Name
```bash
GET /agents/:name
```
#### Register New Agent
```bash
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
```bash
PUT /agents/:name
Content-Type: application/json
{
"url": "https://new-url.com" # Optional, re-fetches from existing URL if omitted
}
```
#### Delete Agent
```bash
DELETE /agents/:name
```
### MCP Server
The MCP server is available at `/mcp` using SSE (Server-Sent Events) transport.
#### Config example
```json
{
"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](https://a2a-protocol.org/latest/specification/#55-agentcard-object-structure) 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
```bash
npm run build
```
### Development Mode (with auto-reload)
```bash
npm run dev
```
### Clean Build
```bash
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.
