UltraThink MCP Server

Standalone Model Context Protocol server with agentic-flow and agentdb integration

Overview

UltraThink is a production-ready MCP server that provides advanced multi-agent coordination, pattern learning, and memory management capabilities. It integrates seamlessly with agentic-flow for swarm coordination and agentdb for persistent learning.

Features

• 🤖 Swarm Management: Initialize and coordinate multi-agent swarms with flexible topologies
• 🧠 Pattern Learning: Automatic discovery and application of successful patterns
• 💾 Memory Persistence: Vector-based semantic search with long-term memory
• 📊 Metrics & Monitoring: Comprehensive health checks and performance tracking
• 🔧 Modular Design: Extensible tool system for custom functionality
• ⚡ High Performance: QUIC transport with lazy initialization
• 🔍 Zero-Config Context Detection: Auto-detect project, user, git, and environment info

Quick Start

Installation

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ultrathink": {
      "command": "node",
      "args": ["/path/to/packages/ultrathink/dist/server/server.js"],
      "env": {
        "ULTRATHINK_DB_PATH": "./data/ultrathink.db"
      }
    }
  }
}

Basic Example

MCP Server Usage

// Initialize a mesh swarm
await mcp.callTool('ultrathink_swarm_init', {
  swarmId: 'my-swarm',
  topology: 'mesh',
  maxAgents: 8
});

// Spawn a researcher agent
await mcp.callTool('ultrathink_agent_spawn', {
  swarmId: 'my-swarm',
  agentType: 'researcher',
  role: 'coordinator',
  capabilities: ['search', 'analyze', 'synthesize']
});

// Orchestrate a task
const result = await mcp.callTool('ultrathink_task_orchestrate', {
  swarmId: 'my-swarm',
  taskDescription: 'Research best practices for microservices',
  priority: 'high',
  strategy: 'adaptive'
});

Context Detection Usage

import { getOrDetectContext } from '@foxruv/iris-ultrathink';

// Auto-detect all context (zero-config!)
const context = await getOrDetectContext();

console.log(context);
// {
//   projectId: 'my-app',
//   projectName: '@company/my-app',
//   userId: '[email protected]',
//   userName: 'John Doe',
//   gitBranch: 'main',
//   gitCommit: 'abc1234',
//   hostname: 'dev-machine',
//   platform: 'linux-x64',
//   nodeVersion: 'v20.0.0'
// }

See Context Detection Documentation for more details.

Available Tools (19 Total)

Swarm Management (3)

• ultrathink_swarm_init - Initialize multi-agent swarm
• ultrathink_swarm_status - Get swarm status and metrics
• ultrathink_swarm_destroy - Shutdown swarm gracefully

Agent Management (3)

• ultrathink_agent_spawn - Spawn specialized agent
• ultrathink_agent_list - List active agents
• ultrathink_agent_metrics - Get agent performance metrics

Task Orchestration (3)

• ultrathink_task_orchestrate - Orchestrate complex tasks
• ultrathink_task_status - Check task execution status
• ultrathink_task_results - Get task completion results

Pattern Learning (4)

• ultrathink_pattern_discover - Discover learned patterns
• ultrathink_pattern_apply - Apply patterns to new tasks
• ultrathink_reflexion_record - Record reflexion for learning
• ultrathink_reflexion_search - Search similar reflexions

Memory Management (3)

• ultrathink_memory_store - Store memory with embeddings
• ultrathink_memory_search - Vector-based memory search
• ultrathink_memory_consolidate - Consolidate related memories

Health & Monitoring (3)

• ultrathink_health_check - Server health status
• ultrathink_metrics_get - Performance metrics
• ultrathink_tool_stats - Tool invocation statistics

Documentation

• Complete Documentation
• Usage Examples
• Context Detection
• Architecture Overview

Architecture

packages/ultrathink/
├── src/
│   ├── server/
│   │   ├── server.ts      # Main MCP server
│   │   ├── types.ts       # Type definitions
│   │   ├── tools.ts       # Tool schemas
│   │   ├── handlers.ts    # Tool implementations
│   │   └── index.ts       # Module exports
│   ├── utils/
│   │   ├── types.ts           # Context type definitions
│   │   ├── project-detector.ts # Package.json detection
│   │   ├── user-detector.ts    # User info detection
│   │   ├── git-detector.ts     # Git repo detection
│   │   ├── context-detector.ts # Main orchestrator
│   │   └── index.ts            # Utility exports
│   └── cli/               # CLI utilities
├── docs/
│   ├── MCP_SERVER.md          # Full documentation
│   ├── EXAMPLES.md            # Usage examples
│   └── CONTEXT_DETECTION.md   # Context detection guide
├── examples/
│   ├── simple-usage.ts             # Quick start example
│   └── context-detection-demo.ts   # Comprehensive demo
└── tests/                 # Test suite

Key Integrations

Agentic-Flow

Provides swarm coordination with:

• Multiple topology support (mesh, hierarchical, ring, star)
• QUIC and HTTP/2 transport protocols
• Dynamic agent spawning
• Task orchestration

AgentDB

Enables pattern learning through:

• Reflexion memory with self-critique
• Vector-based semantic search
• Pattern discovery and application
• Memory consolidation

Development

# Development mode with auto-reload
npm run start:dev

# Type checking
npm run typecheck

# Run tests
npm test

# Lint code
npm run lint

Configuration

Environment variables:

• ULTRATHINK_DB_PATH - Database path (default: ./data/ultrathink.db)
• NODE_ENV - Environment mode (development or production)

Performance

• Startup Time: <100ms (lazy initialization)
• Tool Invocation: <50ms (excluding handler logic)
• Memory Footprint: ~50MB (base) + handler state
• Concurrent Requests: Node.js event loop limited

Troubleshooting

Server won't start

• Verify Node.js >= 18.0.0: node --version
• Check MCP SDK installation: npm list @modelcontextprotocol/sdk
• Review startup logs for errors

Tools returning errors

• Check tool stats: ultrathink_tool_stats
• Review detailed health: ultrathink_health_check { detailed: true }
• Verify dependencies are installed

Performance issues

• Monitor metrics: ultrathink_metrics_get
• Check active resources
• Consolidate memories if high usage

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues
• Documentation: docs/
• Examples: docs/EXAMPLES.md

Credits

Built on top of:

• agentic-flow - Multi-agent coordination
• agentdb - Pattern learning and memory
• @modelcontextprotocol/sdk - MCP protocol

UltraThink - Empowering AI agents with swarm intelligence and persistent learning.