SecondBrain MCP Server

Multi-agent orchestration system with quality control, analytics, and ML-powered intelligence for specialized sub-agent delegation.

SecondBrain MCP Server enables primary AI agents to spawn and coordinate specialized sub-agents while maintaining quality control, preventing infinite loops, and optimizing costs through intelligent delegation.

🚀 Features

• 🤖 Multi-Agent Orchestration: Spawn specialized sub-agents with domain expertise
• 🔒 Loop Protection: Sophisticated session management prevents infinite delegation
• ⚡ Quality Control: 5-tier validation system with ML-powered assessment
• 📊 Real-time Analytics: Performance monitoring and optimization insights
• 🧠 ML Intelligence: Predictive quality scoring and adaptive learning
• 💰 Cost Optimization: 80% cost reduction through intelligent delegation
• 🎯 12 MCP Tools: Comprehensive toolkit for agent coordination

📦 Installation

npm install -g @gork-labs/secondbrain-mcp

🔧 Configuration

Required Environment Variables:

• OPENROUTER_API_KEY: Your OpenRouter API key for accessing AI models
• SECONDBRAIN_MODEL: The model to use for sub-agents (e.g., anthropic/claude-3-5-sonnet-20241022)

Add to your mcp.json configuration file:

{
  "mcpServers": {
    "secondbrain": {
      "command": "npx",
      "args": ["@gork-labs/secondbrain-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key",
        "SECONDBRAIN_MODEL": "anthropic/claude-3-5-sonnet-20241022"
      }
    }
  }
}

Environment Variables

API Configuration

• OPENROUTER_API_KEY - OpenRouter API key (required)

Model Configuration

• SECONDBRAIN_PRIMARY_MODEL - Primary model for orchestration (default: anthropic/claude-3-5-sonnet-20241022)
• SECONDBRAIN_SUBAGENT_MODEL - Model for sub-agents (default: anthropic/claude-3-5-haiku-20241022)

Session Management

• SECONDBRAIN_SESSION_PATH - Custom session storage path (optional)
• SECONDBRAIN_MAX_CALLS - Maximum calls per session (default: 20)

🤖 Model Support

SecondBrain uses OpenRouter for unified access to all AI models:

Available Models

All models available through OpenRouter using standard provider/model format:

• Anthropic Models:

  • anthropic/claude-3-5-sonnet-20241022 - High-quality reasoning (default primary)
  • anthropic/claude-3-5-haiku-20241022 - Fast, cost-effective (default sub-agents)

• OpenAI Models:

  • openai/gpt-4o - OpenAI's latest flagship model
  • openai/gpt-4o-mini - Cost-effective option

• Google Models:

  • google/gemini-pro-1.5 - Google's latest model
  • google/gemini-flash-1.5 - Fast inference

• Open Source Models:

  • meta-llama/llama-3.1-405b-instruct - Large open source model
  • mistralai/mixtral-8x7b-instruct - Efficient mixture of experts

Configuration Examples

# Use Anthropic Claude Sonnet for primary (default)
export SECONDBRAIN_PRIMARY_MODEL="anthropic/claude-3-5-sonnet-20241022"

# Use Anthropic Claude Haiku for sub-agents (default)
export SECONDBRAIN_SUBAGENT_MODEL="anthropic/claude-3-5-haiku-20241022"

# Use OpenAI GPT-4O for primary
export SECONDBRAIN_PRIMARY_MODEL="openai/gpt-4o"

# Use Google Gemini for sub-agents
export SECONDBRAIN_SUBAGENT_MODEL="google/gemini-flash-1.5"

🛠️ Available MCP Tools

Core Agent Tools

• spawn_agent - Spawn specialized sub-agents with domain expertise
• list_subagents - List available specialized agent types
• validate_output - Comprehensive quality control and validation
• get_session_stats - Session tracking and loop protection metrics

Analytics & Intelligence

• get_quality_analytics - Quality trends and performance insights
• get_performance_analytics - Performance optimization metrics
• get_system_health - System status and health monitoring
• generate_analytics_report - Comprehensive analytics reports

ML-Powered Features

• predict_quality_score - ML-based quality prediction
• predict_refinement_success - Refinement success probability
• get_ml_insights - Advanced ML insights and recommendations
• get_optimization_suggestions - System optimization suggestions

🎯 Quick Start Example

```typescript
// Spawn a Security Engineer for vulnerability analysis
const response = await mcp.callTool('spawn_agent', {
  subagent: 'Security Engineer',
  task: 'Analyze web application for security vulnerabilities',
  context: 'E-commerce platform with user authentication and payment processing',
  expected_deliverables: 'Vulnerability report with remediation recommendations'
});

// Validate the sub-agent response
const validation = await mcp.callTool('validate_output', {
  sub_agent_response: response.content[0].text,
  requirements: 'Security vulnerability analysis',
  quality_criteria: 'Must include specific vulnerabilities and remediation steps',
  subagent: 'Security Engineer',
  enable_refinement: true
});

// Get ML insights about system performance const insights = await mcp.callTool('get_ml_insights', {});

## 🏗️ Architecture

### Hub-and-Spoke Model

Primary Agent (GPT-4) ├── Security Engineer → Threat analysis ├── DevOps Engineer → Infrastructure review ├── Database Architect → Data security └── Coordination & Validation → Final report

### Cost Optimization
- **Traditional**: 100% expensive model usage
- **SecondBrain**: 20% primary (GPT-4) + 80% specialized (o4-mini)
- **Result**: ~80% cost reduction with maintained quality

### Quality Control Pipeline
1. **Format Validation** - JSON structure and completeness
2. **Content Assessment** - Deliverables and quality scoring
3. **ML Enhancement** - Predictive assessment and learning
4. **Refinement Management** - Iterative improvement tracking
5. **Analytics Integration** - Performance monitoring and insights

## 📊 Specialized Agent Types

| Agent Type | Expertise | Use Cases |
|------------|-----------|-----------|
| Security Engineer | Security analysis, vulnerability assessment | Code review, threat modeling, compliance |
| DevOps Engineer | Infrastructure, deployment, monitoring | CI/CD, scaling, performance optimization |
| Database Architect | Data modeling, performance, security | Schema design, query optimization, backup |
| Software Architect | System design, patterns, scalability | Architecture decisions, technical strategy |
| Test Engineer | Testing strategies, automation, QA | Test planning, coverage analysis, automation |

## 🔍 Quality Metrics

The system tracks comprehensive quality metrics:

- **Overall Quality Score** (0-100): Weighted assessment across all dimensions
- **Rule-based Validation**: 5 universal quality rules
- **ML-Powered Assessment**: Predictive scoring and confidence levels
- **Refinement Success Rate**: Learning-based improvement tracking
- **Cross-Agent Performance**: Comparative analysis across specializations

## 📈 Analytics Capabilities

### Real-time Monitoring
- Agent performance tracking
- Quality trend analysis
- Cost optimization metrics
- Session management stats

### ML Intelligence
- Ensemble prediction models
- Cross-chatmode pattern analysis
- Optimization opportunity identification
- Adaptive learning and improvement

### Reporting
- Executive summaries
- Detailed technical reports
- Performance optimization insights
- System health monitoring

## 🛡️ Loop Protection

SecondBrain implements sophisticated loop protection:

- **Session Management**: Call limits and refinement tracking
- **Agent Restrictions**: Sub-agents cannot spawn other agents
- **Resource Limits**: Maximum 20 calls per session, 2 refinement iterations
- **Quality Thresholds**: Chatmode-specific quality requirements
- **Timeout Protection**: Automatic session cleanup and resource management

## 🔧 Advanced Configuration

### Custom Quality Thresholds
```json
{
  "qualityThresholds": {
    "Security Engineer": 0.80,
    "DevOps Engineer": 0.75,
    "default": 0.75
  }
}

Analytics Configuration

{
  "analytics": {
    "enabled": true,
    "retentionDays": 30,
    "mlInsights": true
  }
}

🧪 Development

git clone https://github.com/gork-labs/gorka.git
cd gorka/servers/secondbrain-mcp
npm install
npm run build
npm test

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

📋 Requirements

• Node.js: >= 18.0.0
• API Keys: OpenAI and/or Anthropic API access
• MCP Client: Compatible MCP client (GitHub Copilot, Claude Desktop, etc.)

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub Repository
• Model Context Protocol
• Gorka AI Agent System
• Issue Tracker

⭐ Support

If you find SecondBrain MCP Server useful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting issues
• 💡 Suggesting improvements
• 🤝 Contributing code

Built with ❤️ by the Gorka team | Powered by Model Context Protocol