Opichi API Helper MCP Server v2.0.0

🚀 NPX-First Design for Non-Technical Users

A Model Context Protocol (MCP) server that provides AI-powered API integration assistance using Perplexity AI. Designed for easy NPX deployment with zero-configuration setup.

✨ What's New in v2.0.0

• 🎯 Zero-Configuration: Works out of the box with just your API key
• 🔧 Self-Healing: Automatic setup and repair capabilities
• 🏥 Health Diagnostics: Built-in troubleshooting tools
• 📋 Auto-Config: Generates MCP client configurations automatically
• 🌍 Cross-Platform: Enhanced Windows, macOS, and Linux support

Features

• 🔍 Smart API Documentation Search: Search and retrieve relevant API documentation using Perplexity's powerful search capabilities
• 📋 Integration Plan Generation: Generate comprehensive, step-by-step integration plans for any API
• 🔧 Error Diagnosis: Analyze integration errors and provide actionable fixes
• 💾 Intelligent Caching: 30-minute TTL cache for search results to improve performance
• 🛡️ Robust Error Handling: Automatic retries on rate limits and server errors
• ⚡ Fast Performance: 10-second timeout with built-in retry logic

📜 Quick Start

1. 🔑 Get Your API Key

Get your Perplexity API key from: https://www.perplexity.ai/settings/api

2. ⚙️ Add to Your MCP Client

For Windsurf:

{
  "mcpServers": {
    "opichi-api-helper": {
      "command": "npx",
      "args": ["-y", "@opichi/mcp-api-helper@latest", "--perplexity-key", "YOUR_API_KEY"]
    }
  }
}

For Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "opichi-api-helper": {
      "command": "npx",
      "args": ["-y", "@opichi/mcp-api-helper@latest", "--perplexity-key", "YOUR_API_KEY"]
    }
  }
}

3. 🎉 That's It!

The first time you run it, NPX will automatically:

• Download and install the package
• Set up the Python environment
• Install all dependencies
• Configure everything for you

🔧 Troubleshooting

If you encounter any issues:

# Run health check
npx @opichi/mcp-api-helper --health-check

# Repair broken installation
npx @opichi/mcp-api-helper --repair

# Generate configuration templates
npx @opichi/mcp-api-helper --generate-config

# Show help
npx @opichi/mcp-api-helper --help
# Run directly with NPX
npx -y @opichi/mcp-api-helper --perplexity-key YOUR_PERPLEXITY_API_KEY

# Or install globally
npm install -g @opichi/mcp-api-helper
mcp-api-helper --perplexity-key YOUR_PERPLEXITY_API_KEY

Manual Installation

Prerequisites

• Python 3.10 or higher
• Perplexity API key (Get one here)
• Node.js 16+ (for NPX usage)

Install Dependencies

pip install -r requirements.txt

Development Installation

pip install -e ".[dev]"

Configuration

Perplexity API Key Setup

You can provide your Perplexity API key in two ways:

Option 1: Command Line Flag

python helper.py --perplexity-key your_perplexity_api_key_here

Option 2: Environment Variable

export PERPLEXITY_API_KEY=your_perplexity_api_key_here
python helper.py

Option 3: .env File

Create a .env file in the project root:

PERPLEXITY_API_KEY=your_perplexity_api_key_here

Usage

Using NPX (Recommended)

# Start the MCP server with NPX
npx -y @opichi/mcp-api-helper --perplexity-key YOUR_PERPLEXITY_API_KEY

# Using environment variable
export PERPLEXITY_API_KEY=YOUR_API_KEY
npx -y @opichi/mcp-api-helper

Manual Usage (Development)

# Navigate to python directory
cd python

# Using command line flag
python helper.py --perplexity-key YOUR_API_KEY

# Using environment variable
export PERPLEXITY_API_KEY=YOUR_API_KEY
python helper.py

Available Tools

1. search_api_docs(query: str, k: int = 8)

Search for API documentation and integration resources.

Parameters:

• query: Search query for API documentation
• k: Number of results to return (default: 8)

Example:

result = await search_api_docs("Stripe payment API authentication", 5)

2. write_integration_plan(api: str, app_context: str)

Generate a comprehensive integration plan for an API.

Parameters:

• api: Name of the API to integrate
• app_context: Context about your application

Example:

result = await write_integration_plan(
    "GitHub API", 
    "Python web application for repository management"
)

3. diagnose_integration_error(error: str, stack: str = None, api: str = None)

Analyze integration errors and get actionable fixes.

Parameters:

• error: Error message or description
• stack: Optional stack trace
• api: Optional API name for context

Example:

result = await diagnose_integration_error(
    "Connection timeout when calling API",
    stack="Traceback (most recent call last)...",
    api="Stripe API"
)

Integration with AI IDEs

Windsurf Integration

Add this to your Windsurf MCP configuration:

{
  "mcpServers": {
    "opichi-api-helper": {
      "command": "python",
      "args": ["/path/to/opichi-api-mcp/helper.py", "--perplexity-key", "YOUR_API_KEY"],
      "cwd": "/path/to/opichi-api-mcp"
    }
  }
}

Or using environment variables:

{
  "mcpServers": {
    "opichi-api-helper": {
      "command": "python",
      "args": ["/path/to/opichi-api-mcp/helper.py"],
      "cwd": "/path/to/opichi-api-mcp",
      "env": {
        "PERPLEXITY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Project Structure

opichi-api-mcp/
├── package.json           # NPM package configuration
├── index.js               # Main Node.js entry point
├── LICENSE                # MIT license
├── README.md              # This file
├── CHANGELOG.md           # Version history
├── windsurf-config-example.json  # Example Windsurf config
├── bin/                   # NPX executable
│   └── mcp-api-helper.js  # Node.js wrapper for Python server
├── python/                # Python MCP server code
│   ├── helper.py          # Main MCP server entry point
│   ├── perplexity.py      # Perplexity API client with caching
│   ├── tools.py           # MCP tool implementations
│   ├── requirements.txt   # Python dependencies
│   ├── pyproject.toml     # Python project configuration
│   ├── venv/              # Python virtual environment
│   ├── prompts/           # AI prompts for tools
│   │   ├── search_api_docs.txt
│   │   ├── integration_plan.txt
│   │   └── diagnose_error.txt
│   ├── plans/             # Generated integration plans
│   └── tests/             # Test suite
│       ├── test_perplexity.py
│       └── test_tools.py
└── docs/                  # Additional documentation
    └── ide-configs.md     # IDE configuration examples

Development

Running Tests

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_perplexity.py

Code Formatting

# Format code with black
black . --line-length 88

# Check formatting
black . --check --line-length 88

Type Checking

The code includes comprehensive type annotations for better development experience.

Error Handling

The server includes robust error handling:

• Network Timeouts: 10-second timeout with automatic retry
• Rate Limiting: Automatic retry on 429 status codes
• Server Errors: Retry on 5xx status codes
• Caching: 30-minute TTL cache to reduce API calls
• Graceful Degradation: Meaningful error messages when services fail

Performance

• Caching: TTL cache with 30-minute expiration
• Connection Pooling: Reuses HTTP connections
• Timeout Management: 10-second timeout prevents hanging
• Retry Logic: Smart retry on transient failures

Troubleshooting

Common Issues

"Command not found" error

Ensure Python 3.10+ is installed and in your PATH.

"No matching distribution" for FastMCP

Check your Python version with python --version. FastMCP requires Python 3.10+.

"API key required" error

Ensure your Perplexity API key is properly set via command line flag or environment variable.

Connection timeout errors

Check your internet connection and Perplexity API status.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Create an issue on GitHub
• Contact: [email protected]

Built with ❤️ by Opichi LLC