OpenRouter Agents MCP Server

# Upgrade Notes ## 2025-08-26 - New MODE env (AGENT | MANUAL | ALL). Default is ALL (agent + individual tools + always-on ops). - If you prefer a minimal surface, set `MODE=AGENT` to expose only `agent` plus ops tools (`ping`, status, jobs). - `MODE=MANUAL` exposes individual tools without `agent`. - Async `submit_research` now returns `ui_url` and `sse_url`, and emits a `ui_hint` event. - No breaking changes to existing tool params. # Upgrade Notes (v1.2.0) ## Highlights - Async jobs (`submit_research`, `get_job_status`, `cancel_job`) with SSE streams. - Unified `search` (BM25 + vectors + optional LLM rerank). - Usage (tokens) aggregated into `research_metadata.usage`. - Minimal micro UI at `/ui` for live monitoring. - MCP client JSON config examples in README; package exposes `openrouter-agents` bin. ## Breaking changes - None; existing tools remain. `search_index` is still available but superseded by `search`. ## Migrations - On startup, tables and columns are created/altered idempotently: - `index_documents.doc_len`, `index_documents.doc_embedding`. - `jobs`, `job_events`. ## New env vars - `JOBS_CONCURRENCY`, `JOB_HEARTBEAT_MS`, `JOB_LEASE_TIMEOUT_MS` for job worker. - `INDEXER_RERANK_ENABLED`, `INDEXER_RERANK_MODEL` (optional rerank). ## Client configuration - See README for STDIO and HTTP/SSE JSON config blocks. # OpenRouter Agents MCP Server Upgrade Notes ## Summary of Changes We have successfully implemented a suite of enhancements that improve the reliability, performance, and ease of use of the OpenRouter Agents MCP Server: 1. **Eliminated External Database Dependencies** - Replaced MongoDB with PGLite + pgvector for persistent storage - Implemented vector embeddings search natively with pgvector - All data is now stored locally in the `./researchAgentDB` directory 2. **Simplified Caching** - Replaced Redis with node-cache for in-memory caching - Implemented automatic expiration and key limits to prevent memory issues - All caching is now handled within the application process 3. **Streamlined Startup Process** - Created a simplified `start-mcp-server.bat` script - Removed the need for Docker Compose and external services - Updated MCP settings in Cline for plug-and-play operation 4. **Enhanced Documentation** - Updated README.md with new setup and configuration options - Added database configuration options to `.env.example` - Created test scripts to verify functionality ## Testing & Verification Both core features of the system have been tested and verified to work correctly: 1. **Vector Search**: Semantic search for similar past research is functioning with PGLite's vector search capabilities. 2. **Caching**: In-memory caching of research results is working correctly with configurable TTL. 3. **Research Process**: The full research workflow has been tested and works correctly with the new implementation. ## Configuration Options The following new configuration options are available in `.env`: ``` # Database and caching configuration PGLITE_DATA_DIR=./researchAgentDB # Directory for PGLite database files CACHE_TTL_SECONDS=3600 # Cache time-to-live in seconds (default: 1 hour) ``` ## Recent Enhancements (March 29, 2025) We've implemented additional improvements to enhance the reliability and resilience of the OpenRouter Agents MCP Server: 1. **Enhanced PGLite Database Integration**: - Added robust error handling with retry logic using exponential backoff - Implemented in-memory database fallback when file system access fails - Added environment detection for browser vs Node.js contexts - Added comprehensive configuration options for database behavior 2. **Improved Null Safety**: - Added defensive programming techniques throughout the codebase - Implemented safe string handling to prevent "substring of undefined" errors - Added parameter validation with defaults for all tool functions - Fixed several edge cases in the `research_follow_up` tool 3. **Configuration Flexibility**: - Added new environment variables for fine-tuning database behavior - Implemented hierarchical configuration with intelligent defaults - Enhanced documentation of all configuration options ## Next Steps The current implementation satisfies the requirements of Phase 1 and part of Phase 2 of the enhancement plan. Potential future improvements could include: 1. **Pluggable Agent System**: Create an abstract base Agent class with a registration mechanism. 2. **Iterative Planning Mechanism**: Implement multi-stage planning with feedback loops. 3. **Domain-Specific Model Routing**: Route sub-queries to models based on their strengths. 4. **Interactive Research Direction**: Allow user input during the research process. 5. **Multi-Modal Research**: Add support for images and structured data. ## Files Modified - `config.js`: Updated to include PGLite configuration options and resilience settings - `src/utils/dbClient.js`: Enhanced with robust error handling, retry logic, and fallback mechanisms - `src/server/tools.js`: Improved parameter validation and null safety - `.env.example`: Added new configuration options for database resilience - New files: `test-follow-up.js` for focused testing of the research_follow_up tool ## How to Use 1. Start the server using the new script: ``` start-mcp-server.bat ``` 2. Or call the Node.js script directly: ``` node src/server/mcpServer.js --stdio ``` 3. The MCP tools will be available in Cline without any need for external services.