PerchIQX

Appearance

Getting Started ​

Get up and running with PerchIQX in under 5 minutes. This guide walks you through installation, configuration, and connecting to Claude Desktop.

Prerequisites ​

Before you begin, ensure you have:

  • Node.js 20.x or higher - Download here
  • Cloudflare account with D1 databases - Sign up
  • Cloudflare API token with D1 access
  • Claude Desktop (optional, for MCP integration) - Download here

Installation ​

1. Clone the Repository ​

bash
git clone https://github.com/semanticintent/semantic-perch-intelligence-mcp.git
cd semantic-perch-intelligence-mcp

2. Install Dependencies ​

bash
npm install

This installs all required packages including:

  • @modelcontextprotocol/sdk - MCP protocol implementation
  • dotenv - Environment variable management
  • TypeScript and testing tools

3. Configure Environment ​

Copy the example configuration:

bash
cp .env.example .env

Edit .env with your Cloudflare credentials:

bash
# Cloudflare Configuration
CLOUDFLARE_ACCOUNT_ID=your_cloudflare_account_id
CLOUDFLARE_API_TOKEN=your_cloudflare_api_token

# D1 Database Configuration - Development
D1_DEV_DATABASE_ID=your_dev_database_id
D1_DEV_DATABASE_NAME=your_dev_database_name

# D1 Database Configuration - Staging (Optional)
D1_STAGING_DATABASE_ID=your_staging_database_id
D1_STAGING_DATABASE_NAME=your_staging_database_name

# D1 Database Configuration - Production (Optional)
D1_PROD_DATABASE_ID=your_prod_database_id
D1_PROD_DATABASE_NAME=your_prod_database_name

Note: At least one database environment must be configured.

Getting Cloudflare Credentials ​

Get Your API Token ​

  1. Go to Cloudflare Dashboard
  2. Navigate to My Profile → API Tokens
  3. Click Create Token
  4. Use the Edit Cloudflare Workers template
  5. Add D1 permissions: D1:Read
  6. Copy the token to your .env file

Get D1 Database IDs ​

bash
# List all your D1 databases
wrangler d1 list

# Get specific database info
wrangler d1 info <database-name>

Copy the database IDs and names to your .env file.

Build and Run ​

Build the Server ​

bash
npm run build

This compiles TypeScript to JavaScript in the dist/ directory.

Start the MCP Server ​

bash
npm start

Or use the provided shell script:

bash
./start-d1-mcp.sh

You should see:

🚀 Starting PerchIQX MCP Server...
✅ PerchIQX MCP Server running on stdio

Connect to Claude Desktop ​

To use PerchIQX with Claude Desktop, you need to add it to your MCP configuration.

1. Open Claude Desktop Configuration ​

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Or use the menu: Settings → Developer → Edit Config

2. Add MCP Server Configuration ​

json
{
  "mcpServers": {
    "semantic-perch": {
      "command": "node",
      "args": [
        "/absolute/path/to/semantic-perch-intelligence-mcp/dist/index.js"
      ],
      "env": {
        "CLOUDFLARE_ACCOUNT_ID": "your_account_id",
        "CLOUDFLARE_API_TOKEN": "your_api_token",
        "D1_DEV_DATABASE_ID": "your_dev_db_id",
        "D1_DEV_DATABASE_NAME": "your_dev_db_name",
        "D1_STAGING_DATABASE_ID": "your_staging_db_id",
        "D1_STAGING_DATABASE_NAME": "your_staging_db_name",
        "D1_PROD_DATABASE_ID": "your_prod_db_id",
        "D1_PROD_DATABASE_NAME": "your_prod_db_name"
      }
    }
  }
}

Important: Replace /absolute/path/to/ with the actual absolute path to your installation.

3. Restart Claude Desktop ​

Close and reopen Claude Desktop for the changes to take effect.

4. Verify Installation ​

In Claude Desktop, you should see the PerchIQX tools available:

  • analyze_database_schema
  • get_table_relationships
  • validate_database_schema
  • suggest_database_optimizations

First Query ​

Try asking Claude:

"Analyze my development database schema and show me the table structure"

Claude will use the analyze_database_schema tool to introspect your D1 database and provide detailed schema information.

Development Mode ​

For development, use watch mode to rebuild on changes:

bash
npm run dev

Run tests:

bash
# Run all tests
npm test

# Watch mode
npm run test:watch

# With UI
npm run test:ui

# Coverage report
npm run test:coverage

Next Steps ​

Troubleshooting ​

"Environment variable not set" error ​

Make sure your .env file contains all required variables:

  • CLOUDFLARE_ACCOUNT_ID
  • CLOUDFLARE_API_TOKEN
  • At least one database configuration (dev, staging, or production)

"Permission denied" error ​

Verify your API token has D1 read permissions. Regenerate the token if needed.

Claude Desktop doesn't show tools ​

  1. Check that the path in claude_desktop_config.json is correct and absolute
  2. Verify the server builds successfully (npm run build)
  3. Restart Claude Desktop completely
  4. Check Claude Desktop logs for errors

Support ​

Need help?