HALO MCP Server

Official Model Context Protocol (MCP) server for the HALO Research Engine. Enables AI development tools like Cursor, Claude Code, and Warp.dev to leverage HALO's powerful multi-source research capabilities.

🎉 NEW: No API Keys Required! The server now supports fully local operation using open-source providers (DuckDuckGo, Wikipedia, SearxNG) without any external dependencies or costs.

Features

🆓 Zero-Cost Operation

• No API Keys Required: Works completely offline with open-source providers
• DuckDuckGo Integration: Instant answers and web search without tracking
• Wikipedia Access: Comprehensive encyclopedia content
• SearxNG Support: Privacy-focused metasearch engine integration

🔍 Advanced Research Capabilities

• Multi-Source Research: Access multiple providers simultaneously
• Intelligent Result Fusion: Combines and ranks results from different sources
• Research Templates: Pre-built workflows for academic, market, and technical research
• Depth Control: Quick, standard, comprehensive, or exhaustive search modes

🚀 Performance & Reliability

• Parallel Processing: Concurrent searches across multiple providers
• Smart Caching: Built-in caching reduces redundant requests
• Fallback Chain: Automatic provider switching for reliability
• Health Monitoring: Real-time provider status checking

🔌 Integration Ready

• Universal Compatibility: Works with any MCP-compatible tool
• Multiple Export Formats: JSON, Markdown, HTML, CSV
• Dual Mode Support: Local providers or external API (with Perplexity)
• 🐳 Docker Ready: Easy deployment with health checks

Quick Start

🆓 Zero-Setup Installation (No API Keys)

# Install globally
npm install -g @hamza.amjad/halo-mcp-server

# Run immediately - no configuration needed!
npx @hamza.amjad/halo-mcp-server

# The server automatically uses local providers (DuckDuckGo + Wikipedia)

🔑 With API Integration (Optional)

# For enhanced capabilities with Perplexity AI
export PERPLEXITY_API_KEY="your-api-key"
export HALO_ENGINE_MODE="external"

# Run with external API
npx @hamza.amjad/halo-mcp-server

Option 2: Docker (Recommended for Production)

# Pull the image
docker pull haloresearch/mcp-server:latest

# Run with environment variables
docker run -it --rm \
  -e PERPLEXITY_API_KEY="your-api-key" \
  haloresearch/mcp-server:latest

Option 3: Build from Source

# Clone the repository
git clone https://github.com/halo-research/halo-mcp-server.git
cd halo-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run
npm start

Tool Integrations

Cursor

Add to ~/.cursor/settings.json:

{
  "mcp": {
    "servers": {
      "halo": {
        "command": "halo-mcp-server",
        "env": {
          "PERPLEXITY_API_KEY": "${env:PERPLEXITY_API_KEY}"
        }
      }
    }
  }
}

Claude Code

Add to Claude Code MCP settings:

{
  "mcpServers": {
    "halo": {
      "command": "npx",
      "args": ["@hamza.amjad/halo-mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "${env:PERPLEXITY_API_KEY}"
      }
    }
  }
}

See Integration Guides for more tools.

Available Tools

halo.research

Execute intelligent multi-source research queries.

{
  query: string;              // Required: Your research question
  depth?: "quick" | "standard" | "comprehensive" | "exhaustive";
  type?: "general" | "academic" | "technology" | "medical";
  providers?: string[];       // Specific providers to use
  maxResults?: number;        // Limit results
  includeMetadata?: boolean;  // Include source metadata
}

Example: "Research the latest breakthroughs in quantum error correction"

halo.template

Use pre-built research templates for common scenarios.

{
  template: string;     // Required: Template name
  topic: string;        // Required: Research topic
  parameters?: object;  // Template-specific options
}

Available Templates:

• academic-literature: Comprehensive literature review
• market-research: Market analysis report
• competitive-analysis: Competitor research
• technical-specs: Technical documentation research

halo.export

Export research results in various formats.

{
  format: "json" | "markdown" | "html" | "csv" | "pdf";
  includeMetadata?: boolean;  // Include research metadata
  sessionId?: string;         // Export specific session
}

halo.cache

Manage the research cache for cost optimization.

{
  action: "list" | "get" | "clear" | "stats";
  key?: string;  // Required for "get" action
}

Configuration

🎛️ Engine Modes

The HALO MCP Server supports two operation modes:

🆓 Local Mode (Default - No API Keys Required)

Uses open-source providers for completely free operation:

• DuckDuckGo: Web search and instant answers
• Wikipedia: Encyclopedia content
• SearxNG: Privacy-focused metasearch (optional)

🌐 External Mode (Enhanced with API)

Uses the HALO API with Perplexity integration for advanced capabilities.

Environment Variables

Core Configuration

| Variable | Description | Default | |----------|-------------|---------| | HALO_ENGINE_MODE | Engine mode: local or external | local (if no API key) | | MCP_TRANSPORT | Transport type: stdio or websocket | stdio | | LOG_LEVEL | Logging level: debug, info, warn, error | info |

External Mode (API-based)

| Variable | Description | Default | |----------|-------------|---------| | PERPLEXITY_API_KEY | Your Perplexity API key | - | | HALO_API_URL | HALO API server URL | http://localhost:3001 |

Local Mode (Provider Configuration)

| Variable | Description | Default | |----------|-------------|---------| | SEARXNG_ENABLED | Enable SearxNG provider | true | | SEARXNG_URL | SearxNG instance URL | http://localhost:8888 | | DUCKDUCKGO_ENABLED | Enable DuckDuckGo provider | true | | WIKIPEDIA_ENABLED | Enable Wikipedia provider | true | | WIKIPEDIA_LANGUAGE | Wikipedia language code | en |

Optional Settings

| Variable | Description | Default | |----------|-------------|---------| | MCP_PORT | WebSocket server port | 3000 | | MCP_HOST | WebSocket server host | 0.0.0.0 | | REDIS_URL | Redis connection URL | redis://localhost:6379 |

Docker Compose

For production deployment with Redis:

version: '3.8'

services:
  halo-mcp:
    image: haloresearch/mcp-server:latest
    environment:
      PERPLEXITY_API_KEY: ${PERPLEXITY_API_KEY}
      REDIS_URL: redis://redis:6379
    depends_on:
      - redis
    
  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  redis-data:

Development

Setup

# Clone repository
git clone https://github.com/halo-research/halo-mcp-server.git
cd halo-mcp-server

# Install dependencies
npm install

# Run in development mode
npm run dev

Testing

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e

# Coverage report
npm run test:coverage

Building

# TypeScript compilation
npm run build

# Docker image
npm run docker:build

Architecture

The HALO MCP Server implements the Model Context Protocol specification with:

• Protocol Handler: JSON-RPC 2.0 message processing
• Transport Layer: Stdio and WebSocket support
• Tool Registry: Extensible tool management
• HALO Adapter: Integration with HALO Research Engine
• Session Management: Multi-client connection handling

See Architecture Documentation for details.

Performance

• Latency: <50ms tool discovery, <100ms request overhead
• Throughput: 100+ concurrent connections, 1000+ requests/minute
• Caching: 60-80% cost reduction with Redis
• Memory: <256MB baseline usage

Troubleshooting

Common Issues

1. Authentication Error

   Error: PERPLEXITY_API_KEY environment variable is required

   Solution: Set your API key: export PERPLEXITY_API_KEY="your-key"

2. Connection Failed

   Error: Failed to connect to HALO API

   Solution: Ensure HALO API is running or update HALO_API_URL

3. Rate Limiting

   Error: Rate limit exceeded for provider

   Solution: HALO automatically handles rate limits with queuing

Debug Mode

Enable detailed logging:

export LOG_LEVEL=debug
halo-mcp-server

Contributing

We welcome contributions! Please see our Contributing Guidelines.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discord Community
• 📧 Email Support

Acknowledgments

Built with:

• Model Context Protocol by Anthropic
• HALO Research Engine v3.8.0
• TypeScript, Node.js, Redis

Made with ❤️ by the HALO Team