PerchIQX

Appearance

PerchIQXSemantic Perch Intelligence MCP

Deep Insights. Database Intelligence. Dive into your D1 data.

Get Started
View Tools
Architecture
PerchIQX - Perch Intelligence for Cloudflare D1
🗄️

D1 Database Intelligence

Built specifically for Cloudflare D1. Deep schema introspection, relationship analysis, and optimization recommendations powered by semantic intent patterns.

🎯

Semantic Intent Pattern

Natural language queries that understand your database needs. Ask questions like "what optimizations are needed?" and get actionable intelligence instantly.

📊

Schema Analysis

Comprehensive database introspection. Analyze tables, columns, indexes, foreign keys, and relationships with semantic understanding of your data model.

🔍

Relationship Discovery

Automatically detect and analyze foreign key relationships, cardinality patterns, and referential integrity rules across your database schema.

⚡

Optimization Insights

AI-powered recommendations for missing indexes, primary keys, and schema improvements. Get prioritized suggestions with impact analysis.

🧠

MCP Integration

Model Context Protocol server for Claude AI. Seamless integration bringing database intelligence directly into your AI development workflows.

🏗️

Hexagonal Architecture

Clean domain-driven design with semantic anchoring. Reference implementation demonstrating observable properties and intent preservation.

🧪

Comprehensive Testing

398 passing tests across all layers. Domain entities, use cases, infrastructure adapters, and integration tests ensure reliability.

Quick Start ​

bash
# 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:

typescript
┌─────────────────────────────────────────────────────────┐
│                   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 ​

Community & Support ​

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 ​

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.

Connect ​

Built with semantic intent patterns for database intelligence

Deep Insights. Database Intelligence. 🗄️