npm package: @opichi/mcp-api-helper
Description: MCP server for API integration assistance using Perplexity AI
Author: Opichi LLC
Latest version: 2.0.2

# 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:**
```json
{
  "mcpServers": {
    "opichi-api-helper": {
      "command": "npx",
      "args": ["-y", "@opichi/mcp-api-helper@latest", "--perplexity-key", "YOUR_API_KEY"]
    }
  }
}
```

**For Cursor (.cursor/mcp.json):**
```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:

```bash
# 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](https://docs.perplexity.ai/))
- Node.js 16+ (for NPX usage)

### Install Dependencies

```bash
pip install -r requirements.txt
```

### Development Installation

```bash
pip install -e ".[dev]"
```

## Configuration

### Perplexity API Key Setup

You can provide your Perplexity API key in two ways:

#### Option 1: Command Line Flag
```bash
python helper.py --perplexity-key your_perplexity_api_key_here
```

#### Option 2: Environment Variable
```bash
export PERPLEXITY_API_KEY=your_perplexity_api_key_here
python helper.py
```

#### Option 3: .env File
Create a `.env` file in the project root:
```env
PERPLEXITY_API_KEY=your_perplexity_api_key_here
```

## Usage

### Using NPX (Recommended)

```bash
# 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)

```bash
# 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:**
```python
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:**
```python
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:**
```python
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:

```json
{
  "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:

```json
{
  "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

```bash
# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_perplexity.py
```

### Code Formatting

```bash
# 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: courtney@opichi.com

---

Built with ❤️ by [Opichi LLC](https://opichi.com)