Nexus MCP Server

# Overview OpenRouter Search MCP Server is a lightweight Node.js-based Model Context Protocol (MCP) server that provides AI copilots with access to real-time search capabilities via OpenRouter's API, specifically targeting Perplexity Sonar models. This tool addresses the limitation of existing generic URL fetchers and poorly implemented built-in search tools by leveraging Perplexity's high-quality, real-time search capabilities. The target audience is users of AI assistants and copilots (Claude Desktop, Claude Code, Cursor, etc.) who need access to current, accurate information during their workflows. The MCP server runs locally via STDIO and integrates seamlessly with any MCP-compatible AI client, providing transparent access to real-time search without requiring frontend interfaces. # Core Features ## Primary Search Tool - **search_tool**: Single, well-defined search endpoint that accepts queries and returns real-time data - **Transparent Integration**: Tool description written to be self-explanatory to AI copilots - **Real-time Data Access**: Leverages OpenRouter's API to access Perplexity Sonar models for current information - **Minimal Configuration**: Requires only OpenRouter API key for authentication ## Technical Integration - **MCP Protocol Compliance**: Full adherence to Model Context Protocol specification - **STDIO Communication**: Single-user support via standard input/output - **OpenRouter API Integration**: Uses `/chat/completions` endpoint with streaming support - **Error Handling**: Robust error handling and meaningful error responses # User Experience ## User Personas - **Primary**: Users of AI assistants (Claude Desktop, Claude Code, Cursor) requiring real-time information - **Secondary**: Developers and technical professionals using AI copilots for software development - **Tertiary**: General users of MCP-compatible AI clients who need current information access ## Key User Flows 1. **Installation**: `git clone` → `npx` or Node.js execution from local codebase 2. **Configuration**: Set OpenRouter API key in environment variables 3. **Usage**: AI assistant automatically discovers and uses search_tool when real-time data is needed 4. **Transparent Operation**: User experiences seamless search integration without manual tool invocation ## UI/UX Considerations - No frontend interface required - Tool descriptions must be clear and comprehensive for AI assistant understanding - Error messages should be developer-friendly and actionable # Technical Architecture ## System Components - **MCP Server Core**: Node.js application using official TypeScript SDK - **OpenRouter Integration**: HTTP client for API communication - **Search Handler**: Processes search requests and formats responses - **Configuration Manager**: Handles API key and environment setup ## Data Models ```typescript SearchRequest { query: string options?: { model?: string maxTokens?: number temperature?: number } } SearchResponse { result: string metadata?: { model: string tokens: number timestamp: string } } ``` ## APIs and Integrations - **OpenRouter API**: `/chat/completions` endpoint with Perplexity Sonar models - **MCP Protocol**: Standard MCP request/response handling - **Authentication**: Bearer token authentication with OpenRouter ## Infrastructure Requirements - **Node.js**: v16.0.0 or higher - **Dependencies**: MCP TypeScript SDK, HTTP client, configuration management - **Development Tools**: ESLint (flat config with @typescript-eslint), Prettier, pre-commit hooks, TypeScript compiler - **Testing**: Vitest, mocking libraries, test coverage reporting - **Environment**: Local development environment with STDIO support # Development Roadmap ## Phase 1: MVP (Core Search Functionality) - Test suite setup with Vitest and TDD approach - Basic MCP server setup with TypeScript SDK - OpenRouter API integration (test-driven) - Single search_tool implementation (test-driven) - Basic error handling and logging (test-driven) - Environment configuration (API key handling) - Package.json with proper scripts and dependencies - Pre-commit hooks for linting, formatting, type checking, and testing ## Phase 2: Enhanced Features - Multiple search model support (different Perplexity variants) - Search result caching for performance - Advanced error handling and retry logic - Comprehensive logging and debugging - Input validation and sanitization ## Phase 3: Advanced Capabilities - Search result formatting options - Configurable search parameters - Performance optimization - Comprehensive documentation - Integration and end-to-end testing # Logical Dependency Chain ## Foundation (Build First) 1. **Project Setup**: Package.json, TypeScript configuration, MCP SDK integration 2. **Development Tooling**: ESLint (flat config with @typescript-eslint, eslint-config-prettier), Prettier, pre-commit hooks setup 3. **Test Framework Setup**: Vitest configuration, test utilities, mocking setup 4. **OpenRouter Connection**: API client, authentication, basic connectivity test (TDD) 5. **MCP Server Framework**: Basic server structure, protocol handling (TDD) ## Core Functionality (Immediate Usability) 6. **Search Tool Implementation**: Basic search_tool with OpenRouter integration (TDD) 7. **Error Handling**: Basic error responses and logging (TDD) 8. **Configuration**: Environment variable handling for API keys ## Enhancement (Iterative Improvement) 9. **Advanced Search Features**: Multiple models, parameters, caching (TDD) 10. **Robust Error Handling**: Retry logic, detailed error messages (TDD) 11. **Performance Optimization**: Response time improvements, resource management # Development Methodology ## Test-Driven Development (TDD) This project will follow strict TDD practices using the Red-Green-Refactor cycle: ### TDD Implementation Strategy - **Red Phase**: Write failing tests that describe desired behavior before implementation - **Green Phase**: Write minimal code to make tests pass - **Refactor Phase**: Improve code quality while maintaining passing tests ### Testing Approach - **Unit Tests**: All core functionality (search tool, API integration, error handling) - **Integration Tests**: MCP protocol compliance, OpenRouter API interaction - **Mocking**: External dependencies (OpenRouter API, file system, environment) - **Coverage**: Maintain >90% test coverage for critical paths ### TDD Benefits for This Project - **Protocol Compliance**: Tests ensure MCP specification adherence - **API Integration**: Mock OpenRouter responses for reliable testing - **Error Handling**: Comprehensive edge case coverage - **Refactoring Safety**: Confident code improvements with test safety net # Risks and Mitigations ## Technical Challenges - **MCP Protocol Compliance**: Mitigate by following official TypeScript SDK patterns and documentation - **OpenRouter API Changes**: Implement robust error handling and API versioning awareness - **Search Quality**: Test with various query types and validate Perplexity Sonar model responses ## MVP Scoping - **Feature Creep**: Focus on single search_tool functionality first - **Over-engineering**: Keep initial implementation simple and functional - **Configuration Complexity**: Minimize required configuration to API key only ## Resource Constraints - **API Costs**: Implement reasonable rate limiting and error handling - **Development Time**: Prioritize core functionality over advanced features - **Maintenance**: Design for simplicity to reduce ongoing maintenance burden # Appendix ## Research Findings ### MCP Server Best Practices (2025) - Use Node.js v16+ with TypeScript for type safety - Implement structured logging with Winston - Use Zod for input validation - Follow modular design patterns - Implement proper error handling and resource management - Setup pre-commit hooks with ESLint (flat config), Prettier, and TypeScript checking - Follow Test-Driven Development (TDD) with Red-Green-Refactor cycle - Use Vitest for unit testing with comprehensive mocking - Maintain high test coverage for critical business logic ### ESLint Configuration (2025 Best Practices) - Use ESLint flat config format (eslint.config.js) - Core plugins: @typescript-eslint/eslint-plugin, @eslint/js, eslint-config-prettier - Additional plugins: eslint-plugin-node, eslint-plugin-import, eslint-plugin-unused-imports - Integrate with Prettier to avoid formatting conflicts - Use @typescript-eslint/parser with project-aware type checking - Enable strict TypeScript rules for better type safety ### OpenRouter API Integration - Use `/chat/completions` endpoint for Perplexity Sonar models - Authenticate with Bearer token API keys - Enable streaming for real-time responses - Leverage OpenAI-compatible SDK patterns - Implement proper rate limiting awareness ## Technical Specifications - **Protocol**: Model Context Protocol (MCP) - **Communication**: STDIO - **Authentication**: OpenRouter API key via environment variables - **Models**: Perplexity Sonar family via OpenRouter - **Deployment**: Local git clone + NPX execution