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