PerchIQXSemantic Perch Intelligence MCP

Quick Start ​

# Clone the repository
git clone https://github.com/semanticintent/semantic-perch-intelligence-mcp.git

# Install dependencies
cd semantic-perch-intelligence-mcp
npm install

# Configure your Cloudflare credentials
cp .env.example .env
# Edit .env with your credentials

# Build the MCP server
npm run build

# Start using with Claude Desktop
# Add to your Claude Desktop configuration

What is PerchIQX? ​

PerchIQX (Perch Intelligence Quotient eXtended) is a Model Context Protocol (MCP) server that brings deep database intelligence to your AI assistant. Like a cormorant perched above the water, diving deep to catch fish, PerchIQX dives into your Cloudflare D1 databases to surface the insights you need.

Note: PerchIQX serves as both a practical D1 introspection tool and a reference implementation of the Semantic Intent pattern applied to database intelligence. The codebase demonstrates hexagonal architecture, domain-driven design, and semantic anchoring principles.

Why "Perch"? ​

Perch (cormorant) birds are expert fishers that perch above water, dive deep, and surface with their catch. PerchIQX brings that same precision to database intelligence:

• Perch = observation point above your data
• IQ = Intelligence Quotient
• X = eXtended capabilities

Core Philosophy ​

1. Deep Insights - Comprehensive schema analysis, not surface-level queries
2. Database Intelligence - Semantic understanding of your data model
3. Dive Deep. Surface Smart. - Extract meaningful patterns from complex schemas

Key Features ​

🎯 MCP Tools ​

• Analyze Database Schema - Complete schema introspection with metadata and samples
• Get Table Relationships - Foreign key analysis with cardinality detection
• Validate Database Schema - Check for anti-patterns and schema issues
• Suggest Optimizations - AI-powered recommendations for performance improvements

📡 Cloudflare D1 Integration ​

Direct API integration for:

• Multi-environment support (dev, staging, production)
• Real-time schema analysis
• Complete table and column introspection
• Index and foreign key discovery
• Sample data extraction

🧠 Semantic Intent Pattern ​

Built on research-backed principles:

• Observable property anchoring
• Intent preservation through transformations
• Semantic over structural analysis
• Domain-driven design

Architecture ​

Built on Hexagonal Architecture with clean separation:

┌─────────────────────────────────────────────────────────┐
│                   Presentation Layer                     │
│              (MCP Server - Protocol Handling)            │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                  Application Layer                       │
│        (Use Cases - Schema Analysis Orchestration)      │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                    Domain Layer                          │
│     (Schema Entities, Relationship Logic, Services)     │
│              Pure Business Logic                         │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                Infrastructure Layer                      │
│       (Cloudflare D1 REST API, HTTP Client)             │
│           Technical Adapters                             │
└─────────────────────────────────────────────────────────┘

Use Cases ​

🏗️ Database Development ​

• Schema Design - Understand existing schemas before making changes
• Migration Planning - Identify relationships and dependencies
• Optimization - Find missing indexes and schema improvements
• Documentation - Auto-generate schema documentation

📈 Analytics & Monitoring ​

• Track schema evolution across environments
• Validate schema integrity and best practices
• Monitor relationship complexity
• Detect potential performance bottlenecks

🤖 AI Workflow Integration ​

• Query your database schema via Claude AI
• Natural language database analysis
• Conversational schema exploration
• AI-assisted optimization planning

Documentation ​

• Getting Started - Installation and configuration
• Tools Overview - Complete MCP tool reference
• Architecture - Hexagonal architecture and design patterns
• API Reference - Technical documentation

Community & Support ​

• Repository: github.com/semanticintent/semantic-perch-intelligence-mcp
• Documentation: docs.perchiqx.dev
• Issues: Report bugs and request features
• Discussions: Architecture, patterns, and use cases

About the Author ​

Michael Shatny is a software developer specializing in modernizing legacy systems through agentic UX, AI-powered workflows, and semantic intent patterns. Based in Ontario, Canada, Michael's work bridges practical software development with academic research in AI-assisted development.

Research & Publications ​

• ORCID: 0009-0006-2011-3258
• Research Site: semanticintent.dev
• Published Papers: Semantic Intent as SSOT (DOI: 10.5281/zenodo.17114972)

PerchIQX serves as a reference implementation of the Semantic Intent pattern applied to database intelligence. The research behind this pattern achieved 78% improvement in behavioral consistency in real-world applications.

Part of Cormorant Foraging ​

PerchIQX is part of the Cormorant Foraging framework - a three-dimensional approach to intelligence systems that emerged organically from building production tools.

PerchIQX represents the Space dimension of Cormorant Foraging:

Learn more: cormorantforaging.dev - Intelligence Systems, Naturally Organized

Related Projects ​

• ChirpIQX - Fantasy hockey intelligence MCP
• WakeIQX - AI context temporal intelligence MCP

Connect ​

• GitHub: @semanticintent
• Portfolio: semanticintent.dev