Bibliomantic MCP Server

# Implementation Summary ## Project Overview The Bibliomantic MCP Server is a Model Context Protocol implementation that integrates I Ching divination with AI responses, following the bibliomantic approach described in Philip K. Dick's "The Man in the High Castle." ## Technical Architecture ### Core Components **I Ching System (`iching.py`)** - Complete 64-hexagram database with traditional names and interpretations - Three-coin method simulation using cryptographically secure randomness - Flexible hexagram generation with proper yin/yang line creation - Formatted output optimized for AI integration **Bibliomantic Logic (`divination.py`)** - Query augmentation system that integrates I Ching wisdom with user questions - Input validation and comprehensive error handling - Metadata tracking for transparency in divination process - Graceful degradation when divination operations fail **FastMCP Server (`bibliomantic_fastmcp_ethical.py`)** - Official MCP SDK implementation using FastMCP framework - Tools for interactive divination and consultation functions - Resources for direct hexagram database access and AI context loading - Prompt templates for structured philosophical exploration - Comprehensive ethical safeguards in all user-facing responses ### MCP Implementation Features **Tools** - `i_ching_divination`: Generate random hexagrams with optional query context - `bibliomantic_consultation`: Full bibliomantic process with query augmentation - `get_hexagram_details`: Lookup specific hexagrams by number (1-64) - `server_statistics`: System information and capabilities overview **Resources** - `hexagram://{number}`: Individual hexagram data for AI context loading - `iching://database`: Complete 64-hexagram database overview **Prompts** - `career_guidance_prompt`: Structured career consultation templates - `creative_guidance_prompt`: Creative project guidance templates - `general_guidance_prompt`: Universal life guidance templates ## Design Decisions ### Randomness Generation Uses Python's `secrets` module for cryptographically secure randomness to provide authentic bibliomantic authenticity while maintaining technical transparency. ### FastMCP Framework Adoption Migrated from custom MCP implementation to official FastMCP framework for: - Professional protocol compliance - Automatic JSON schema generation - Built-in development tools (MCP Inspector) - Reduced boilerplate code (90% reduction) - Enhanced type safety ### Ethical Framework Integration Implements user-facing ethical disclaimers in all MCP responses to ensure end users understand the system's nature and limitations, addressing responsibility concerns for divination-based AI tools. ### Cultural Approach Treats I Ching as philosophical tradition rather than supernatural system, providing educational context about ancient Chinese wisdom while respecting cultural origins. ## File Structure ``` bibliomantic-mcp-server/ ├── bibliomantic_fastmcp_ethical.py # Main FastMCP server implementation ├── bibliomantic_server.py # Package entry point ├── iching.py # I Ching hexagram database and logic ├── divination.py # Bibliomantic divination system ├── __init__.py # Package initialization ├── requirements.txt # Python dependencies ├── pyproject.toml # Modern Python packaging ├── LICENSE # MIT license ├── README.md # Project documentation └── docs/ ├── ETHICAL_SAFEGUARDS.md # Ethical framework documentation └── IMPLEMENTATION_SUMMARY.md # This document ``` ## Dependencies **Core Requirements** - `mcp[cli]>=1.9.0`: Official MCP Python SDK with CLI tools - Python 3.8+: For modern async/await support **Removed Dependencies** Previous custom implementation required FastAPI, uvicorn, httpx, and custom HTTP client infrastructure. FastMCP framework eliminates these dependencies. ## Usage Patterns ### Installation Methods - `uvx bibliomantic-mcp-server`: Recommended installation method - `pip install bibliomantic-mcp-server`: Alternative installation - Direct execution: `python bibliomantic_server.py` ### Claude Desktop Integration Standard MCP server configuration with stdio transport for seamless integration with Claude Desktop and other MCP-compatible hosts. ### Development Workflow - `mcp dev bibliomantic_server.py`: Built-in MCP Inspector for testing - Type-safe implementation with automatic schema validation - Professional error handling with proper MCP error responses ## Quality Assurance ### Testing Strategy - FastMCP migration verification ensures all components function correctly - MCP Inspector provides interactive testing of tools, resources, and prompts - Type safety with automatic JSON schema generation prevents malformed requests ### Code Quality - Full type hints throughout codebase - Comprehensive documentation and inline comments - Professional error handling and logging - Adherence to MCP best practices and security guidelines ## Educational Framework ### Learning Objectives - Understanding ancient Chinese philosophical traditions - Exploring Philip K. Dick's literary themes and bibliomantic concepts - Demonstrating MCP server development with cultural content - Bridging traditional wisdom systems with modern AI capabilities ### Cultural Sensitivity - Respectful treatment of I Ching as philosophical system - Educational context provided for all consultations - Emphasis on pattern recognition and reflection rather than prediction - Clear attribution to traditional sources and cultural origins ## Future Enhancements Potential improvements include hexagram visualization resources, multi-language interpretation support, advanced prompt templates for specialized consultation types, and expanded educational materials about I Ching philosophy and Philip K. Dick's literary contributions. ## Conclusion The implementation successfully demonstrates how traditional wisdom systems can be thoughtfully integrated with modern AI through professional MCP server development, maintaining both technical excellence and cultural sensitivity while providing clear ethical boundaries for responsible use.