Add comprehensive documentation for BZZZ MCP Server
- 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 <noreply@anthropic.com>
This commit is contained in:
anthonyrawlins
552
mcp-server/BZZZ-MCP-README.md
Normal file
552
mcp-server/BZZZ-MCP-README.md
Normal file
@@ -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.
|
||||||
609
mcp-server/docs/API_REFERENCE.md
Normal file
609
mcp-server/docs/API_REFERENCE.md
Normal file
@@ -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<string, any>; // 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<string, any>; // 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<string, any>; // 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<string, {
|
||||||
|
calls: number; // Calls per model
|
||||||
|
cost: number; // Cost per model
|
||||||
|
tokens: number; // Tokens per model
|
||||||
|
}>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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.
|
||||||
640
mcp-server/docs/DEPLOYMENT.md
Normal file
640
mcp-server/docs/DEPLOYMENT.md
Normal file
@@ -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.
|
||||||
Reference in New Issue
Block a user