nexus-mcp 1.0.0

package/README.md

@@ -0,0 +1,495 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<div align="center">
+
+# 🔍 Nexus MCP Server
+
+**AI integration without the complexity**
+
+[![npm version](https://badge.fury.io/js/nexus-mcp.svg)](https://www.npmjs.com/package/nexus-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
+
+_Intelligent AI model search and discovery with zero-install simplicity_
+
+[Quick Start](#-quick-start) • [Features](#-features) • [Documentation](#-documentation) • [Contributing](#-contributing)
+
+</div>
+
+---
+
+## 🚀 What is Nexus?
+
+Nexus is a production-ready **Model Context Protocol (MCP) server** that brings AI-powered web search directly into your development environment. Get intelligent search results with proper citations in **Claude Desktop**, **Cursor**, or any MCP-compatible client - all with a single command.
+
+### Why Nexus?
+
+- **🎯 Zero Setup**: Ready in 30 seconds with `npx` - no installation, no configuration
+- **🧠 AI-Powered**: Uses Perplexity Sonar models for intelligent, current web search
+- **📚 Source Citations**: Get authoritative sources with every search result
+- **🔧 Developer-First**: Built for developers who want AI capabilities without complexity
+- **⚡ Production-Ready**: Enterprise-grade reliability with comprehensive error handling
+
+## ✨ Features
+
+<table>
+<tr>
+<td width="50%">
+
+### 🚀 **Zero-Install Simplicity**
+
+- Ready in 30 seconds with `npx`
+- No dependencies or build steps
+- Cross-platform compatibility
+- Always up-to-date
+
+### 🧠 **AI-Powered Intelligence**
+
+- Perplexity Sonar model integration
+- Real-time web content search
+- Context-aware result ranking
+- Multiple model options
+
+</td>
+<td width="50%">
+
+### 📚 **Professional Quality**
+
+- Source citations and metadata
+- Comprehensive error handling
+- Production-grade reliability
+- TypeScript implementation
+
+### 🔧 **Developer Experience**
+
+- MCP protocol compliance
+- Extensive documentation
+- Configurable parameters
+- Community support
+
+</td>
+</tr>
+</table>
+
+## 🏃‍♂️ Quick Start
+
+**🚀 Zero-install setup - Ready in 30 seconds!**
+
+### Prerequisites
+
+- Node.js 16 or higher
+- An OpenRouter API key (get one at [OpenRouter](https://openrouter.ai))
+
+### Zero-Config Installation
+
+No build steps, no dependencies, no setup required:
+
+```bash
+# Set your OpenRouter API key
+export OPENROUTER_API_KEY=your-api-key-here
+
+# Run the server instantly
+npx nexus-mcp --stdio
+```
+
+That's it! The server is now running and ready for MCP client connections.
+
+### Testing the NPX Installation
+
+```bash
+# Test the CLI help
+npx nexus-mcp --help
+
+# Test the version
+npx nexus-mcp --version
+
+# Run with your API key
+OPENROUTER_API_KEY=your-key npx nexus-mcp --stdio
+```
+
+## Alternative: Local Development Installation
+
+For local development or customization:
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/your-username/nexus-mcp.git
+cd nexus-mcp
+```
+
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Build the server:
+
+```bash
+npm run build
+```
+
+4. Configure your OpenRouter API key:
+
+```bash
+# Copy the example environment file
+cp .env.example .env
+
+# Edit .env and add your actual API key
+# OPENROUTER_API_KEY=your-api-key-here
+```
+
+5. Test the server:
+
+```bash
+npm start
+```
+
+## Integration with MCP Clients
+
+### 🚀 Quick Setup with NPX (Recommended)
+
+The easiest way to integrate with any MCP client is using NPX:
+
+### Claude Code
+
+Add this server to your Claude Code MCP settings:
+
+1. Open your MCP settings file (usually `~/.claude/mcp_settings.json`)
+
+2. Add the server configuration using NPX:
+
+```json
+{
+  "mcpServers": {
+    "nexus": {
+      "command": "npx",
+      "args": ["nexus-mcp", "--stdio"],
+      "env": {
+        "OPENROUTER_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+3. Restart Claude Code
+
+**That's it!** No installation, no build steps, no path configuration required.
+
+### Cursor
+
+Configure the server in Cursor's MCP settings:
+
+1. Open Cursor settings and navigate to MCP servers
+
+2. Add a new server with:
+
+   - **Name**: `nexus`
+   - **Command**: `npx`
+   - **Args**: `["nexus-mcp", "--stdio"]`
+   - **Environment Variables**:
+     - `OPENROUTER_API_KEY`: `your-api-key-here`
+
+3. Restart Cursor
+
+### Other MCP Clients
+
+For any MCP-compatible client, use these connection details:
+
+- **Transport**: stdio
+- **Command**: `npx`
+- **Args**: `["nexus-mcp", "--stdio"]`
+- **Environment Variables**: `OPENROUTER_API_KEY=your-api-key-here`
+
+### Alternative: Local Installation
+
+If you prefer using a local installation (after following the local development setup):
+
+```json
+{
+  "mcpServers": {
+    "nexus": {
+      "command": "node",
+      "args": ["/path/to/nexus-mcp/dist/cli.js", "--stdio"],
+      "env": {
+        "OPENROUTER_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+Once integrated, you can use the search tool in your MCP client:
+
+### Basic Search
+
+```
+Use the search tool to find information about "latest developments in AI"
+```
+
+### Advanced Search with Parameters
+
+```
+Search for "climate change solutions" using:
+- Model: perplexity/sonar
+- Max tokens: 2000
+- Temperature: 0.3
+```
+
+## Available Tools
+
+### `search`
+
+The main search tool that provides AI-powered web search capabilities.
+
+**Parameters:**
+
+- `query` (required): Search query (1-2000 characters)
+- `model` (optional): Perplexity model to use (default: "perplexity/sonar")
+- `maxTokens` (optional): Maximum response tokens (1-4000, default: 1000)
+- `temperature` (optional): Response randomness (0-2, default: 0.7)
+
+**Example Response:**
+
+```
+Based on current information, here are the latest developments in AI...
+
+[Detailed AI-generated response with current information]
+
+---
+**Search Metadata:**
+- Model: perplexity/sonar
+- Response time: 1250ms
+- Tokens used: 850
+- Sources: 5 found
+```
+
+## Configuration
+
+### Environment Variables
+
+- `OPENROUTER_API_KEY` (required): Your OpenRouter API key
+- `NODE_ENV` (optional): Environment setting (development, production, test)
+- `LOG_LEVEL` (optional): Logging level (debug, info, warn, error)
+
+### Advanced Configuration
+
+The server supports additional configuration through environment variables:
+
+- `OPENROUTER_TIMEOUT_MS`: Request timeout in milliseconds (default: 30000)
+- `OPENROUTER_MAX_RETRIES`: Maximum retry attempts (default: 3)
+- `OPENROUTER_BASE_URL`: Custom OpenRouter API base URL
+
+## Resources
+
+The server provides a configuration status resource at `config://status` that shows:
+
+- Server health status
+- Configuration information (with masked API key)
+- Search tool availability
+- Server uptime and version
+
+## Troubleshooting
+
+### NPX-Specific Issues
+
+**"npx: command not found"**
+
+- Ensure Node.js 16+ is installed: `node --version`
+- Update npm: `npm install -g npm@latest`
+
+**"Cannot find package 'nexus-mcp'"**
+
+- The package may not be published yet. Use local installation instead
+- Verify network connectivity for npm registry access
+
+**NPX takes a long time to start**
+
+- This is normal on first run as NPX downloads the package
+- Subsequent runs will be faster due to caching
+- For faster startup, use local installation instead
+
+**"Permission denied" errors with NPX**
+
+- Try: `npx --yes nexus-mcp --stdio`
+- Or set npm permissions: `npm config set user 0 && npm config set unsafe-perm true`
+
+### Common Issues
+
+**"Search functionality is not available"**
+
+- Ensure `OPENROUTER_API_KEY` environment variable is set
+- Verify your API key is valid at [OpenRouter](https://openrouter.ai)
+- Check the server logs for initialization errors
+
+**"Authentication failed: Invalid API key"**
+
+- Double-check your API key format and validity
+- Ensure the key has sufficient credits/permissions
+- Test the key directly at OpenRouter dashboard
+
+**"Rate limit exceeded"**
+
+- Wait for the rate limit to reset (usually 1 minute)
+- Consider upgrading your OpenRouter plan for higher limits
+- Monitor usage in your OpenRouter dashboard
+
+**Connection timeouts**
+
+- Check your internet connection
+- The server will automatically retry failed requests
+- Increase timeout if needed: `OPENROUTER_TIMEOUT_MS=60000`
+
+**MCP client can't connect to server**
+
+- Verify the `--stdio` flag is included in your MCP configuration
+- Check that Node.js 16+ is available in your MCP client's environment
+- Ensure the API key is properly set in the environment variables
+
+### Debug Logging
+
+Enable debug logging by:
+
+**For local development:** Add `LOG_LEVEL=debug` to your `.env` file
+
+**For MCP clients:** Add `LOG_LEVEL: "debug"` to the `env` section of your MCP configuration
+
+This will provide detailed information about:
+
+- Configuration loading
+- API requests and responses
+- Error details and stack traces
+- Performance metrics
+
+### Testing Connection
+
+You can test if the server is working by checking the configuration status resource in your MCP client, or by running a simple search query.
+
+## Development
+
+For developers working on this server:
+
+```bash
+# Development with hot reload
+npm run dev
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+## 💰 API Credits and Costs
+
+This server uses OpenRouter's API, which charges based on token usage:
+
+- **Perplexity Sonar models**: Check current pricing at [OpenRouter Models](https://openrouter.ai/models)
+- **Usage monitoring**: Track consumption through the OpenRouter dashboard
+- **Cost control**: Set usage limits in your OpenRouter account
+- **Optimization**: Nexus includes built-in rate limiting and intelligent caching
+
+## 📚 Documentation
+
+<div align="center">
+
+| 📖 **Guide**        | 🔗 **Link**                                 | 📝 **Description**               |
+| ------------------- | ------------------------------------------- | -------------------------------- |
+| **Quick Start**     | [Getting Started](#-quick-start)            | Zero-install setup in 30 seconds |
+| **API Reference**   | [MCP Tools](CLAUDE.md#development-commands) | Complete command reference       |
+| **Configuration**   | [Environment Setup](#configuration)         | Advanced configuration options   |
+| **Contributing**    | [Contributing Guide](CONTRIBUTING.md)       | Join our open source community   |
+| **Troubleshooting** | [Common Issues](#troubleshooting)           | Solutions to common problems     |
+
+</div>
+
+## 🤝 Contributing
+
+We welcome contributions from developers of all experience levels!
+
+<table>
+<tr>
+<td width="33%">
+
+### 🚀 **Get Started**
+
+- Fork the repository
+- Read our [Contributing Guide](CONTRIBUTING.md)
+- Check out [good first issues](https://github.com/search?q=repo%3Anexus-mcp+label%3A%22good+first+issue%22&type=issues)
+
+</td>
+<td width="33%">
+
+### 🐛 **Report Issues**
+
+- [Bug Reports](https://github.com/nexus-mcp/issues/new?template=bug_report.yml)
+- [Feature Requests](https://github.com/nexus-mcp/issues/new?template=feature_request.yml)
+- [Ask Questions](https://github.com/nexus-mcp/issues/new?template=question.yml)
+
+</td>
+<td width="33%">
+
+### 💬 **Join Community**
+
+- [GitHub Discussions](https://github.com/nexus-mcp/discussions)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Roadmap & Project Board](https://github.com/nexus-mcp/projects)
+
+</td>
+</tr>
+</table>
+
+### 🌟 Recognition
+
+Contributors are recognized in our:
+
+- [Contributors list](https://github.com/nexus-mcp/graphs/contributors)
+- Release notes for significant contributions
+- Community spotlights and testimonials
+
+## 🔗 Related Projects
+
+- [Model Context Protocol](https://modelcontextprotocol.io) - The standard we implement
+- [OpenRouter](https://openrouter.ai) - Our AI model provider
+- [Claude Desktop](https://claude.ai) - Primary MCP client
+- [Cursor](https://cursor.sh) - AI-powered code editor with MCP support
+
+## 📞 Support & Community
+
+<div align="center">
+
+| 💬 **Need Help?**    | 🔗 **Resource**                                                                                      |
+| -------------------- | ---------------------------------------------------------------------------------------------------- |
+| **Quick Questions**  | [GitHub Discussions](https://github.com/nexus-mcp/discussions)                                       |
+| **Bug Reports**      | [GitHub Issues](https://github.com/nexus-mcp/issues)                                                 |
+| **Documentation**    | [OpenRouter Docs](https://openrouter.ai/docs) • [MCP Specification](https://modelcontextprotocol.io) |
+| **Feature Requests** | [Enhancement Proposals](https://github.com/nexus-mcp/issues/new?template=feature_request.yml)        |
+
+</div>
+
+## 📄 License
+
+**MIT License** - see [LICENSE](LICENSE) file for details.
+
+---
+
+<div align="center">
+
+**Made with ❤️ by the open source community**
+
+[⭐ Star us on GitHub](https://github.com/nexus-mcp) • [📦 View on NPM](https://www.npmjs.com/package/nexus-mcp) • [📚 Read the Docs](CLAUDE.md)
+
+_Nexus: AI integration without the complexity_
+
+</div>

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { createServer } from './index.js';
+function printUsage() {
+    console.log(`
+Usage: nexus [options]
+
+Nexus MCP Server - Intelligent AI model search and discovery
+
+Options:
+  --stdio     Use STDIO transport (required for MCP clients)
+  --help      Show this help message
+  --version   Show version information
+
+Environment Variables:
+  OPENROUTER_API_KEY    OpenRouter API key (required)
+  NODE_ENV             Environment (development, production, test)
+
+Examples:
+  npx nexus-mcp --stdio
+  nexus --stdio
+`);
+}
+function printVersion() {
+    console.log(`nexus-mcp v1.0.0`);
+}
+async function main() {
+    try {
+        const { values } = parseArgs({
+            args: process.argv.slice(2),
+            options: {
+                stdio: {
+                    type: 'boolean',
+                    default: false,
+                },
+                help: {
+                    type: 'boolean',
+                    default: false,
+                },
+                version: {
+                    type: 'boolean',
+                    default: false,
+                },
+            },
+            allowPositionals: true,
+        });
+        if (values.help) {
+            printUsage();
+            process.exit(0);
+        }
+        if (values.version) {
+            printVersion();
+            process.exit(0);
+        }
+        if (!values.stdio) {
+            console.error('Error: --stdio flag is required for MCP server operation');
+            printUsage();
+            process.exit(1);
+        }
+        // Check for required environment variables
+        if (!process.env.OPENROUTER_API_KEY) {
+            console.error('Error: OPENROUTER_API_KEY environment variable is required');
+            console.error('Please set your OpenRouter API key:');
+            console.error('  export OPENROUTER_API_KEY=your_api_key_here');
+            process.exit(1);
+        }
+        // Set default environment if not specified
+        if (!process.env.NODE_ENV) {
+            process.env.NODE_ENV = 'production';
+        }
+        // Start the MCP server
+        await createServer();
+    }
+    catch (error) {
+        console.error('Failed to start Nexus MCP server:', error);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,SAAS,UAAU;IACjB,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;CAiBb,CAAC,CAAC;AACH,CAAC;AAED,SAAS,YAAY;IACnB,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAClC,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;YAC3B,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;YAC3B,OAAO,EAAE;gBACP,KAAK,EAAE;oBACL,IAAI,EAAE,SAAS;oBACf,OAAO,EAAE,KAAK;iBACf;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,SAAS;oBACf,OAAO,EAAE,KAAK;iBACf;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,SAAS;oBACf,OAAO,EAAE,KAAK;iBACf;aACF;YACD,gBAAgB,EAAE,IAAI;SACvB,CAAC,CAAC;QAEH,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAChB,UAAU,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,YAAY,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAClB,OAAO,CAAC,KAAK,CAAC,0DAA0D,CAAC,CAAC;YAC1E,UAAU,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,2CAA2C;QAC3C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,CAAC;YACpC,OAAO,CAAC,KAAK,CACX,4DAA4D,CAC7D,CAAC;YACF,OAAO,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;YACrD,OAAO,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;YAC/D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,2CAA2C;QAC3C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC1B,OAAO,CAAC,GAAG,CAAC,QAAQ,GAAG,YAAY,CAAC;QACtC,CAAC;QAED,uBAAuB;QACvB,MAAM,YAAY,EAAE,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,mCAAmC,EAAE,KAAK,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}

package/dist/clients/index.d.ts

@@ -0,0 +1,2 @@
+export * from './openrouter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/clients/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/clients/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/clients/index.js

@@ -0,0 +1,2 @@
+export * from './openrouter.js';
+//# sourceMappingURL=index.js.map

package/dist/clients/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/clients/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/clients/openrouter.d.ts

@@ -0,0 +1,101 @@
+import type { ChatCompletionRequest, ChatCompletionResponse, ChatCompletionChunk } from '../types/openrouter.js';
+export interface OpenRouterClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    userAgent?: string;
+    maxRetries?: number;
+    retryDelay?: number;
+}
+export interface RetryConfig {
+    maxRetries: number;
+    retryDelay: number;
+    retryableStatusCodes: number[];
+}
+export declare class OpenRouterClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly defaultHeaders;
+    private readonly retryConfig;
+    constructor(config: OpenRouterClientConfig);
+    /**
+     * Validate API key format
+     */
+    private validateApiKey;
+    /**
+     * Sleep for a given amount of time
+     */
+    private sleep;
+    /**
+     * Calculate exponential backoff delay
+     */
+    private calculateBackoffDelay;
+    /**
+     * Check if an error is retryable
+     */
+    private isRetryableError;
+    /**
+     * Make authenticated HTTP request to OpenRouter API with retry logic
+     */
+    makeRequest<T>(endpoint: string, options?: RequestInit): Promise<T>;
+    /**
+     * Set custom headers for requests
+     */
+    setHeaders(headers: Record<string, string>): void;
+    /**
+     * Get current headers
+     */
+    getHeaders(): Record<string, string>;
+    /**
+     * Test API connection and authentication
+     */
+    testConnection(): Promise<boolean>;
+    /**
+     * Create a chat completion using the OpenRouter API
+     */
+    chatCompletions(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
+    /**
+     * Create a streaming chat completion using the OpenRouter API
+     * Returns an async generator that yields chat completion chunks
+     */
+    chatCompletionsStream(request: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown>;
+}
+/**
+ * Base error class for OpenRouter API errors
+ */
+export declare class OpenRouterApiError extends Error {
+    readonly statusCode: number;
+    readonly type: string;
+    readonly code: number;
+    constructor(message: string, statusCode: number, type: string, code: number);
+    isRateLimitError(): boolean;
+    isAuthenticationError(): boolean;
+    isServerError(): boolean;
+}
+/**
+ * Authentication error class
+ */
+export declare class AuthenticationError extends OpenRouterApiError {
+    constructor(message: string, statusCode?: number, code?: number);
+}
+/**
+ * Rate limit error class
+ */
+export declare class RateLimitError extends OpenRouterApiError {
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, retryAfter?: number | undefined, statusCode?: number, code?: number);
+}
+/**
+ * Server error class for 5xx status codes
+ */
+export declare class ServerError extends OpenRouterApiError {
+    constructor(message: string, statusCode: number, code: number);
+}
+/**
+ * Generic API error class for 4xx client errors
+ */
+export declare class ClientError extends OpenRouterApiError {
+    constructor(message: string, statusCode: number, type: string, code: number);
+}
+//# sourceMappingURL=openrouter.d.ts.map