isc-playbook-mcp-server 0.1.0

MCP server for searching and browsing the IBM ISC Playbook with hybrid search capabilities

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 [e-mail]: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 ([e-mail])

Last Updated

November 12, 2025