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:

chmod +x scripts/install.sh
./scripts/install.sh

Windows:

scripts\install.bat

GitBook Setup

1. Get API Token

1. Go to GitBook Developer Settings
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
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:

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:

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

// 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

// 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

// 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

npm run build

Development Mode

npm run dev

Testing

Test the server directly:

# 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