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
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