researcher-mcp

Pagent-Money/researcher-mcp

3.1

If you are the rightful owner of researcher-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Researcher-MCP is a research agent MCP server that performs live internet research and generates comprehensive reports using the DedalusLab Python SDK.

Tools
2
Resources
0
Prompts
0

Researcher-MCP Server

A research agent MCP server integrated with DedalusLab for live internet research - TypeScript implementation fully compliant with Dedalus Labs MCP Server Guidelines.

🎯 Dedalus Platform Ready

This server is 100% compliant with Dedalus Labs guidelines and ready for deployment on the Dedalus platform with HTTP-first architecture.

Features

  • 🔍 Live Internet Search: Real-time search using SerpAPI with intelligent fallbacks
  • 🤖 AI-Powered Research: Generate comprehensive research reports using OpenAI GPT models
  • 🌐 HTTP-First: Streamable HTTP transport for modern web compatibility
  • 📱 STDIO Support: Development-friendly STDIO transport
  • 🔧 Modular Architecture: Clean separation of concerns following Dedalus guidelines
  • 📊 Structured Output: JSON-formatted search results and markdown reports
  • 🛡️ Robust Fallbacks: Multiple fallback mechanisms ensure reliability
  • ⚡ High Performance: Async/await throughout with concurrent operations
  • 🔒 Type Safety: Full TypeScript type checking and interfaces
  • 🏥 Production Ready: Health checks, session management, CORS support

Quick Start

Installation

git clone <repository-url>
cd researcher-mcp
npm install
npm run build

Environment Setup

cp env.template .env
# Edit .env with your API keys

Required environment variables:

OPENAI_API_KEY=your_openai_api_key_here

Optional environment variables:

DEDALUS_API_KEY=your_dedalus_api_key_here
SERPAPI_API_KEY=your_serpapi_api_key_here
PORT=8080
NODE_ENV=production

Usage

# HTTP server (default - Dedalus compatible)
npm start

# Custom port
researcher-mcp --port 3000

# STDIO mode (development)
researcher-mcp --stdio

# Help
researcher-mcp --help

Available Tools

research_topic

Research a topic using live internet search and generate a comprehensive report (< 300 words).

Parameters:

  • topic (required): The topic to research
  • focus_areas (optional): Specific areas to focus on

Example:

{
  "tool": "research_topic",
  "arguments": {
    "topic": "quantum computing breakthroughs",
    "focus_areas": ["IBM", "Google", "commercial applications"]
  }
}

quick_search

Perform a quick internet search for recent information.

Parameters:

  • query (required): The search query
  • num_results (optional): Number of results to return (default: 5)

Example:

{
  "tool": "quick_search",
  "arguments": {
    "query": "latest AI developments 2024",
    "num_results": 3
  }
}

Integration

Claude Desktop (HTTP Mode - Recommended)

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "researcher": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Claude Desktop (STDIO Mode - Development)

{
  "mcpServers": {
    "researcher": {
      "command": "researcher-mcp",
      "args": ["--stdio"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "SERPAPI_API_KEY": "your-serpapi-api-key"
      }
    }
  }
}

Dedalus Platform

The server is ready for deployment on the Dedalus platform with its HTTP-first architecture and compliant structure.

Architecture

Directory Structure (Dedalus Compliant)

src/
├── index.ts            # Main entry point
├── cli.ts              # Command-line argument parsing
├── config.ts           # Configuration management
├── server.ts           # Server instance creation
├── client.ts           # External API client
├── types.ts            # TypeScript type definitions
├── tools/
│   ├── index.ts        # Tool exports
│   └── research.ts     # Tool definitions and handlers
└── transport/
    ├── index.ts        # Transport exports
    ├── http.ts         # HTTP transport (primary)
    └── stdio.ts        # STDIO transport (development)

Transport Layer

Primary: Streamable HTTP Transport
  • Endpoint: /mcp - Main MCP communication
  • Health Check: /health - Service monitoring
  • SSE Fallback: /sse - Server-Sent Events support
  • Session Management: UUID-based session tracking
  • CORS Support: Web client compatibility
Fallback: STDIO Transport
  • Development Mode: --stdio flag
  • Local Testing: Direct process communication
  • Backward Compatibility: Works with existing STDIO clients

Development

Scripts

npm run build          # Compile TypeScript
npm run watch          # Watch mode compilation
npm start              # Run HTTP server
npm run start:stdio    # Run STDIO server
npm run dev            # Build and run HTTP server
npm run dev:stdio      # Build and run STDIO server
npm test               # Run test client
npm run clean          # Clean build artifacts

Testing

Local Testing
# Test HTTP server
npm run dev

# Test STDIO server
npm run dev:stdio

# Run test client
npm test
Deployment Testing
# Comprehensive testing with Python scripts
cd examples

# Setup testing environment
./setup_tests.sh

# Test local functionality
python3 test_basic.py

# Test Dedalus deployment (requires API keys)
python3 test_dedalus_deployment.py

For detailed testing instructions, see .

Docker Support

# Build and run with Docker
docker build -t researcher-mcp .
docker run -p 8080:8080 --env-file .env researcher-mcp

# Or use docker-compose
docker-compose up -d

API Integration Details

SerpAPI Integration

  • Primary search method for real-time internet results
  • Handles up to 10 organic results per query
  • Automatic fallback on errors or rate limits
  • Free tier: 250 searches/month

OpenAI Integration

  • GPT-4o-mini for report generation and fallback search
  • Structured prompts for consistent output
  • Temperature tuning for balanced creativity/accuracy
  • Token limits optimized for concise reports

DedalusLab Integration

  • Enhanced AI capabilities (when available)
  • Advanced tool usage for research analysis
  • Seamless fallback to OpenAI when needed

Health Monitoring

Health Check Endpoint

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "service": "researcher-mcp",
  "version": "0.2.0"
}

Compliance

This server is 100% compliant with Dedalus Labs MCP Server Guidelines:

  • ✅ Entry Point: src/index.ts as main entry point
  • ✅ TypeScript Only: Full TypeScript implementation
  • ✅ HTTP Transport: Streamable HTTP transport as primary method
  • ✅ MCP SDK Version: Using @modelcontextprotocol/sdk ^1.17.3
  • ✅ Modular Architecture: Clear separation of concerns
  • ✅ Production Ready: Health checks, session management, error handling

See for detailed compliance analysis.

Requirements

  • Node.js: >= 18.0.0
  • TypeScript: >= 5.0.0
  • API Keys: OpenAI (required), SerpAPI & DedalusLab (optional)

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes with proper TypeScript types
  4. Add tests for new functionality
  5. Ensure Dedalus compliance
  6. Submit a pull request

Support

For issues and questions:

  • Check the
  • Review the
  • Open an issue on GitHub

Dedalus Platform: ✅ READY
HTTP Transport: ✅ PRIMARY
STDIO Transport: ✅ DEVELOPMENT
Production Ready: ✅ YES