Agent Talk
by phakbulut
README.md
# Agent Talk
**Agent Talk** is a powerful Model Context Protocol (MCP) server that enables autonomous AI agents (Frontend and Backend) to communicate asynchronously and autonomously, manage API contracts, and coordinate their development efforts with zero manual synchronization overhead.
## Vision
In modern AI-driven development, multiple autonomous agents need to work together seamlessly:
- **Backend Agent** implements APIs and publishes route contracts
- **Frontend Agent** discovers available endpoints and integrates them
- **Integration Issues** are reported and tracked bidirectionally
- **Context Efficiency** is maintained through intelligent grouping
Agent Talk solves this coordination problem by providing:
1. **Contract-First API Management** - Backend agents register their routes with OpenAPI 3.0 compatible schemas before implementation
2. **Autonomous Discovery** - Frontend agents discover available APIs without human intervention
3. **Issue Tracking** - Bidirectional feedback when integration problems occur
4. **Context Management** - Routes grouped by domain to reduce LLM context usage in large projects
5. **Asynchronous Coordination** - Agents update each other's status without blocking operations
## Features
Route Contract Management
- Register and update API routes with OpenAPI 3.0 schemas
- Group routes by domain/service for efficient context management
- Track route status: draft → pending → active → deprecated
- Search and list routes with powerful filtering
Issue Tracking & Feedback
- Frontend agents report integration issues with detailed context
- Backend agents monitor open issues for their routes
- Mark issues as resolved with audit trail
- Track issues by route, reporter, or status
Asynchronous Agent Communication
- No blocking operations - agents operate independently
- Pull-based architecture for efficient resource usage
- Pagination support for large result sets
- Rich metadata for informed decision-making
Enterprise-Grade Architecture
- Modular design: repositories -> services -> tools
- Type-safe with TypeScript
- Comprehensive error handling and validation
- SQLite for portability and zero dependencies
## Quick Start
### Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/agent-talk.git
cd agent-talk
# Install dependencies
npm install
# Build the project
npm run build
# Start the server
npm start
```
### Environment Setup
```bash
# Copy the example environment file
cp .env.example .env
# Customize if needed (optional)
# AGENT_TALK_DB_PATH=./data/agent_talk.db
```
### Development
```bash
# Watch for changes and rebuild
npm run watch
# Run in development mode
npm run dev
# Format code
npm run format
# Lint code
npm run lint
```
## Architecture
### Single Project Architecture
```
Agent Talk MCP Server
├── Tools (MCP Interface)
│ ├── Route Tools (register, list, search)
│ └── Issue Tools (report, track, resolve)
├── Services (Business Logic)
│ ├── RouteService (contract management)
│ └── IssueService (issue tracking)
├── Repositories (Data Access)
│ ├── RouteRepository (route persistence)
│ └── IssueRepository (issue persistence)
├── Database (SQLite)
│ └── Tables: routes, issues
└── Utilities (Validation, Error Handling)
├── Validation (OpenAPI schema validation)
└── Error Handling (custom error types)
```
### Multi-Project Architecture (Recommended)
When working on multiple full-stack projects simultaneously, use a centralized Agent Talk server:
```
Central MCP Server
┌──────────────────────────────────────┐
│ Agent Talk MCP Server (Central) │
│ npm start (Terminal 1) │
│ Listens for all agents │
│ data/myapp-shared.db │
└──────────────────────────────────────┘
│
┌────┼────┬──────────┬──────────┐
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
Backend Frontend Mobile Desktop Other
Project Project App App Projects
(Node.js)(React) (RN) (Electron)
```
**Project Directory Structure:**
```
myapp/
├── myapp-agent-talk/ (Central MCP Server)
│ ├── src/
│ ├── package.json
│ ├── .env (DB: ./data/myapp-shared.db)
│ ├── data/
│ │ └── myapp-shared.db (All projects use this)
│ └── npm start
│
├── backend/ (Node.js/Express API)
│ ├── src/
│ ├── .env (AGENT_TALK_DB_PATH=../myapp-agent-talk/data/myapp-shared.db)
│ └── npm start
│
├── frontend/ (React/Vue UI)
│ ├── src/
│ ├── .env (AGENT_TALK_DB_PATH=../myapp-agent-talk/data/myapp-shared.db)
│ └── npm start
│
└── mobile/ (React Native/Flutter)
├── src/
├── .env (AGENT_TALK_DB_PATH=../myapp-agent-talk/data/myapp-shared.db)
└── npm start
```
## Available Tools
### Route Management
#### `register_or_update_route`
Backend agent registers a new API route or updates an existing one.
```json
{
"group_name": "users",
"path": "/api/v1/users",
"method": "POST",
"description": "Create a new user",
"request_schema": {
"type": "object",
"properties": {
"name": { "type": "string" },
"email": { "type": "string", "format": "email" }
},
"required": ["name", "email"]
},
"response_schema": {
"201": {
"type": "object",
"properties": {
"id": { "type": "string", "format": "uuid" },
"name": { "type": "string" },
"email": { "type": "string" }
}
},
"400": {
"type": "object",
"properties": {
"error": { "type": "string" }
}
}
},
"status": "active"
}
```
#### `get_route_contract`
Frontend agent retrieves the complete contract for a specific endpoint.
```json
{
"path": "/api/v1/users",
"method": "POST"
}
```
#### `list_groups`
Frontend agent discovers all available route groups (for context efficiency).
```json
{}
```
Returns:
```json
{
"groups": ["users", "auth", "products"],
"total_groups": 3,
"total_routes": 45,
"routes_by_status": {
"active": 40,
"draft": 3,
"pending_implementation": 2
}
}
```
#### `list_routes_by_group`
Frontend agent fetches routes within a specific group.
```json
{
"group_name": "users",
"limit": 50,
"offset": 0
}
```
#### `search_routes`
Search routes by path or description.
```json
{
"query": "user",
"limit": 10
}
```
### Issue Management
#### `report_route_issue`
Frontend agent reports a problem with a route.
```json
{
"route_id": "550e8400-e29b-41d4-a716-446655440000",
"reporter": "frontend_agent",
"issue_description": "The POST /api/v1/users endpoint returns 400 instead of 201 when creating a user with valid data. Expected status 201, got 400. The response_schema specifies it should return user ID."
}
```
#### `list_route_issues`
Backend agent retrieves issues for their routes.
```json
{
"route_id": "550e8400-e29b-41d4-a716-446655440000",
"status_filter": "open",
"limit": 100
}
```
#### `list_open_issues`
Backend agent gets a dashboard view of all problems across the system.
```json
{
"limit": 50,
"offset": 0
}
```
#### `resolve_route_issue`
Backend agent marks an issue as resolved after fixing it.
```json
{
"issue_id": "550e8400-e29b-41d4-a716-446655440001"
}
```
#### `reopen_route_issue`
Reopen a resolved issue if the problem resurfaces.
```json
{
"issue_id": "550e8400-e29b-41d4-a716-446655440001"
}
```
#### `list_issues_by_group`
Get all issues for a specific route group.
```json
{
"group_name": "users",
"limit": 100
}
```
#### `get_issue_statistics`
System-wide issue dashboard metrics.
```json
{}
```
Returns:
```json
{
"total_issues": 15,
"open_issues": 3,
"resolved_issues": 12,
"issues_by_reporter": {
"frontend_agent": 8,
"backend_agent": 2
}
}
```
## Data Models
### Route Contract
```typescript
interface RouteContract {
id: string; // UUID
group_name: string; // "users", "auth", etc.
path: string; // "/api/v1/users"
method: string; // "GET", "POST", etc.
status: "draft" | "pending_implementation" | "active" | "deprecated";
description: string; // What this endpoint does
request_schema: OpenAPISchema; // Request validation schema
response_schema: Record<number, OpenAPISchema>; // Status code → schema
created_at: number; // Unix timestamp
updated_at: number; // Unix timestamp
}
```
### Route Issue
```typescript
interface RouteIssue {
id: string; // UUID
route_id: string; // Foreign key to route
reporter: string; // "frontend_agent", etc.
issue_description: string; // Detailed problem description
status: "open" | "resolved";
created_at: number; // Unix timestamp
updated_at: number; // Unix timestamp
}
```
## Multi-Project Setup Guide
When working on multiple full-stack projects with shared backend, use a centralized Agent Talk instance.
### Setup Steps
**Step 1: Create central Agent Talk instance**
```bash
mkdir myapp
cd myapp
git clone https://github.com/yourusername/agent-talk.git myapp-agent-talk
cd myapp-agent-talk
npm install
cp .env.example .env
```
**Step 2: Configure central Agent Talk**
```bash
# myapp/myapp-agent-talk/.env
AGENT_TALK_DB_PATH=./data/myapp-shared.db
NODE_ENV=production
```
**Step 3: Start central Agent Talk (keep running)**
```bash
cd myapp/myapp-agent-talk
npm start
# Terminal stays open, listens for agents from all projects
```
**Step 4: Configure Backend Project**
```bash
# myapp/backend/.env
AGENT_TALK_DB_PATH=../myapp-agent-talk/data/myapp-shared.db
BACKEND_PORT=5000
```
```bash
cd myapp/backend
npm start
# Backend Agent registers routes to central Agent Talk
```
**Step 5: Configure Frontend Project**
```bash
# myapp/frontend/.env
AGENT_TALK_DB_PATH=../myapp-agent-talk/data/myapp-shared.db
FRONTEND_PORT=3000
```
```bash
cd myapp/frontend
npm start
# Frontend Agent discovers and uses Backend routes
```
**Step 6: Configure Mobile Project**
```bash
# myapp/mobile/.env
AGENT_TALK_DB_PATH=../myapp-agent-talk/data/myapp-shared.db
MOBILE_PORT=3001
```
```bash
cd myapp/mobile
npm start
# Mobile Agent uses same routes from central Agent Talk
```
### Multi-Project Workflow Example
**Monday - Backend Development**
```bash
# Terminal 1: Central Agent Talk
cd myapp/myapp-agent-talk && npm start
# Terminal 2: Backend
cd myapp/backend && npm start
# Backend Agent registers: POST /api/users, GET /api/users/{id}, etc.
# Routes saved to: myapp-shared.db
```
**Tuesday - Frontend Development**
```bash
# Terminal 1: Central Agent Talk (still running from Monday)
# Terminal 3: Frontend
cd myapp/frontend && npm start
# Frontend Agent discovers Monday's Backend routes
# Retrieves POST /api/users contract with full schema
# Implements form to consume the API
# If problems occur: reports issue via report_route_issue
```
**Wednesday - Mobile Development**
```bash
# Terminal 1: Central Agent Talk (still running)
# Terminal 4: Mobile
cd myapp/mobile && npm start
# Mobile Agent accesses same Backend routes
# Uses identical schema as Frontend
# Consistency guaranteed by central Agent Talk
```
**Thursday - Bug Fixes**
```bash
# Frontend Agent discovered: POST /api/users returns 500 instead of 201
# Reports issue to central Agent Talk
# Backend Agent sees open issue via list_open_issues
# Backend Agent fixes the bug
# Backend Agent marks issue as resolved
# Frontend Agent automatically aware of fix
```
### Benefits
- Single source of truth (myapp-shared.db)
- Routes never mix between projects
- All agents coordinate through one server
- No data duplication
- Easy to add more projects
- Perfect for microservices
### Alternative: Isolated Databases
If projects are completely independent, use separate databases:
```bash
# backend/.env
AGENT_TALK_DB_PATH=../myapp-agent-talk/data/backend-only.db
# frontend/.env
AGENT_TALK_DB_PATH=../myapp-agent-talk/data/frontend-only.db
# mobile/.env
AGENT_TALK_DB_PATH=../myapp-agent-talk/data/mobile-only.db
```
Each project gets its own database - complete isolation but no coordination.
## Use Cases
### Backend Agent Workflow
1. **Register New Endpoint**
```
Call: register_or_update_route
Input: {path, method, request_schema, response_schema, status: "draft"}
Output: Route ID, confirmation
```
2. **Monitor Integration Issues**
```
Call: list_route_issues
Input: {route_id, status_filter: "open"}
Output: Open issues for this route
```
3. **Update Route Status**
```
Call: register_or_update_route (with same path/method)
Input: {status: "active"}
Output: Updated route
```
4. **Resolve Reported Issues**
```
Call: resolve_route_issue
Input: {issue_id}
Output: Confirmation
```
### Frontend Agent Workflow
1. **Discover Available Groups**
```
Call: list_groups
Output: ["users", "auth", "products", ...]
```
2. **Explore Routes in a Group**
```
Call: list_routes_by_group
Input: {group_name: "users"}
Output: Summary of routes in this group
```
3. **Get Full Contract**
```
Call: get_route_contract
Input: {path: "/api/v1/users", method: "POST"}
Output: Complete request/response schemas
```
4. **Report Integration Issue**
```
Call: report_route_issue
Input: {route_id, reporter, issue_description}
Output: Issue ID, confirmation
```
## Error Handling
Agent Talk provides detailed error messages to help agents understand what went wrong:
```json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "group_name must contain only alphanumeric characters, hyphens, and underscores",
"statusCode": 400,
"details": {
"field": "group_name",
"requirement": "alphanumeric, hyphens, underscores"
}
}
}
```
Common error codes:
- `VALIDATION_ERROR` - Input validation failed
- `SCHEMA_VALIDATION_ERROR` - OpenAPI schema is malformed
- `NOT_FOUND` - Resource doesn't exist
- `CONFLICT` - Operation conflicts with existing state
- `DATABASE_ERROR` - Database operation failed
- `TOOL_NOT_FOUND` - Requested tool doesn't exist
## Database
Agent Talk uses SQLite for maximum portability:
- **Location**: `./data/agent_talk.db` (configurable via `AGENT_TALK_DB_PATH`)
- **Schema**: Auto-created on first run
- **Indexes**: Optimized for common queries
- **Foreign Keys**: Enabled for referential integrity
### Database Tables
```sql
-- Routes table
CREATE TABLE routes (
id TEXT PRIMARY KEY,
group_name TEXT NOT NULL,
path TEXT NOT NULL,
method TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'draft',
description TEXT NOT NULL,
request_schema TEXT NOT NULL, -- JSON
response_schema TEXT NOT NULL, -- JSON
created_at INTEGER NOT NULL,
updated_at INTEGER NOT NULL,
UNIQUE(group_name, path, method)
);
-- Issues table
CREATE TABLE issues (
id TEXT PRIMARY KEY,
route_id TEXT NOT NULL,
reporter TEXT NOT NULL,
issue_description TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'open',
created_at INTEGER NOT NULL,
updated_at INTEGER NOT NULL,
FOREIGN KEY (route_id) REFERENCES routes(id) ON DELETE CASCADE
);
```
## Performance Considerations
- **Pagination**: All list operations support pagination with limit/offset
- **Indexing**: Optimized indexes on common filter fields
- **Search**: Full-text search on path and description
- **Grouping**: Routes grouped by domain to reduce context in large projects
- **Status Tracking**: Efficient filtering by status for workflow management
## Testing
While Agent Talk is production-ready, you can extend it with tests:
```bash
# Run existing tests
npm test
# Add your own tests in src/**/*.test.ts
```
## Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## Project Structure
```
agent-talk/
├── src/
│ ├── db/ # Database initialization
│ │ └── database.ts
│ ├── repositories/ # Data access layer
│ │ ├── routeRepository.ts
│ │ └── issueRepository.ts
│ ├── services/ # Business logic
│ │ ├── routeService.ts
│ │ └── issueService.ts
│ ├── tools/ # MCP tool definitions
│ │ ├── routeTools.ts
│ │ └── issueTools.ts
│ ├── types/ # TypeScript interfaces
│ │ └── index.ts
│ ├── utils/ # Utilities
│ │ ├── errors.ts # Custom error classes
│ │ └── validation.ts # Input validation
│ └── index.ts # MCP server entry point
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
├── README.md
└── CONTRIBUTING.md
```
## License
MIT License - see LICENSE file for details
## Support
- [Documentation](https://github.com/yourusername/agent-talk/wiki)
- [Issue Tracker](https://github.com/yourusername/agent-talk/issues)
- [Discussions](https://github.com/yourusername/agent-talk/discussions)
## Acknowledgments
Built with:
- [Model Context Protocol](https://modelcontextprotocol.io/) - Agent communication framework
- [TypeScript](https://www.typescriptlang.org/) - Type safety
- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) - High-performance SQLite
- [OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.3) - Contract specification standard
---
**Agent Talk** - Empowering autonomous agents to build better APIs together.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues