From dd098a5c84fd2565ca6f7512c1fa2785103ab035 Mon Sep 17 00:00:00 2001 From: anthonyrawlins Date: Sun, 10 Aug 2025 11:50:26 +1000 Subject: [PATCH] Add comprehensive documentation for BZZZ MCP Server MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Complete API reference with all interfaces and examples - Detailed deployment guide for development and production - Main README with architecture overview and usage instructions πŸ€– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- mcp-server/BZZZ-MCP-README.md | 552 ++++++++++++++++++++++++++ mcp-server/docs/API_REFERENCE.md | 609 +++++++++++++++++++++++++++++ mcp-server/docs/DEPLOYMENT.md | 640 +++++++++++++++++++++++++++++++ 3 files changed, 1801 insertions(+) create mode 100644 mcp-server/BZZZ-MCP-README.md create mode 100644 mcp-server/docs/API_REFERENCE.md create mode 100644 mcp-server/docs/DEPLOYMENT.md diff --git a/mcp-server/BZZZ-MCP-README.md b/mcp-server/BZZZ-MCP-README.md new file mode 100644 index 00000000..ffa67a06 --- /dev/null +++ b/mcp-server/BZZZ-MCP-README.md @@ -0,0 +1,552 @@ +# BZZZ MCP Server + +A sophisticated Model Context Protocol (MCP) server that enables GPT-5 agents to participate in the BZZZ P2P network for distributed AI coordination and collaboration. + +## Overview + +The BZZZ MCP Server bridges the gap between OpenAI's GPT-5 and the BZZZ distributed coordination system, allowing AI agents to: + +- **Announce capabilities** and join the P2P network +- **Discover and communicate** with other agents using semantic addressing +- **Coordinate complex tasks** through threaded conversations +- **Escalate decisions** to human operators when needed +- **Track costs** and manage OpenAI API usage +- **Maintain performance metrics** and agent health monitoring + +## Architecture + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ GPT-5 Agent │◄──►│ BZZZ MCP Server │◄──►│ BZZZ Go Service β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ + β–Ό β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Cost Trackerβ”‚ β”‚ P2P Network β”‚ + β”‚ & Logging β”‚ β”‚ (libp2p) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Core Components + +| Component | Purpose | Features | +|-----------|---------|----------| +| **Agent Manager** | Agent lifecycle & task coordination | Performance tracking, task queuing, capability matching | +| **Conversation Manager** | Multi-threaded discussions | Auto-escalation, thread summarization, participant management | +| **P2P Connector** | BZZZ network integration | HTTP/WebSocket client, semantic addressing, network discovery | +| **OpenAI Integration** | GPT-5 API wrapper | Streaming, cost tracking, model management, prompt engineering | +| **Cost Tracker** | Usage monitoring | Daily/monthly limits, model pricing, usage analytics | +| **Logger** | Structured logging | Winston-based, multi-transport, component-specific | + +## Quick Start + +### Prerequisites + +- Node.js 18+ +- OpenAI API key with GPT-5 access +- BZZZ Go service running on `localhost:8080` + +### Installation + +```bash +cd /path/to/BZZZ/mcp-server +npm install +npm run build +``` + +### Configuration + +Create your OpenAI API key file: +```bash +echo "your-openai-api-key-here" > ~/chorus/business/secrets/openai-api-key-for-bzzz.txt +``` + +### Running the Server + +```bash +# Development mode +npm run dev + +# Production mode +npm start + +# Run integration test +node test-integration.js +``` + +## Configuration + +### Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `OPENAI_MODEL` | `gpt-5` | OpenAI model to use | +| `OPENAI_MAX_TOKENS` | `4000` | Maximum tokens per request | +| `OPENAI_TEMPERATURE` | `0.7` | Model temperature | +| `BZZZ_NODE_URL` | `http://localhost:8080` | BZZZ Go service URL | +| `BZZZ_NETWORK_ID` | `bzzz-local` | Network identifier | +| `DAILY_COST_LIMIT` | `100.0` | Daily spending limit (USD) | +| `MONTHLY_COST_LIMIT` | `1000.0` | Monthly spending limit (USD) | +| `MAX_ACTIVE_THREADS` | `10` | Maximum concurrent threads | +| `LOG_LEVEL` | `info` | Logging level | + +### Advanced Configuration + +The server automatically configures escalation rules and agent role templates. See `src/config/config.ts` for detailed options. + +## MCP Tools Reference + +The BZZZ MCP Server provides 6 core tools for agent interaction: + +### 1. bzzz_announce + +Announce agent presence and capabilities on the BZZZ network. + +**Input Schema:** +```json +{ + "agent_id": "string (required)", + "role": "string (required)", + "capabilities": ["string"], + "specialization": "string", + "max_tasks": "number (default: 3)" +} +``` + +**Example:** +```json +{ + "agent_id": "architect-001", + "role": "architect", + "capabilities": ["system_design", "code_review", "performance_analysis"], + "specialization": "distributed_systems", + "max_tasks": 5 +} +``` + +### 2. bzzz_lookup + +Discover agents and resources using semantic addressing. + +**Input Schema:** +```json +{ + "semantic_address": "string (required)", + "filter_criteria": { + "expertise": ["string"], + "availability": "boolean", + "performance_threshold": "number" + } +} +``` + +**Address Format:** `bzzz://agent:role@project:task/path` + +**Example:** +```json +{ + "semantic_address": "bzzz://*:architect@myproject:api_design", + "filter_criteria": { + "expertise": ["REST", "GraphQL"], + "availability": true, + "performance_threshold": 0.8 + } +} +``` + +### 3. bzzz_get + +Retrieve content from BZZZ semantic addresses. + +**Input Schema:** +```json +{ + "address": "string (required)", + "include_metadata": "boolean (default: true)", + "max_history": "number (default: 10)" +} +``` + +### 4. bzzz_post + +Post events or messages to BZZZ addresses. + +**Input Schema:** +```json +{ + "target_address": "string (required)", + "message_type": "string (required)", + "content": "object (required)", + "priority": "string (low|medium|high|urgent, default: medium)", + "thread_id": "string (optional)" +} +``` + +### 5. bzzz_thread + +Manage threaded conversations between agents. + +**Input Schema:** +```json +{ + "action": "string (create|join|leave|list|summarize, required)", + "thread_id": "string (required for most actions)", + "participants": ["string"] (required for create), + "topic": "string (required for create)" +} +``` + +**Thread Management:** +- **Create**: Start new discussion thread +- **Join**: Add agent to existing thread +- **Leave**: Remove agent from thread +- **List**: Get threads for current agent +- **Summarize**: Generate thread summary + +### 6. bzzz_subscribe + +Subscribe to real-time events from the BZZZ network. + +**Input Schema:** +```json +{ + "event_types": ["string"] (required), + "filter_address": "string (optional)", + "callback_webhook": "string (optional)" +} +``` + +## Agent Roles & Capabilities + +The MCP server comes with predefined agent role templates: + +### Architect Agent +- **Specialization**: System design and architecture +- **Capabilities**: `system_design`, `architecture_review`, `technology_selection`, `scalability_analysis` +- **Use Cases**: Technical guidance, design validation, technology decisions + +### Code Reviewer Agent +- **Specialization**: Code quality and security +- **Capabilities**: `code_review`, `security_analysis`, `performance_optimization`, `best_practices_enforcement` +- **Use Cases**: Pull request reviews, security audits, code quality checks + +### Documentation Agent +- **Specialization**: Technical writing +- **Capabilities**: `technical_writing`, `api_documentation`, `user_guides`, `knowledge_synthesis` +- **Use Cases**: API docs, user manuals, knowledge base creation + +## Conversation Management + +### Thread Lifecycle + +```mermaid +graph TD + A[Create Thread] --> B[Active] + B --> C[Add Participants] + B --> D[Exchange Messages] + D --> E{Escalation Triggered?} + E -->|Yes| F[Escalated] + E -->|No| D + F --> G[Human Intervention] + G --> H[Resolved] + B --> I[Paused] + I --> B + B --> J[Completed] +``` + +### Escalation Rules + +The system automatically escalates threads based on: + +1. **Long Running Threads**: > 2 hours with no progress +2. **Consensus Failure**: > 3 disagreements in discussions +3. **Error Rate**: High failure rate in thread messages + +### Escalation Actions + +- **Notify Human**: Alert project managers or stakeholders +- **Request Expert**: Bring in specialized agents +- **Escalate to Architect**: Involve senior technical decision makers +- **Create Decision Thread**: Start focused decision-making process + +## Cost Management + +### Pricing (GPT-5 Estimates) +- **Prompt Tokens**: $0.05 per 1K tokens +- **Completion Tokens**: $0.15 per 1K tokens + +### Cost Tracking Features +- Real-time usage monitoring +- Daily and monthly spending limits +- Automatic warnings at 80% threshold +- Per-model cost breakdown +- Usage analytics and reporting + +### Cost Optimization Tips +1. Use appropriate temperature settings (0.3 for consistent tasks, 0.7 for creative work) +2. Set reasonable token limits for different task types +3. Monitor high-usage agents and optimize prompts +4. Use streaming for real-time applications + +## Integration with BZZZ Go Service + +### Required BZZZ API Endpoints + +The MCP server expects these endpoints from the BZZZ Go service: + +| Endpoint | Method | Purpose | +|----------|--------|---------| +| `/api/v1/health` | GET | Health check | +| `/api/v1/pubsub/publish` | POST | Publish messages | +| `/api/v1/p2p/send` | POST | Direct messaging | +| `/api/v1/network/query` | POST | Network queries | +| `/api/v1/network/status` | GET | Network status | +| `/api/v1/projects/{id}/data` | GET | Project data | +| `/api/v1/ws` | WebSocket | Real-time events | + +### Message Format + +```json +{ + "type": "message_type", + "content": {...}, + "sender": "node_id", + "timestamp": "2025-08-09T16:22:20Z", + "messageId": "msg-unique-id", + "networkId": "bzzz-local" +} +``` + +## Development + +### Project Structure + +``` +mcp-server/ +β”œβ”€β”€ src/ +β”‚ β”œβ”€β”€ agents/ # Agent management +β”‚ β”œβ”€β”€ ai/ # OpenAI integration +β”‚ β”œβ”€β”€ config/ # Configuration +β”‚ β”œβ”€β”€ conversations/ # Thread management +β”‚ β”œβ”€β”€ p2p/ # BZZZ network client +β”‚ β”œβ”€β”€ tools/ # MCP protocol tools +β”‚ β”œβ”€β”€ utils/ # Utilities (logging, cost tracking) +β”‚ └── index.ts # Main server +β”œβ”€β”€ dist/ # Compiled JavaScript +β”œβ”€β”€ test-integration.js # Integration tests +β”œβ”€β”€ package.json +β”œβ”€β”€ tsconfig.json +└── README.md +``` + +### Building and Testing + +```bash +# Install dependencies +npm install + +# Build TypeScript +npm run build + +# Run development server +npm run dev + +# Run linting +npm run lint + +# Format code +npm run format + +# Run integration test +node test-integration.js +``` + +### Adding New Agent Types + +1. **Define Role Configuration** in `src/config/config.ts`: +```typescript +{ + role: 'new_role', + specialization: 'domain_expertise', + capabilities: ['capability1', 'capability2'], + systemPrompt: 'Your role-specific prompt...', + interactionPatterns: { + 'other_role': 'interaction_pattern' + } +} +``` + +2. **Add Task Types** in `src/agents/agent-manager.ts`: +```typescript +case 'new_task_type': + result = await this.executeNewTaskType(agent, task, taskData); + break; +``` + +3. **Test Integration** with existing agents and workflows. + +## Monitoring and Observability + +### Logging + +The server provides structured logging with multiple levels: + +```typescript +// Component-specific logging +const logger = new Logger('ComponentName'); +logger.info('Operation completed', { metadata }); +logger.error('Operation failed', { error: error.message }); +``` + +### Metrics and Health + +- **Agent Performance**: Success rates, response times, task completion +- **Thread Health**: Active threads, escalation rates, resolution times +- **Network Status**: Connection health, message throughput, peer count +- **Cost Analytics**: Spending trends, model usage, token consumption + +### Debugging + +Enable debug logging: +```bash +export LOG_LEVEL=debug +npm run dev +``` + +View detailed component interactions, P2P network events, and OpenAI API calls. + +## Troubleshooting + +### Common Issues + +**1. "OpenAI API key not found"** +- Ensure API key file exists: `~/chorus/business/secrets/openai-api-key-for-bzzz.txt` +- Check file permissions and content + +**2. "Failed to connect to BZZZ service"** +- Verify BZZZ Go service is running on `localhost:8080` +- Check network connectivity and firewall settings +- Verify API endpoint availability + +**3. "Thread escalation not working"** +- Check escalation rule configuration +- Verify human notification endpoints +- Review escalation logs for rule triggers + +**4. "High API costs"** +- Review daily/monthly limits in configuration +- Monitor token usage per agent type +- Optimize system prompts and temperature settings +- Use streaming for long-running conversations + +### Performance Optimization + +1. **Agent Management** + - Limit concurrent tasks per agent + - Use performance thresholds for agent selection + - Implement agent health monitoring + +2. **Conversation Threading** + - Set appropriate thread timeouts + - Use thread summarization for long discussions + - Implement thread archival policies + +3. **Network Efficiency** + - Use WebSocket connections for real-time events + - Implement message batching for bulk operations + - Cache frequently accessed network data + +## Security Considerations + +### API Key Management +- Store OpenAI keys securely outside of code repository +- Use environment-specific key files +- Implement key rotation procedures + +### Network Security +- Use HTTPS/WSS for all external connections +- Validate all incoming P2P messages +- Implement rate limiting for API calls + +### Agent Isolation +- Sandbox agent executions where possible +- Validate agent capabilities and permissions +- Monitor for unusual agent behavior patterns + +## Deployment + +### Production Checklist + +- [ ] OpenAI API key configured and tested +- [ ] BZZZ Go service running and accessible +- [ ] Cost limits set appropriately for environment +- [ ] Logging configured for production monitoring +- [ ] WebSocket connections tested for stability +- [ ] Escalation rules configured for team workflow +- [ ] Performance metrics and alerting set up + +### Docker Deployment + +```dockerfile +FROM node:18-alpine +WORKDIR /app +COPY package*.json ./ +RUN npm ci --only=production +COPY dist/ ./dist/ +EXPOSE 3000 +CMD ["node", "dist/index.js"] +``` + +### Systemd Service + +```ini +[Unit] +Description=BZZZ MCP Server +After=network.target + +[Service] +Type=simple +User=bzzz +WorkingDirectory=/opt/bzzz-mcp-server +ExecStart=/usr/bin/node dist/index.js +Restart=always +Environment=NODE_ENV=production + +[Install] +WantedBy=multi-user.target +``` + +## Contributing + +### Development Workflow + +1. Fork the repository +2. Create a feature branch: `git checkout -b feature/new-feature` +3. Make changes following TypeScript and ESLint rules +4. Add tests for new functionality +5. Update documentation as needed +6. Submit a pull request + +### Code Style + +- Use TypeScript strict mode +- Follow existing naming conventions +- Add JSDoc comments for public APIs +- Include comprehensive error handling +- Write meaningful commit messages + +## License + +This project follows the same license as the BZZZ project. + +## Support + +For issues and questions: +- Review this documentation and troubleshooting section +- Check the integration test for basic connectivity +- Examine logs for detailed error information +- Consult the BZZZ project documentation for P2P network issues + +--- + +**BZZZ MCP Server v1.0.0** - Enabling GPT-5 agents to collaborate in distributed P2P networks. \ No newline at end of file diff --git a/mcp-server/docs/API_REFERENCE.md b/mcp-server/docs/API_REFERENCE.md new file mode 100644 index 00000000..a188207b --- /dev/null +++ b/mcp-server/docs/API_REFERENCE.md @@ -0,0 +1,609 @@ +# BZZZ MCP Server API Reference + +Complete API reference for all components and interfaces in the BZZZ MCP Server. + +## Table of Contents + +- [MCP Tools](#mcp-tools) +- [Agent Management](#agent-management) +- [Conversation Management](#conversation-management) +- [P2P Connector](#p2p-connector) +- [OpenAI Integration](#openai-integration) +- [Cost Tracker](#cost-tracker) +- [Configuration](#configuration) +- [Error Handling](#error-handling) + +## MCP Tools + +### bzzz_announce + +Announce agent presence and capabilities on the BZZZ network. + +**Parameters:** +- `agent_id` (string, required): Unique identifier for the agent +- `role` (string, required): Agent's primary role (architect, reviewer, documentation, etc.) +- `capabilities` (string[], optional): List of agent capabilities +- `specialization` (string, optional): Agent's area of expertise +- `max_tasks` (number, optional, default: 3): Maximum concurrent tasks + +**Response:** +```json +{ + "success": true, + "message": "Agent architect-001 (architect) announced to BZZZ network", + "agent": { + "id": "architect-001", + "role": "architect", + "capabilities": ["system_design", "architecture_review"], + "specialization": "distributed_systems", + "status": "idle" + } +} +``` + +**Errors:** +- Missing required fields (`agent_id`, `role`) +- Agent ID already exists +- Network communication failure + +### bzzz_lookup + +Discover agents and resources using semantic addressing. + +**Parameters:** +- `semantic_address` (string, required): BZZZ semantic address in format `bzzz://agent:role@project:task/path` +- `filter_criteria` (object, optional): Additional filtering options + - `expertise` (string[]): Required expertise areas + - `availability` (boolean): Only available agents + - `performance_threshold` (number): Minimum performance score (0-1) + +**Address Components:** +- `agent`: Specific agent ID or `*` for any +- `role`: Agent role or `*` for any +- `project`: Project identifier or `*` for any +- `task`: Task identifier or `*` for any +- `path`: Optional resource path + +**Response:** +```json +{ + "success": true, + "address": "bzzz://*:architect@myproject:api_design", + "parsed_address": { + "agent": null, + "role": "architect", + "project": "myproject", + "task": "api_design", + "path": null, + "raw": "bzzz://*:architect@myproject:api_design" + }, + "matches": [ + { + "id": "architect-001", + "role": "architect", + "capabilities": ["system_design", "api_design"], + "available": true, + "performance": 0.95, + "score": 85 + } + ], + "count": 1, + "query_time": "2025-08-09T16:22:20Z" +} +``` + +### bzzz_get + +Retrieve content from BZZZ semantic addresses. + +**Parameters:** +- `address` (string, required): BZZZ semantic address +- `include_metadata` (boolean, optional, default: true): Include resource metadata +- `max_history` (number, optional, default: 10): Maximum historical entries + +**Response:** +```json +{ + "success": true, + "address": "bzzz://architect-001:architect@myproject:api_design", + "content": { + "agent_info": { + "id": "architect-001", + "role": "architect", + "status": "idle", + "performance": 0.95 + }, + "recent_activity": [...], + "current_tasks": [...] + }, + "metadata": { + "last_updated": "2025-08-09T16:22:20Z", + "content_type": "agent_data", + "version": "1.0" + }, + "retrieved_at": "2025-08-09T16:22:20Z" +} +``` + +### bzzz_post + +Post events or messages to BZZZ addresses. + +**Parameters:** +- `target_address` (string, required): Target BZZZ address +- `message_type` (string, required): Type of message being sent +- `content` (object, required): Message content +- `priority` (string, optional, default: "medium"): Message priority (low, medium, high, urgent) +- `thread_id` (string, optional): Conversation thread ID + +**Response:** +```json +{ + "success": true, + "message_id": "msg-1691601740123-abc123def", + "target_address": "bzzz://reviewer-001:reviewer@myproject:code_review", + "message_type": "review_request", + "delivery_results": { + "delivered": true, + "recipients": ["reviewer-001"], + "delivery_time": 145 + }, + "posted_at": "2025-08-09T16:22:20Z" +} +``` + +### bzzz_thread + +Manage threaded conversations between agents. + +**Parameters:** +- `action` (string, required): Action to perform + - `create`: Start new thread + - `join`: Join existing thread + - `leave`: Leave thread + - `list`: List threads for agent + - `summarize`: Generate thread summary +- `thread_id` (string, conditional): Required for join, leave, summarize actions +- `participants` (string[], conditional): Required for create action +- `topic` (string, conditional): Required for create action + +**Create Thread Response:** +```json +{ + "success": true, + "action": "create", + "thread_id": "thread-1691601740123-xyz789", + "result": { + "id": "thread-1691601740123-xyz789", + "topic": "API Design Review", + "participants": ["architect-001", "reviewer-001"], + "creator": "architect-001", + "status": "active", + "created_at": "2025-08-09T16:22:20Z" + }, + "timestamp": "2025-08-09T16:22:20Z" +} +``` + +**List Threads Response:** +```json +{ + "success": true, + "action": "list", + "result": [ + { + "id": "thread-1691601740123-xyz789", + "topic": "API Design Review", + "participants": ["architect-001", "reviewer-001"], + "status": "active", + "last_activity": "2025-08-09T16:20:15Z", + "message_count": 5 + } + ], + "timestamp": "2025-08-09T16:22:20Z" +} +``` + +### bzzz_subscribe + +Subscribe to real-time events from the BZZZ network. + +**Parameters:** +- `event_types` (string[], required): Types of events to subscribe to +- `filter_address` (string, optional): Address pattern to filter events +- `callback_webhook` (string, optional): Webhook URL for notifications + +**Event Types:** +- `agent_announcement`: Agent joins/leaves network +- `task_assignment`: Tasks assigned to agents +- `thread_created`: New conversation threads +- `thread_escalated`: Thread escalations +- `network_status`: Network status changes + +**Response:** +```json +{ + "success": true, + "subscription_id": "sub-1691601740123-def456", + "event_types": ["agent_announcement", "task_assignment"], + "filter_address": "bzzz://*:architect@*", + "subscribed_at": "2025-08-09T16:22:20Z", + "status": "active" +} +``` + +## Agent Management + +### Agent Interface + +```typescript +interface Agent { + id: string; // Unique agent identifier + role: string; // Agent role (architect, reviewer, etc.) + capabilities: string[]; // List of capabilities + specialization: string; // Area of expertise + maxTasks: number; // Maximum concurrent tasks + currentTasks: AgentTask[]; // Currently assigned tasks + status: 'idle' | 'busy' | 'offline' | 'error'; + performance: number; // Performance score (0-1) + available: boolean; // Availability status + systemPrompt: string; // GPT-5 system prompt + createdAt: string; // Creation timestamp + lastActivity: string; // Last activity timestamp + metadata: Record; // Additional metadata +} +``` + +### Task Interface + +```typescript +interface AgentTask { + id: string; // Unique task identifier + type: string; // Task type + description: string; // Task description + status: 'pending' | 'in_progress' | 'completed' | 'failed'; + startTime: string; // Task start time + endTime?: string; // Task completion time + result?: any; // Task result + error?: string; // Error message if failed +} +``` + +### Task Types + +#### chat_completion +General purpose chat completion task. + +**Task Data:** +```typescript +{ + messages: ChatMessage[]; // Conversation messages + model?: string; // Override default model + temperature?: number; // Override temperature + maxTokens?: number; // Override token limit +} +``` + +#### code_review +Code review and analysis task. + +**Task Data:** +```typescript +{ + code: string; // Code to review + language: string; // Programming language + context?: string; // Additional context +} +``` + +#### documentation +Documentation generation task. + +**Task Data:** +```typescript +{ + content: string; // Content to document + documentType: string; // Type of documentation + audience: string; // Target audience +} +``` + +#### architecture_analysis +System architecture analysis task. + +**Task Data:** +```typescript +{ + systemDescription: string; // System to analyze + requirements: string; // System requirements + constraints: string; // System constraints +} +``` + +## Conversation Management + +### Thread Interface + +```typescript +interface ConversationThread { + id: string; // Unique thread identifier + topic: string; // Thread topic/subject + participants: string[]; // Participant agent IDs + creator: string; // Thread creator ID + status: 'active' | 'paused' | 'completed' | 'escalated'; + createdAt: string; // Creation timestamp + lastActivity: string; // Last activity timestamp + messages: ThreadMessage[]; // Thread messages + metadata: Record; // Thread metadata + escalationHistory: EscalationEvent[]; // Escalation events + summary?: string; // Thread summary +} +``` + +### Message Interface + +```typescript +interface ThreadMessage { + id: string; // Unique message identifier + threadId: string; // Parent thread ID + sender: string; // Sender agent ID + content: string; // Message content + messageType: 'text' | 'code' | 'file' | 'decision' | 'question'; + timestamp: string; // Message timestamp + replyTo?: string; // Reply to message ID + metadata: Record; // Message metadata +} +``` + +### Escalation Events + +```typescript +interface EscalationEvent { + id: string; // Unique escalation ID + threadId: string; // Parent thread ID + rule: string; // Triggered escalation rule + reason: string; // Escalation reason + triggeredAt: string; // Escalation timestamp + actions: EscalationAction[]; // Actions taken + resolved: boolean; // Resolution status + resolution?: string; // Resolution description +} +``` + +## P2P Connector + +### Network Peer Interface + +```typescript +interface NetworkPeer { + id: string; // Peer identifier + address: string; // Network address + capabilities: string[]; // Peer capabilities + lastSeen: string; // Last seen timestamp + status: 'online' | 'offline' | 'busy'; +} +``` + +### Subscription Interface + +```typescript +interface BzzzSubscription { + id: string; // Subscription identifier + eventTypes: string[]; // Subscribed event types + filterAddress?: string; // Address filter pattern + callbackWebhook?: string; // Callback webhook URL + subscriberId: string; // Subscriber agent ID +} +``` + +## OpenAI Integration + +### Completion Options + +```typescript +interface CompletionOptions { + model?: string; // Model to use (default: gpt-5) + temperature?: number; // Temperature (0-2, default: 0.7) + maxTokens?: number; // Max tokens (default: 4000) + systemPrompt?: string; // System prompt + messages?: ChatMessage[]; // Conversation messages +} +``` + +### Completion Result + +```typescript +interface CompletionResult { + content: string; // Generated content + usage: TokenUsage; // Token usage statistics + model: string; // Model used + finishReason: string; // Completion finish reason + cost: number; // Estimated cost (USD) +} +``` + +### Token Usage + +```typescript +interface TokenUsage { + promptTokens: number; // Input tokens used + completionTokens: number; // Output tokens generated + totalTokens: number; // Total tokens consumed +} +``` + +## Cost Tracker + +### Cost Usage Interface + +```typescript +interface CostUsage { + date: string; // Date (YYYY-MM-DD or YYYY-MM) + totalCost: number; // Total cost in USD + apiCalls: number; // Number of API calls + tokens: { + prompt: number; // Total prompt tokens + completion: number; // Total completion tokens + total: number; // Total tokens + }; + models: Record; +} +``` + +### Cost Limits + +```typescript +interface CostTrackerConfig { + dailyLimit: number; // Daily spending limit (USD) + monthlyLimit: number; // Monthly spending limit (USD) + warningThreshold: number; // Warning threshold (0-1) +} +``` + +### Cost Events + +The cost tracker emits the following events: + +- `warning`: Emitted when usage exceeds warning threshold +- `limit_exceeded`: Emitted when usage exceeds daily/monthly limits + +## Configuration + +### Main Configuration Interface + +```typescript +interface BzzzMcpConfig { + openai: { + apiKey: string; // OpenAI API key + defaultModel: string; // Default model (gpt-5) + maxTokens: number; // Default max tokens + temperature: number; // Default temperature + }; + bzzz: { + nodeUrl: string; // BZZZ Go service URL + networkId: string; // Network identifier + pubsubTopics: string[]; // PubSub topic subscriptions + }; + cost: { + dailyLimit: number; // Daily cost limit + monthlyLimit: number; // Monthly cost limit + warningThreshold: number; // Warning threshold + }; + conversation: { + maxActiveThreads: number; // Max concurrent threads + defaultTimeout: number; // Thread timeout (seconds) + escalationRules: EscalationRule[]; // Escalation rules + }; + agents: { + maxAgents: number; // Maximum agents + defaultRoles: AgentRoleConfig[]; // Default role configs + }; + logging: { + level: string; // Log level + file?: string; // Log file path + }; +} +``` + +### Escalation Rules + +```typescript +interface EscalationRule { + name: string; // Rule name + conditions: EscalationCondition[]; // Trigger conditions + actions: EscalationAction[]; // Actions to take + priority: number; // Rule priority +} + +interface EscalationCondition { + type: 'thread_duration' | 'no_progress' | 'disagreement_count' | 'error_rate'; + threshold: number | boolean; // Condition threshold + timeframe?: number; // Time window (seconds) +} + +interface EscalationAction { + type: 'notify_human' | 'request_expert' | 'escalate_to_architect' | 'create_decision_thread'; + target?: string; // Action target + priority?: string; // Action priority + participants?: string[]; // Additional participants +} +``` + +## Error Handling + +### Standard Error Response + +```typescript +interface ErrorResponse { + success: false; + error: string; // Error message + code?: string; // Error code + details?: any; // Additional error details + timestamp: string; // Error timestamp +} +``` + +### Common Error Codes + +- `INVALID_PARAMETERS`: Invalid or missing parameters +- `AGENT_NOT_FOUND`: Referenced agent doesn't exist +- `THREAD_NOT_FOUND`: Referenced thread doesn't exist +- `NETWORK_ERROR`: P2P network communication failure +- `OPENAI_ERROR`: OpenAI API error +- `COST_LIMIT_EXCEEDED`: Cost limit exceeded +- `ESCALATION_FAILED`: Thread escalation failed + +### Error Handling Best Practices + +1. **Always check response.success** before processing results +2. **Log errors** with appropriate detail level +3. **Implement retry logic** for transient network errors +4. **Handle cost limit errors** gracefully with user notification +5. **Provide meaningful error messages** to users and logs + +## Rate Limits and Throttling + +### OpenAI API Limits +- **GPT-5**: Rate limits depend on your OpenAI tier +- **Tokens per minute**: Varies by subscription +- **Requests per minute**: Varies by subscription + +### BZZZ Network Limits +- **Messages per second**: Configurable per node +- **Thread creation**: Limited by `maxActiveThreads` +- **Subscription limits**: Limited by network capacity + +### Handling Rate Limits + +1. **Implement exponential backoff** for retries +2. **Monitor usage patterns** and adjust accordingly +3. **Use streaming** for real-time applications +4. **Cache results** where appropriate +5. **Implement circuit breakers** for failing services + +## Monitoring and Observability + +### Health Check Endpoints + +While the MCP server doesn't expose HTTP endpoints directly, you can monitor health through: + +1. **Log analysis**: Monitor error rates and response times +2. **Cost tracking**: Monitor API usage and costs +3. **Agent performance**: Track task completion rates +4. **Thread metrics**: Monitor conversation health +5. **Network connectivity**: Monitor P2P connection status + +### Metrics to Monitor + +- **Agent availability**: Percentage of agents online and available +- **Task completion rate**: Successful task completion percentage +- **Average response time**: Time from task assignment to completion +- **Thread escalation rate**: Percentage of threads requiring escalation +- **Cost per interaction**: Average cost per agent interaction +- **Network latency**: P2P network communication delays + +This completes the comprehensive API reference for the BZZZ MCP Server. Use this reference when integrating with the server or developing new features. \ No newline at end of file diff --git a/mcp-server/docs/DEPLOYMENT.md b/mcp-server/docs/DEPLOYMENT.md new file mode 100644 index 00000000..11fb0998 --- /dev/null +++ b/mcp-server/docs/DEPLOYMENT.md @@ -0,0 +1,640 @@ +# BZZZ MCP Server Deployment Guide + +Complete deployment guide for the BZZZ MCP Server in various environments. + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Environment Configuration](#environment-configuration) +- [Development Deployment](#development-deployment) +- [Production Deployment](#production-deployment) +- [Docker Deployment](#docker-deployment) +- [Systemd Service](#systemd-service) +- [Monitoring and Health Checks](#monitoring-and-health-checks) +- [Backup and Recovery](#backup-and-recovery) +- [Troubleshooting](#troubleshooting) + +## Prerequisites + +### System Requirements + +**Minimum Requirements:** +- Node.js 18.0 or higher +- 2 CPU cores +- 4GB RAM +- 10GB disk space +- Network access to OpenAI API +- Network access to BZZZ Go service + +**Recommended Requirements:** +- Node.js 20.0 or higher +- 4 CPU cores +- 8GB RAM +- 50GB disk space +- High-speed internet connection +- Load balancer for multiple instances + +### External Dependencies + +1. **OpenAI API Access** + - Valid OpenAI API key + - GPT-5 model access + - Sufficient API credits + +2. **BZZZ Go Service** + - Running BZZZ Go service instance + - Network connectivity to BZZZ service + - Compatible BZZZ API version + +3. **Network Configuration** + - Outbound HTTPS access (port 443) for OpenAI + - HTTP/WebSocket access to BZZZ service + - Optionally: Inbound access for health checks + +## Environment Configuration + +### Environment Variables + +Create a `.env` file or set system environment variables: + +```bash +# OpenAI Configuration +OPENAI_MODEL=gpt-5 +OPENAI_MAX_TOKENS=4000 +OPENAI_TEMPERATURE=0.7 + +# BZZZ Configuration +BZZZ_NODE_URL=http://localhost:8080 +BZZZ_NETWORK_ID=bzzz-production + +# Cost Management +DAILY_COST_LIMIT=100.0 +MONTHLY_COST_LIMIT=1000.0 +COST_WARNING_THRESHOLD=0.8 + +# Performance Settings +MAX_ACTIVE_THREADS=10 +MAX_AGENTS=5 +THREAD_TIMEOUT=3600 + +# Logging +LOG_LEVEL=info +LOG_FILE=/var/log/bzzz-mcp/server.log + +# Node.js Settings +NODE_ENV=production +``` + +### Security Configuration + +1. **API Key Management** +```bash +# Create secure directory +sudo mkdir -p /opt/bzzz-mcp/secrets +sudo chown bzzz:bzzz /opt/bzzz-mcp/secrets +sudo chmod 700 /opt/bzzz-mcp/secrets + +# Store OpenAI API key +echo "your-openai-api-key" | sudo tee /opt/bzzz-mcp/secrets/openai-api-key.txt +sudo chown bzzz:bzzz /opt/bzzz-mcp/secrets/openai-api-key.txt +sudo chmod 600 /opt/bzzz-mcp/secrets/openai-api-key.txt +``` + +2. **Network Security** +```bash +# Configure firewall (Ubuntu/Debian) +sudo ufw allow out 443/tcp # OpenAI API +sudo ufw allow out 8080/tcp # BZZZ Go service +sudo ufw allow in 3000/tcp # Health checks (optional) +``` + +## Development Deployment + +### Local Development Setup + +1. **Clone and Install** +```bash +cd /path/to/BZZZ/mcp-server +npm install +``` + +2. **Configure Development Environment** +```bash +# Copy example environment file +cp .env.example .env + +# Edit configuration +nano .env +``` + +3. **Start Development Server** +```bash +# With hot reload +npm run dev + +# Or build and run +npm run build +npm start +``` + +### Development Docker Setup + +```dockerfile +# Dockerfile.dev +FROM node:20-alpine + +WORKDIR /app + +# Install dependencies +COPY package*.json ./ +RUN npm ci + +# Copy source +COPY . . + +# Development command +CMD ["npm", "run", "dev"] +``` + +```bash +# Build and run development container +docker build -f Dockerfile.dev -t bzzz-mcp:dev . +docker run -p 3000:3000 -v $(pwd):/app bzzz-mcp:dev +``` + +## Production Deployment + +### Manual Production Setup + +1. **Create Application User** +```bash +sudo useradd -r -s /bin/false bzzz +sudo mkdir -p /opt/bzzz-mcp +sudo chown bzzz:bzzz /opt/bzzz-mcp +``` + +2. **Install Application** +```bash +# Copy built application +sudo cp -r dist/ /opt/bzzz-mcp/ +sudo cp package*.json /opt/bzzz-mcp/ +sudo chown -R bzzz:bzzz /opt/bzzz-mcp + +# Install production dependencies +cd /opt/bzzz-mcp +sudo -u bzzz npm ci --only=production +``` + +3. **Configure Logging** +```bash +sudo mkdir -p /var/log/bzzz-mcp +sudo chown bzzz:bzzz /var/log/bzzz-mcp +sudo chmod 755 /var/log/bzzz-mcp + +# Setup log rotation +sudo tee /etc/logrotate.d/bzzz-mcp << EOF +/var/log/bzzz-mcp/*.log { + daily + rotate 30 + compress + delaycompress + missingok + notifempty + create 644 bzzz bzzz + postrotate + systemctl reload bzzz-mcp + endscript +} +EOF +``` + +## Docker Deployment + +### Production Dockerfile + +```dockerfile +FROM node:20-alpine AS builder + +WORKDIR /app + +# Copy package files +COPY package*.json ./ + +# Install all dependencies +RUN npm ci + +# Copy source code +COPY . . + +# Build application +RUN npm run build + +# Production stage +FROM node:20-alpine AS production + +# Create app user +RUN addgroup -g 1001 -S bzzz && \ + adduser -S bzzz -u 1001 + +# Create app directory +WORKDIR /opt/bzzz-mcp + +# Copy built application +COPY --from=builder --chown=bzzz:bzzz /app/dist ./dist +COPY --from=builder --chown=bzzz:bzzz /app/package*.json ./ + +# Install only production dependencies +RUN npm ci --only=production && npm cache clean --force + +# Create directories +RUN mkdir -p /var/log/bzzz-mcp && \ + chown bzzz:bzzz /var/log/bzzz-mcp + +# Switch to app user +USER bzzz + +# Health check +HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ + CMD node dist/health-check.js || exit 1 + +EXPOSE 3000 + +CMD ["node", "dist/index.js"] +``` + +### Docker Compose Setup + +```yaml +version: '3.8' + +services: + bzzz-mcp: + build: . + container_name: bzzz-mcp-server + restart: unless-stopped + environment: + - NODE_ENV=production + - LOG_LEVEL=info + - BZZZ_NODE_URL=http://bzzz-go:8080 + - DAILY_COST_LIMIT=100.0 + - MONTHLY_COST_LIMIT=1000.0 + volumes: + - ./secrets:/opt/bzzz-mcp/secrets:ro + - bzzz-mcp-logs:/var/log/bzzz-mcp + networks: + - bzzz-network + depends_on: + - bzzz-go + labels: + - "traefik.enable=true" + - "traefik.http.routers.bzzz-mcp.rule=Host(`bzzz-mcp.local`)" + - "traefik.http.services.bzzz-mcp.loadbalancer.server.port=3000" + + bzzz-go: + image: bzzz-go:latest + container_name: bzzz-go-service + restart: unless-stopped + ports: + - "8080:8080" + networks: + - bzzz-network + +volumes: + bzzz-mcp-logs: + +networks: + bzzz-network: + driver: bridge +``` + +### Deployment Commands + +```bash +# Build and start services +docker-compose up -d + +# View logs +docker-compose logs -f bzzz-mcp + +# Update application +docker-compose pull +docker-compose up -d --force-recreate + +# Stop services +docker-compose down +``` + +## Systemd Service + +### Service Configuration + +```ini +# /etc/systemd/system/bzzz-mcp.service +[Unit] +Description=BZZZ MCP Server +Documentation=https://docs.bzzz.local/mcp-server +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +User=bzzz +Group=bzzz +WorkingDirectory=/opt/bzzz-mcp + +# Environment +Environment=NODE_ENV=production +Environment=LOG_LEVEL=info +EnvironmentFile=-/etc/bzzz-mcp/environment + +# Execution +ExecStart=/usr/bin/node dist/index.js +ExecReload=/bin/kill -HUP $MAINPID + +# Process management +Restart=always +RestartSec=10 +KillMode=mixed +KillSignal=SIGTERM +TimeoutSec=30 + +# Security +NoNewPrivileges=yes +ProtectSystem=strict +ProtectHome=yes +ReadWritePaths=/var/log/bzzz-mcp +PrivateTmp=yes + +# Logging +StandardOutput=journal +StandardError=journal +SyslogIdentifier=bzzz-mcp + +[Install] +WantedBy=multi-user.target +``` + +### Service Management + +```bash +# Install and enable service +sudo systemctl daemon-reload +sudo systemctl enable bzzz-mcp +sudo systemctl start bzzz-mcp + +# Service status and logs +sudo systemctl status bzzz-mcp +sudo journalctl -u bzzz-mcp -f + +# Service control +sudo systemctl stop bzzz-mcp +sudo systemctl restart bzzz-mcp +sudo systemctl reload bzzz-mcp +``` + +### Environment File + +```bash +# /etc/bzzz-mcp/environment +OPENAI_MODEL=gpt-5 +BZZZ_NODE_URL=http://localhost:8080 +BZZZ_NETWORK_ID=bzzz-production +DAILY_COST_LIMIT=100.0 +MONTHLY_COST_LIMIT=1000.0 +LOG_FILE=/var/log/bzzz-mcp/server.log +``` + +## Monitoring and Health Checks + +### Health Check Script + +```javascript +// health-check.js +const http = require('http'); + +function healthCheck() { + return new Promise((resolve, reject) => { + const req = http.request({ + hostname: 'localhost', + port: 3000, + path: '/health', + method: 'GET', + timeout: 3000 + }, (res) => { + if (res.statusCode === 200) { + resolve('healthy'); + } else { + reject(new Error(`Health check failed: ${res.statusCode}`)); + } + }); + + req.on('error', reject); + req.on('timeout', () => reject(new Error('Health check timeout'))); + req.end(); + }); +} + +healthCheck() + .then(() => process.exit(0)) + .catch(() => process.exit(1)); +``` + +### Monitoring Script + +```bash +#!/bin/bash +# /usr/local/bin/bzzz-mcp-monitor.sh + +LOG_FILE="/var/log/bzzz-mcp/monitor.log" +SERVICE_NAME="bzzz-mcp" + +log() { + echo "$(date '+%Y-%m-%d %H:%M:%S') $1" >> $LOG_FILE +} + +# Check if service is running +if ! systemctl is-active --quiet $SERVICE_NAME; then + log "ERROR: Service $SERVICE_NAME is not running" + systemctl restart $SERVICE_NAME + log "INFO: Attempted to restart $SERVICE_NAME" + exit 1 +fi + +# Check memory usage +MEMORY_USAGE=$(ps -o pid,ppid,cmd,%mem --sort=-%mem -C node | grep bzzz-mcp | awk '{print $4}') +if [[ -n "$MEMORY_USAGE" ]] && (( $(echo "$MEMORY_USAGE > 80" | bc -l) )); then + log "WARNING: High memory usage: ${MEMORY_USAGE}%" +fi + +# Check log file size +LOG_SIZE=$(du -m /var/log/bzzz-mcp/server.log 2>/dev/null | cut -f1) +if [[ -n "$LOG_SIZE" ]] && (( LOG_SIZE > 100 )); then + log "WARNING: Large log file: ${LOG_SIZE}MB" +fi + +log "INFO: Health check completed" +``` + +### Cron Job Setup + +```bash +# Add to crontab +sudo crontab -e + +# Check every 5 minutes +*/5 * * * * /usr/local/bin/bzzz-mcp-monitor.sh +``` + +## Backup and Recovery + +### Configuration Backup + +```bash +#!/bin/bash +# /usr/local/bin/backup-bzzz-mcp.sh + +BACKUP_DIR="/backup/bzzz-mcp" +DATE=$(date +%Y%m%d_%H%M%S) + +mkdir -p $BACKUP_DIR + +# Backup configuration +tar -czf $BACKUP_DIR/config-$DATE.tar.gz \ + /etc/bzzz-mcp/ \ + /opt/bzzz-mcp/secrets/ \ + /etc/systemd/system/bzzz-mcp.service + +# Backup logs (last 7 days) +find /var/log/bzzz-mcp/ -name "*.log" -mtime -7 -exec \ + tar -czf $BACKUP_DIR/logs-$DATE.tar.gz {} + + +# Cleanup old backups (keep 30 days) +find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete + +echo "Backup completed: $DATE" +``` + +### Recovery Procedure + +1. **Stop Service** +```bash +sudo systemctl stop bzzz-mcp +``` + +2. **Restore Configuration** +```bash +cd /backup/bzzz-mcp +tar -xzf config-YYYYMMDD_HHMMSS.tar.gz -C / +``` + +3. **Verify Permissions** +```bash +sudo chown -R bzzz:bzzz /opt/bzzz-mcp +sudo chmod 600 /opt/bzzz-mcp/secrets/* +``` + +4. **Restart Service** +```bash +sudo systemctl start bzzz-mcp +sudo systemctl status bzzz-mcp +``` + +## Troubleshooting + +### Common Issues + +**1. Service Won't Start** +```bash +# Check logs +sudo journalctl -u bzzz-mcp -n 50 + +# Common causes: +# - Missing API key file +# - Permission issues +# - Port conflicts +# - Missing dependencies +``` + +**2. High Memory Usage** +```bash +# Monitor memory usage +ps aux | grep node +htop + +# Possible solutions: +# - Reduce MAX_AGENTS +# - Decrease MAX_ACTIVE_THREADS +# - Restart service periodically +``` + +**3. OpenAI API Errors** +```bash +# Check API key validity +curl -H "Authorization: Bearer $OPENAI_API_KEY" \ + https://api.openai.com/v1/models + +# Common issues: +# - Invalid or expired API key +# - Rate limit exceeded +# - Insufficient credits +``` + +**4. BZZZ Connection Issues** +```bash +# Test BZZZ service connectivity +curl http://localhost:8080/api/v1/health + +# Check network configuration +netstat -tulpn | grep 8080 +``` + +### Performance Tuning + +**Node.js Optimization:** +```bash +# Add to service environment +NODE_OPTIONS="--max-old-space-size=4096 --optimize-for-size" +``` + +**System Optimization:** +```bash +# Increase file descriptor limits +echo "bzzz soft nofile 65536" >> /etc/security/limits.conf +echo "bzzz hard nofile 65536" >> /etc/security/limits.conf + +# Optimize network settings +echo 'net.core.somaxconn = 1024' >> /etc/sysctl.conf +sysctl -p +``` + +### Debug Mode + +Enable debug logging for troubleshooting: + +```bash +# Temporary debug mode +sudo systemctl edit bzzz-mcp + +# Add: +[Service] +Environment=LOG_LEVEL=debug + +# Reload and restart +sudo systemctl daemon-reload +sudo systemctl restart bzzz-mcp +``` + +### Log Analysis + +```bash +# Real-time log monitoring +sudo journalctl -u bzzz-mcp -f + +# Error analysis +grep -i error /var/log/bzzz-mcp/server.log | tail -20 + +# Performance analysis +grep -i "response time" /var/log/bzzz-mcp/server.log | tail -10 +``` + +This completes the comprehensive deployment guide. Follow the appropriate section based on your deployment environment and requirements. \ No newline at end of file