Developer Research MCP Server

This repository contains a Model Context Protocol (MCP) server designed to provide structured research capabilities, primarily web search, for AI agents or other development tools. MCP enables standardized communication between a client (like an AI agent) and servers offering specialized tools.

This server initially uses OpenRouter for its web search functionality but is built with an extensible architecture to easily integrate additional research providers (e.g., other search engines, databases) in the future.

Table of Contents

• Developer Research MCP Server
  • Table of Contents
  • Features
  • Architecture and Extensibility
  • Prerequisites
  • Installation
  • Configuration
  • Consumption
    • Using with Roo Code
  • Available Tools
    • search_web
      • Parameters
      • Example (Conceptual Roo Code Usage)
      • Response Format
  • License

Features

• Provides web search capabilities via providers like OpenRouter.
• Optimized for retrieving technical and software development content.
• Designed for extensibility to support multiple research providers.
• Implements reliable error handling and retry mechanisms.
• Delivers results in a well-structured, consistent JSON format suitable for programmatic use.

Architecture and Extensibility

This server utilizes a modular architecture. Each research provider (like OpenRouter) is implemented as a distinct module adhering to a common interface. This design principle makes it straightforward to:

1. Add support for new search engines or data sources.
2. Switch between providers based on configuration or request parameters (future enhancement).
3. Maintain and update provider-specific logic independently.

Prerequisites

• Node.js v18 or higher
• npm (comes with Node.js)
• An API key for the desired research provider (e.g., OpenRouter)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/developer-research-server.git # Replace with the actual URL
   cd developer-research-server
   

2. Install dependencies: Use npm to install the project dependencies.

   npm install
   

3. Build the project: Compile the TypeScript code to JavaScript.

   npm run build
   

   The compiled output will be in the build/ directory.

Configuration

The server is configured using environment variables.

1. Create a .env file: Copy the mcp-config-sample.json (if available, or create one manually) to a .env file in the project root.

   # Example .env file content:
   OPENROUTER_API_KEY=your_openrouter_api_key_here
   OPENROUTER_API_URL=https://openrouter.ai/api/v1
   

   Note: Ensure the .env file is added to your .gitignore to avoid committing secrets.

2. Required Environment Variables:

   • OPENROUTER_API_KEY (required for OpenRouter provider): Your unique OpenRouter API key.
   • OPENROUTER_API_URL (optional): The base URL for the OpenRouter API. Defaults to https://openrouter.ai/api/v1.

   Future providers might require different environment variables.

Consumption

This MCP server listens for requests over standard input/output (stdio) when run directly. It's designed to be integrated into tools like Roo Code.

Using with Roo Code

To use this server with Roo Code, add the following configuration to your .roo/mcp.json file. Adjust the args path to point to the compiled index.js file within your cloned repository location.

{
  "mcpServers": {
    "developer-research": {
      // Changed name to be more generic
      "command": "node",
      "args": ["/full/path/to/your/developer-research-server/build/index.js"], // <-- IMPORTANT: Update this path
      "env": {
        // Environment variables are typically loaded from the .env file
        // Or can be explicitly set here if needed, but .env is recommended for secrets
        // "OPENROUTER_API_KEY": "your-openrouter-api-key", // <-- Replace or load from .env
        // "OPENROUTER_API_URL": "https://openrouter.ai/api/v1"
      },
      "alwaysAllow": ["search_web"], // List tools the agent can always use
      "timeout": 60 // Timeout in seconds
    }
  }
}

Important:

• Replace /full/path/to/your/developer-research-server/build/index.js with the correct absolute path on your system.
• Ensure the OPENROUTER_API_KEY is securely configured, preferably via the .env file loaded by the server process itself, rather than hardcoding it in mcp.json.

Available Tools

Currently, the server provides the following tools:

search_web

Performs a web search using the configured provider (currently OpenRouter) and returns relevant results.

Parameters

• query (string, required): The search query.
• num_results (integer, optional): The desired number of search results. Must be between 1 and 10. Defaults to 5.
• focus (string, optional): Specifies the focus area for the search. Supported values: "technical", "development", "general". Defaults to "technical".

Example (Conceptual Roo Code Usage)

// Within a Roo Code agent or script
const searchResults = await useMcpTool("developer-research", "search_web", {
  query: "advanced typescript patterns",
  num_results: 3,
  focus: "technical",
});

console.log(searchResults);

Response Format

The tool returns a JSON object with the following structure:

{
  "success": true, // Boolean indicating if the search was successful
  "results": [
    // Array of result objects
    {
      "title": "Title of the search result",
      "url": "https://example.com/page",
      "content": "A snippet or summary of the page content...",
      "domain": "example.com"
    }
    // ... more results
  ],
  "total_results": 3 // The actual number of results returned
}

In case of an error, the response might look like:

{
  "success": false,
  "error": "Description of the error that occurred."
}

License

MIT