npm package: @pepperi-addons/pepperi-apidesign-mcp
Description: MCP server for Pepperi API documentation with intelligent search and query optimization
Author: Pepperi Team
Latest version: 1.0.5

# Pepperi API Design MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to Pepperi API documentation hosted on GitBook. This server enables AI assistants to search, retrieve, and analyze Pepperi's API design information programmatically with intelligent query processing and progressive search capabilities.

## Overview

This MCP server connects to GitBook's API to provide structured access to Pepperi's API documentation. It features intelligent search with stopword processing, progressive query strategies, and optional AI fallback for comprehensive documentation discovery across multiple GitBook spaces.

## Available Tools

### **`search_content`**
Primary search tool for finding documentation across all spaces with intelligent query processing.
- **Organization-Wide Search**: Efficiently searches across all spaces in an organization simultaneously
- **Query Processing**: Automatic stopword removal and query optimization
- **Progressive Search**: Multiple search strategies with fallback mechanisms
- **AI Fallback**: Optional AI-powered search when regular search returns no results
- **Context Preservation**: Results include `_spaceContext.spaceId` for follow-up content retrieval
- **Use Cases**: Find API endpoints, search for PNS information, locate specific documentation

### **`get_content`** 
Retrieve specific documentation content by page ID or path.
- **Methods**: `page_id`, `page_path`
- **Formats**: `document`, `markdown`
- **Requirements**: Must provide `spaceId` from `search_content` results or `manage_documentation`
- **Use Cases**: Get detailed page content, retrieve specific API documentation sections

### **`manage_documentation`**
Comprehensive documentation management for organizations, spaces, and content structure.
- **Actions**: `organizations`, `spaces`, `space_details`, `content_structure`
- **Use Cases**: Discover available spaces, get organization structure, explore content hierarchy

### **`manage_resources`**
Resource management for collections, files, and workspace assets.
- **Actions**: `collections`, `collection_details`, `collection_spaces`, `space_files`, `file_details`
- **Use Cases**: Browse collections, access file metadata, manage workspace resources

## Installation

### Quick Install (Recommended)

Use the provided installation scripts for automatic setup:

**Linux/macOS:**
```bash
chmod +x scripts/install.sh
./scripts/install.sh
```

**Windows:**
```cmd
scripts\install.bat
```

## GitBook Setup

### 1. Get API Token

1. Go to [GitBook Developer Settings](https://app.gitbook.com/account/developer)
2. Click **"Create new token"**
3. Give it a descriptive name (e.g., "Pepperi MCP Server")
4. Copy the generated token (starts with `gb_api_`)

### 2. Get Organization ID

1. Go to [app.gitbook.com](https://app.gitbook.com)
2. Click on your profile/avatar in the top right
3. Select the organization you want to use
4. Look at the URL - it will be: `https://app.gitbook.com/o/{ORGANIZATION_ID}/`
5. Copy the `ORGANIZATION_ID` from the URL

### 3. Environment Configuration

Create a `.env` file with your credentials:

```env
GITBOOK_API_TOKEN=gb_api_your_token_here
GITBOOK_ORGANIZATION_ID=your_organization_id_here
ENABLE_AI_FALLBACK=false
```

### Environment Variables

- **`GITBOOK_API_TOKEN`** (required): Your GitBook API token
- **`GITBOOK_ORGANIZATION_ID`** (required): Your GitBook organization ID
- **`ENABLE_AI_FALLBACK`** (optional): Enable AI-powered fallback search when regular search returns no results (default: `false`)

## MCP Configuration

After running the installation script, a `mcp-config.json` file will be created in your project directory. This file contains a complete MCP server configuration with the exact installation path, ready to be copied to your MCP client configuration.

**Sample generated configuration:**
```json
{
  "mcpServers": {
    "pepperi-apidesign": {
      "command": "npx",
      "args": [
        "@pepperi-addons/pepperi-apidesign-mcp@latest"
      ],
      "env": {
        "GITBOOK_API_TOKEN": "your_gitbook_api_token_here",
        "GITBOOK_ORGANIZATION_ID": "your_organization_id_here",
        "ENABLE_AI_FALLBACK": "false"
      }
    }
  }
}
```

Simply update the environment variables with your actual GitBook credentials and copy this configuration to your MCP client.

## Usage Examples

### Search for Documentation
```typescript
// Search for PNS (Pepperi Notification Service) information
await mcpClient.callTool('search_content', {
  query: 'PNS subscription',
  maxResults: 10
});

// Search for API endpoints
await mcpClient.callTool('search_content', {
  query: 'API authentication OAuth',
  maxResults: 5
});
```

### Get Organization Structure
```typescript
// List all organizations
await mcpClient.callTool('manage_documentation', {
  action: 'organizations'
});

// Get spaces in an organization
await mcpClient.callTool('manage_documentation', {
  action: 'spaces',
  organizationId: 'your-org-id'
});
```

### Retrieve Specific Content
```typescript
// Get page content by ID (using spaceId from search results)
await mcpClient.callTool('get_content', {
  method: 'page_id',
  pageId: 'page-uuid-from-search',
  spaceId: 'space-id-from-search-context',
  format: 'markdown'
});

// Get page content by path
await mcpClient.callTool('get_content', {
  method: 'page_path',
  pagePath: 'pepperi-notification-service/subscribe',
  spaceId: 'space-id-from-manage-documentation',
  format: 'document'
});
```

## Features

### **Intelligent Search Processing**
Advanced query processing with multiple fallback strategies:
- **Organization-First Strategy** - Primary search uses efficient organization-wide API calls
- **Stopword Removal** - Automatic filtering of common words that dilute search effectiveness
- **Progressive Search** - Multiple search strategies including keyword extraction, stemming, and acronym detection
- **AI Fallback** - Optional AI-powered search when regular search returns no results
- **Query Optimization** - Prescriptive tool descriptions guide AI models to use focused technical terms

### **Read-Only Operations**
All tools are designed as read-only operations with built-in caching for optimal performance:
- **Safe to use** - No data modification capabilities
- **Idempotent** - Safe to call multiple times
- **Cached responses** - 5-minute TTL for improved performance

### **Organization-Wide Search**
- **Efficient Search**: Single API call searches across all spaces in an organization
- **Context Preservation**: Results include `_spaceContext` with space ID and name
- **Unified Results**: Aggregated results from multiple spaces with clear space identification
- **Performance Optimized**: Much faster than individual space searches

### **Flexible Content Access**
- Retrieve content by page ID or path with required space context
- Support for multiple output formats (JSON document, Markdown)
- Comprehensive resource and collection management

## Development

### Project Structure
```
src/
├── server/          # MCP server implementation with tool definitions
├── services/        # GitBook API client and service layer
├── types/           # TypeScript type definitions and interfaces
├── utils/           # Configuration, logging, and stopword query processor
└── index.ts         # Entry point with graceful shutdown handling
```

### Building
```bash
npm run build
```

### Development Mode
```bash
npm run dev
```

### Testing
Test the server directly:
```bash
# Ensure you have built the project first
npm run build

# Run the test script
node examples/test-mcp-server.js
```

**Note**: The test script requires your GitBook credentials to be set in environment variables or `.env` file. It will use test values if credentials are not provided.

## Troubleshooting

### Common Issues

1. **Authentication Errors**
   ```
   ❌ Please set your GITBOOK_API_TOKEN environment variable
   ```
   - Verify your GitBook API token is valid and properly set
   - Check token permissions include read access to the spaces

2. **Installation Issues**
   - Ensure Node.js version 16+ is installed
   - Run `npm install` to install dependencies
   - Use the provided installation scripts for automated setup