bzzz/mcp-server/BZZZ-MCP-README.md

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

cd /path/to/BZZZ/mcp-server
npm install
npm run build

Configuration

Create your OpenAI API key file:

echo "your-openai-api-key-here" > ~/chorus/business/secrets/openai-api-key-for-bzzz.txt

Running the Server

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

{
  "agent_id": "string (required)",
  "role": "string (required)",
  "capabilities": ["string"],
  "specialization": "string",
  "max_tasks": "number (default: 3)"
}

Example:

{
  "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:

{
  "semantic_address": "string (required)",
  "filter_criteria": {
    "expertise": ["string"],
    "availability": "boolean",
    "performance_threshold": "number"
  }
}

Address Format: bzzz://agent:role@project:task/path

Example:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

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

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

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

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

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:

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

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

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

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