presearch-search-api-mcp

Name: presearch-search-api-mcp
Availability: InStock
Author: NosytLabs

The presearch-search-api is an API designed to leverage the search capabilities of the Presearch platform. By using this API, developers can retrieve search results and integrate them into their applications. Implemented in TypeScript, it is designed with usability and extensibility in mind.

GitHub

GitHub Stars

User Rating

Not Rated

Favorites

Views

Forks

Issues

README

Presearch MCP Server

Production-Ready Model Context Protocol Server for Presearch API

⚠️ Community Project Notice: This is an independent, community-developed MCP server and is not officially affiliated with, endorsed by, or connected to Presearch. It provides access to Presearch's public API through the Model Context Protocol.

📋 Project Overview

The Presearch MCP Server is a fully optimized, production-ready implementation that bridges the Model Context Protocol (MCP) with Presearch's powerful search engine. This server enables seamless integration of Presearch's capabilities into MCP-compatible applications, providing developers and users with access to high-quality, privacy-focused search results.

Key Highlights:

Production Ready: Fully tested and optimized for production deployments
MCP Compliant: Complete adherence to Model Context Protocol specifications
Enhanced Security: Advanced security features including JWT authentication and HTTPS enforcement
Performance Optimized: In-memory caching, request optimization, and efficient resource management
Smithery.ai Integration: Ready for deployment on the Smithery.ai platform
Comprehensive Testing: 100% test coverage with real API validation

✨ Features

🔍 Core Search Functionality

Advanced Search API Integration: Direct connection to Presearch's official API endpoint
Comprehensive Parameter Support: Query, pagination, country/language filters, time ranges, safe search, and freshness controls
Real-time Results: Access to Presearch's high-quality search index with up-to-date information
Multi-format Export: JSON, CSV, Markdown export capabilities

🛠️ MCP Protocol Implementation

Full MCP Compliance: Implements all required MCP tools and protocols
Tool Ecosystem: Six specialized tools for search, export, scraping, caching, and health monitoring
Seamless Integration: Compatible with Claude Desktop, VS Code, and other MCP clients
Protocol Version: Supports latest MCP specifications

🔒 Enterprise-Grade Security

JWT Authentication: Secure API key management with Bearer token validation
HTTPS Enforcement: All communications encrypted and secure
Input Validation: Comprehensive parameter validation using Zod schemas
Error Handling: Secure error responses without sensitive data exposure
Rate Limiting: Built-in protection against abuse

⚡ Performance & Reliability

Intelligent Caching: 5-minute TTL in-memory caching for improved response times
Request Optimization: Efficient API calls with automatic retry mechanisms
Memory Management: Automatic cache cleanup and resource optimization
Health Monitoring: Built-in system health checks and diagnostics
Scalability: Designed for horizontal scaling and high-load scenarios

🚀 Deployment Flexibility

Smithery.ai Ready: Optimized for Smithery.ai platform deployment
Docker Support: Containerized deployment with Docker and Docker Compose
Cloud Native: Compatible with AWS, Heroku, and other cloud platforms
Local Development: Easy setup for development and testing environments

📦 Installation

Prerequisites

Node.js: Version 18.0 or higher
NPM: Latest version recommended
Presearch API Key: Valid API key from Presearch Search API
Network: HTTPS connectivity for API calls

Quick Install

# Clone the repository
git clone https://github.com/NosytLabs/presearch-search-api-mcp.git
cd presearch-search-api-mcp

# Install dependencies
npm install

# Verify installation
npm test

Alternative Installation Methods

# Install via NPM (when published)
npm install -g presearch-mcp-server

# Or install from source
npm install https://github.com/NosytLabs/presearch-search-api-mcp.git

⚙️ Configuration

Environment Variables

Create a .env file in your project root with the following variables:

# Required: Your Presearch API key
PRESEARCH_API_KEY=your_api_key_here

# Optional: Application configuration
NODE_ENV=production
LOG_LEVEL=info
CACHE_TTL=3600000
PORT=3000
HOST=0.0.0.0

# Optional: Monitoring and metrics
METRICS_ENABLED=true
HEALTH_CHECK_INTERVAL=30000

Configuration Options

Variable	Default	Description
`PRESEARCH_API_KEY`	-	Your Presearch API key (required)
`NODE_ENV`	`development`	Environment mode
`LOG_LEVEL`	`info`	Logging verbosity (error, warn, info, debug)
`CACHE_TTL`	`3600000`	Cache time-to-live in milliseconds
`PORT`	`3000`	Server port
`HOST`	`localhost`	Server host
`METRICS_ENABLED`	`false`	Enable metrics collection
`HEALTH_CHECK_INTERVAL`	`30000`	Health check interval in milliseconds

🚀 Smithery.ai Deployment

The Presearch MCP Server is fully optimized for deployment on Smithery.ai, providing a seamless, managed hosting experience.

Prerequisites

Smithery.ai account
Valid Presearch API key
Smithery configuration file (included)

Deployment Steps

Prepare Configuration

# Ensure smithery.yaml is present in your project root
ls smithery.yaml

Set Environment Variables

# Configure your API key in Smithery.ai dashboard or via CLI
smithery config set PRESEARCH_API_KEY=your_jwt_token_here

Deploy to Smithery.ai

# Deploy using Smithery CLI
smithery deploy

# Or deploy via web interface at smithery.ai

Verify Deployment

# Check deployment status
smithery status

# Test the deployed server
curl https://your-deployment.smithery.ai/health

Smithery.ai Benefits

Managed Hosting: No server management required
Auto-scaling: Automatic scaling based on demand
Monitoring: Built-in monitoring and logging
Security: Enterprise-grade security features
Global CDN: Fast, reliable access worldwide

🛠️ MCP Integration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "presearch": {
      "command": "npx",
      "args": ["presearch-mcp-server"],
      "env": {
        "PRESEARCH_API_KEY": "your_api_key_here"
      }
    }
  }
}

VS Code Extension

{
  "mcp.server.presearch": {
    "command": "npm",
    "args": ["run", "dev"],
    "cwd": "${workspaceFolder}/presearch-mcp-server",
    "env": {
      "PRESEARCH_API_KEY": "${env:PRESEARCH_API_KEY}"
    }
  }
}

Other MCP Clients

The server is compatible with any MCP-compliant client. Refer to your client's documentation for integration instructions.

📖 Usage Examples

Basic Search

// Simple search query
const result = await search({
  query: "artificial intelligence",
  count: 10,
  country: "US"
});

Advanced Search with Filters

// Research query with time and safety filters
const research = await search({
  query: "quantum computing breakthroughs 2024",
  freshness: "py",
  safesearch: "moderate",
  useCache: true
});

Export Results

// Export search results to CSV
const exportData = await export_results({
  query: "renewable energy trends",
  format: "csv",
  count: 50
});

Content Scraping

// Extract content from a web page
const content = await scrape_content({
  url: "https://example.com/article",
  extractText: true,
  extractLinks: true,
  includeMetadata: true
});

🔧 API Reference

Available Tools

`search`

Perform web searches with advanced filtering options.

Parameters:

query (string, required): Search query
count (number, optional): Number of results (1-20, default 10)
offset (number, optional): Pagination offset (default 0)
country (string, optional): Country code (e.g., "US", "GB")
search_lang (string, optional): Search language (e.g., "en", "es")
ui_lang (string, optional): UI language (e.g., "en-US")
safesearch (string, optional): Safe search level ("off", "moderate", "strict")
freshness (string, optional): Time filter ("pd", "pw", "pm", "py")
useCache (boolean, optional): Enable caching

`export_results`

Export search results in multiple formats.

Parameters:

query (string, required): Search query
format (string, optional): Export format ("json", "csv", "markdown")
count (number, optional): Number of results to export
country (string, optional): Country code for search

`scrape_content`

Extract content from web pages.

Parameters:

url (string, required): URL to scrape
extractText (boolean, optional): Extract text content
extractLinks (boolean, optional): Extract links
extractImages (boolean, optional): Extract images
includeMetadata (boolean, optional): Include page metadata

`cache_stats`

View cache statistics and performance metrics.

`cache_clear`

Clear all cached search results.

`health_check`

Perform system health and connectivity checks.

Response Formats

Search Response

{
  "query": "search query",
  "type": "search",
  "web": {
    "results": [
      {
        "title": "Result Title",
        "url": "https://example.com",
        "description": "Result description",
        "rank": 1
      }
    ]
  }
}

Export Response

{
  "format": "csv",
  "data": "title,link,description...",
  "metadata": {
    "query": "search term",
    "timestamp": "2024-01-01T00:00:00Z",
    "totalResults": 50
  }
}

🔧 Troubleshooting

Common Issues

Authentication Errors

Error: 401 Unauthorized

Solutions:

Verify API key in .env file
Ensure valid API key from Presearch
Check account credits and subscription
Confirm API key hasn't expired

Connection Issues

Error: Timeout of 30000ms exceeded

Solutions:

Check internet connectivity
Verify Presearch API accessibility
Adjust timeout settings
Check firewall/proxy configurations

Rate Limiting

Error: 429 Too Many Requests

Solutions:

Implement request throttling
Use exponential backoff
Check API usage limits
Consider plan upgrade

Debugging

# Enable debug logging
DEBUG=* npm start

# Test API connectivity
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://na-us-1.presearch.com/v1/search?q=test"

# Check server health
npm run health-check

🤝 Contribution Guidelines

We welcome contributions to improve the Presearch MCP Server! Please follow these guidelines:

Getting Started

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Make your changes
Run tests: npm test
Submit a pull request

Development Setup

# Install development dependencies
npm install

# Run in development mode
npm run dev

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

Code Standards

JavaScript/Node.js: Follow ESLint configuration
Documentation: Update README for new features
Testing: Add tests for new functionality
Commits: Use conventional commit format

Reporting Issues

Use GitHub Issues for bug reports
Include detailed reproduction steps
Provide environment information
Attach relevant logs

Feature Requests

Check existing issues first
Provide detailed use case
Explain expected behavior
Consider implementation complexity

📊 Testing & Quality Assurance

Test Suite

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test
npm test -- --grep "search functionality"

Test Results

🧪 Presearch MCP Server v1.0 - Test Suite
🔗 Testing against: https://na-us-1.presearch.com/v1/search

📊 TEST SUMMARY
===============
Total Tests: 7
✅ Passed: 7
❌ Failed: 0
Success Rate: 100%

🎉 ALL TESTS PASSED!