npm package: @feathered_wolf/pae-mcp
Description: MCP server for discovering and querying aggregated API endpoints
Author: Gary Hughes
Latest version: 1.0.0

# PA-Endpoints MCP Server

Model Context Protocol (MCP) server for discovering and querying aggregated API endpoints from multiple Swagger/OpenAPI sources.

[![npm version](https://img.shields.io/npm/v/@feathered_wolf/pae-mcp.svg)](https://www.npmjs.com/package/@feathered_wolf/pae-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

PA-Endpoints MCP Server provides AI agents with tools to:
- **List Services** - Browse all configured API services with metadata
- **Search Endpoints** - Find endpoints using flexible queries across all services
- **Get Details** - Retrieve comprehensive endpoint information including parameters and schemas

Perfect for AI-assisted API discovery, documentation exploration, and integration planning.

## Installation

### Using npx (Recommended)

No installation needed - run directly:

```bash
npx @feathered_wolf/pae-mcp --api-url http://localhost:8080
```

### Global Installation

```bash
npm install -g @feathered_wolf/pae-mcp
```

## Quick Start

1. **Start the PA-Endpoints .NET API** (required):
   ```bash
   cd src/api/PA.Endpoints.Api
   dotnet run
   ```

2. **Run the MCP server**:
   ```bash
   npx @feathered_wolf/pae-mcp --api-url http://localhost:8080
   ```

The server communicates via stdin/stdout following the MCP protocol and can be used with any MCP-compatible client.

## Usage

### Command Line

```bash
pae-mcp [options]
```

**Options:**
- `--api-url <url>` - API base URL (default: http://localhost:8080)
- `--log-level <level>` - Log level: error, warn, info, debug (default: info)
- `--version` - Show version number
- `--help` - Display help information

### Environment Variables

Create a `.env` file:

```env
API_URL=http://localhost:8080
MCP_SERVER_NAME=pae-mcp
LOG_LEVEL=info
```

## Configuration

### Claude Desktop Integration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pa-endpoints": {
      "command": "npx",
      "args": [
        "@feathered_wolf/pae-mcp",
        "--api-url",
        "http://localhost:8080",
        "--log-level",
        "info"
      ]
    }
  }
}
```

## MCP Tools

### list_services

Lists all configured API services or endpoints for a specific service.

**Parameters:**
- `service_id` (optional) - Get endpoints for a specific service
- `tags` (optional, array) - Filter services by tags
- `enabled_only` (optional, boolean, default: true) - Only return enabled services

**Examples:**

List all services:
```json
{
  "name": "list_services",
  "arguments": {}
}
```

Get endpoints for a service:
```json
{
  "name": "list_services",
  "arguments": {
    "service_id": "petstore"
  }
}
```

### search_endpoints

Search for API endpoints across all services using flexible query syntax.

**Parameters:**
- `query` (required, string) - Search keywords, path, or method
- `service_names` (optional, array) - Filter by service names
- `methods` (optional, array) - Filter by HTTP methods (GET, POST, PUT, DELETE, PATCH)
- `limit` (optional, number, default: 50, max: 500) - Maximum results

**Examples:**

Search by keyword:
```json
{
  "name": "search_endpoints",
  "arguments": {
    "query": "user"
  }
}
```

Search with filters:
```json
{
  "name": "search_endpoints",
  "arguments": {
    "query": "order",
    "methods": ["POST", "PUT"],
    "service_names": ["ecommerce-api"],
    "limit": 10
  }
}
```

### get_endpoint_details

Get comprehensive information about a specific endpoint.

**Parameters:**
- `endpoint_id` (required, string) - Unique endpoint identifier (format: service-method-path)
- `include_examples` (optional, boolean, default: true) - Include JSON schema examples

**Example:**

```json
{
  "name": "get_endpoint_details",
  "arguments": {
    "endpoint_id": "petstore-get-/pet/{petId}",
    "include_examples": true
  }
}
```

## Troubleshooting

### Connection Errors

**Error:** `ECONNREFUSED` or `ENOTFOUND`

**Solution:**
1. Verify .NET API is running: `curl http://localhost:8080/api/services`
2. Check API_URL configuration
3. Ensure firewall allows connections

### No Results

**Issue:** Search returns no endpoints

**Solution:**
1. Verify services are configured in API
2. Check API logs for Swagger fetch errors
3. Ensure services are enabled

### Configuration Error

**Error:** `Configuration not initialized`

**Solution:**
- Provide API_URL via `--api-url` flag or `.env` file

## Development

### Prerequisites

- Node.js >=18.0.0
- npm >=9.0.0
- PA-Endpoints .NET API

### Setup

```bash
git clone <repository-url>
cd src/mcp-server
npm install
```

### Build

```bash
npm run build
```

### Test

```bash
# Run all tests
npm test

# Watch mode
npm run test:watch

# Specific test
npm test -- search-endpoints.test.ts
```

### Lint

```bash
npm run lint
```

### Development Mode

```bash
npm run dev
```

### Local Testing

```bash
# Build and link locally
npm run build
npm link

# Test globally
pae-mcp --help
pae-mcp --api-url http://localhost:8080

# Unlink
npm unlink -g @feathered_wolf/pae-mcp
```

## Architecture

```
┌─────────────────┐
│   AI Assistant  │
│  (Claude, etc)  │
└────────┬────────┘
         │ MCP Protocol
         │ (stdin/stdout)
┌────────▼────────┐
│   MCP Server    │
│  (this package) │
├─────────────────┤
│ • list_services │
│ • search        │
│ • get_details   │
└────────┬────────┘
         │ HTTP REST
┌────────▼────────┐
│  PA-Endpoints   │
│    .NET API     │
└─────────────────┘
```

**Components:**
- **Server** - MCP protocol handler and tool registry
- **API Client** - HTTP client with retry logic
- **Tools** - Three endpoint discovery tools
- **Logger** - Winston-based structured logging
- **Errors** - Custom error classes with MCP formatting

## Requirements

- **Runtime:** Node.js >=18.0.0
- **Backend:** PA-Endpoints .NET API (must be running)

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass: `npm test`
5. Follow existing code style: `npm run lint`
6. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- **Issues:** File issues on GitHub
- **Documentation:** See `/docs` directory
- **API Documentation:** http://localhost:8080/swagger (when API running)

---

**Built with [Model Context Protocol](https://modelcontextprotocol.io/)**