ISC Playbook MCP Server

Model Context Protocol (MCP) server for searching and browsing the IBM ISC Playbook with hybrid search capabilities.

Features

• Hybrid Search: Combines semantic (dense vectors) and keyword (sparse vectors) search using Milvus Lite
• 1,358 Indexed Pages: Complete IBM ISC Playbook content (1,091 documents + 266 folders)
• Natural Language Queries: Search using conversational questions
• GitHub Copilot Integration: Access playbook directly from VS Code

Architecture

• Vector Database: Milvus Lite (embedded, no external service needed)
• Embeddings: sentence-transformers (all-MiniLM-L6-v2, 384-dim)
• Search Algorithm: RRF (Reciprocal Rank Fusion) for result merging
• MCP Framework: FastMCP (Python SDK)

Installation

Option 1: Using uvx (Recommended)

The easiest way to use this MCP server is with uvx:

# Install and run directly with uvx
uvx isc-playbook-mcp-server

Option 2: From PyPI

# Install from PyPI
pip install isc-playbook-mcp-server

# Run the server
isc-playbook-mcp-server

Option 3: From Source (Development)

1. Clone the repository:

   git clone git@github.ibm.com:kirtijha/isc-playbook-mcp-server.git
   cd isc-playbook-mcp-server
   

2. Install with uv:

   uv pip install -e .
   

   Or with pip:

   python -m venv .venv
   source .venv/bin/activate  # On macOS/Linux
   pip install -e .
   

Usage

MCP Server Configuration

Add to your MCP settings file (e.g., ~/.config/mcp/mcp.json or VS Code's MCP settings):

Using uvx (Recommended):

{
  "mcpServers": {
    "isc-playbook": {
      "command": "uvx",
      "args": ["isc-playbook-mcp-server"]
    }
  }
}

Using installed package:

{
  "mcpServers": {
    "isc-playbook": {
      "command": "isc-playbook-mcp-server"
    }
  }
}
}

Available Tools

1. search_playbook: Natural language search across all pages using hybrid search (semantic + keyword)
2. get_document: Retrieve full content of a specific document by URL
3. browse_by_type: List all documents or folders
4. search_by_path: Find documents by navigation path pattern (e.g., "UPX > PRM DevOps")
5. get_related_documents: Find semantically similar documents to a given document
6. get_index_stats: Get statistics about indexed content (total pages, documents, folders)

Example Queries

Natural Language Search:

• "How do I troubleshoot production issues in ISC?"
• "What is the process for onboarding new team members?"
• "How to create and manage Salesforce packages?"
• "Deployment process to staging environment"

Path-based Search:

• "Show me all documents in UPX > PRM DevOps"
• "Find everything under ISC Sales > Development"
• "What's in the Salesforce Admin section?"

Related Documents:

• "Find documents similar to the deployment guide"
• "What else should I read after the onboarding doc?"

Project Structure

playbook-mcp-server/
├── src/
│   ├── server.py           # FastMCP server
│   ├── hybrid_indexer.py   # Milvus Lite hybrid search
│   ├── scraper.py          # Playbook scraper
│   └── cleaner.py          # HTML cleaner
├── data/
│   ├── cleaned/            # Cleaned JSON data
│   └── index/              # Milvus database
├── requirements.txt
└── README.md

Technical Details

• Vocabulary Size: 100K terms for sparse vectors (BM25-like)
• Text Limit: 65,535 characters per document (Milvus VARCHAR limit)
• Preview Size: 1,000 chars in search results, 500 in browse
• Batch Size: 100 documents per indexing batch

Production Ready

✅ Comprehensive data coverage (3.2x more than initial version)
✅ No data loss or unnecessary truncation
✅ Accurate hybrid search with RRF fusion
✅ Error handling and logging
✅ Optimized for performance

License

IBM Internal Use Only

Authors

• Kirti Jha (kirtijha@in.ibm.com)

Last Updated

November 12, 2025