Shopify App Pre-Approval Framework

A Rust-native agentic system that validates Shopify apps against official approval documentation. Provides comprehensive validation through CLI, REST API, and MCP server interfaces.

🚀 Claude Code Plugin (Quick Start)

Validate your Shopify apps directly from Claude Code with one command:

claude plugins add github:umerkhan95/shopify-app-approver

Then just ask Claude:

• "Check if my Shopify app is ready for the App Store"
• "Validate the webhook handlers"
• "What GDPR requirements am I missing?"

The plugin auto-activates when it detects Shopify app patterns in your project.

📖 Full Plugin Documentation →

Features

• Multi-Language Parsing: Analyze JavaScript, TypeScript, Ruby, Python, and PHP using tree-sitter
• Deep AST Analysis: Detect complex patterns like API calls, webhooks, billing, and security operations
• Cross-File Dependency Tracking: Build dependency graphs, detect circular dependencies
• Configuration Validation: Validate shopify.app.toml including GDPR webhook requirements
• Comprehensive Validation: Check webhooks, API usage, billing, security, OAuth, and data protection
• LLM-Powered Analysis: GLM 4.7 primary with Claude fallback for deep semantic analysis
• Circuit Breaker Pattern: Automatic failover between LLM providers
• Distributed Tracing: OpenTelemetry support for observability
• Multi-Tenant SaaS: JWT authentication with tenant isolation
• MCP Integration: Lightweight tools for AI agents (Claude Code, Windsurf, OpenCode)

Build Status

• Tests: 48 passing
• Rust: 1.75+ required
• Platform: Linux, macOS, Windows

Quick Start

Prerequisites

• Rust 1.75+ (tested with 1.93.0)
• SQLite 3.x (bundled via SQLx)

Installation

# Clone the repository
git clone https://github.com/umerkhan95/shopify-app-approver.git
cd shopify-app-approver

# Copy environment configuration
cp .env.example .env

# Edit .env with your API keys
# Required: JWT_SECRET (min 32 chars)
# Optional: GLM_API_KEY, ANTHROPIC_API_KEY for LLM features

# Build the project
cargo build --release

Running the API Server

# Set required environment variable
export JWT_SECRET="your-secret-key-at-least-32-characters"

# Run the API server
cargo run -p shopify-approver-api

# Server starts at http://localhost:3000

Running the CLI

# Validate a Shopify app
cargo run -p shopify-approver-cli -- check ./path/to/app

# Search documentation
cargo run -p shopify-approver-cli -- docs search "GDPR webhooks"

# List validation rules
cargo run -p shopify-approver-cli -- rules list

Running the MCP Server (for AI Agents)

# Build and run MCP server
cargo build --release -p shopify-approver-mcp-server
./target/release/shopify-mcp-server

# With RAG support (optional)
MISTRAL_API_KEY=your-key QDRANT_URL=http://localhost:6334 ./target/release/shopify-mcp-server

Configure in Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "shopify-pre-approval": {
      "command": "/path/to/shopify-mcp-server"
    }
  }
}

Or install as a plugin (recommended):

claude plugins add github:umerkhan95/shopify-app-approver

Architecture

shopify-app-approver/
├── crates/
│   ├── core/           # Shared types, traits, error handling
│   ├── parsers/        # Multi-language parsing (tree-sitter)
│   ├── validators/     # Rule engine with pattern matching
│   ├── vector/         # Qdrant client for semantic search
│   ├── db/             # SQLite database layer (SQLx)
│   ├── rig-agent/      # LLM orchestration with circuit breaker
│   ├── mcp-server/     # MCP protocol server
│   ├── cli/            # Command-line interface
│   ├── api/            # REST API (Axum) with OpenTelemetry
│   └── ingestion/      # Documentation crawler
├── rules/              # Validation rules (TOML)
├── migrations/         # Database migrations
└── tests/              # Integration tests

API Endpoints

Authentication

Reviews

Validation (Quick Checks)

Documentation & Search

Validation Rules

Rules are defined in TOML format under rules/:

Environment Variables

MCP Server Tools

The MCP server provides lightweight tools for AI agents:

{
  "tools": [
    "quick_check_file",    // Validate single file (~50-100 tokens)
    "check_webhooks",      // GDPR webhook status (~30-50 tokens)
    "check_api_usage",     // GraphQL vs REST (~50 tokens)
    "check_billing",       // Billing compliance (~30-50 tokens)
    "get_fix_hint",        // Fix recommendation (~100 tokens)
    "search_docs",         // Search documentation (~200 tokens)
    "approval_status"      // Overall readiness (~100 tokens)
  ]
}

Development

Running Tests

# Run all tests
cargo test --workspace

# Run specific crate tests
cargo test -p shopify-approver-validators

# Run with logging
RUST_LOG=debug cargo test --workspace

Code Quality

# Format code
cargo fmt

# Run linter
cargo clippy --workspace -- -D warnings

# Check compilation
cargo check --workspace

Database Migrations

Migrations run automatically on API server startup. For manual control:

# Migrations are in migrations/ directory
# SQLite database is created at $DATABASE_URL path

Security

• Password Hashing: Argon2 with secure defaults
• JWT Tokens: Access (1h) and refresh (7d) token rotation
• Tenant Isolation: All queries filtered by tenant_id
• Rate Limiting: DashMap-based concurrent rate limiting
• Input Validation: Size limits, format validation
• CORS: Configurable allowed origins

Performance

• SQLite with WAL: Write-Ahead Logging for better concurrency
• Circuit Breaker: Automatic LLM failover (5 failures, 30s reset)
• Inline Hints: #[inline] on hot path functions
• Bulk Inserts: Transaction-based batch operations
• Connection Pooling: Configurable pool sizes

Observability

OpenTelemetry tracing is built-in:

# Enable OTLP export
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_SERVICE_NAME=shopify-approver-api

# JSON logs for production
export LOG_FORMAT=json

License

MIT License - see LICENSE for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Run cargo fmt and cargo clippy
4. Submit a pull request

See CLAUDE.md for development guidelines.