Skip to content

Documentation, Examples & Claude Agent Integration Guide

Overview

Create comprehensive documentation and examples that enable Claude agents to effectively use the MCP server. This includes API documentation, usage examples, troubleshooting guides, and best practices specifically tailored for AI agents.

Claude Agent Success Criteria

A Claude agent should be able to:

  • ✅ Quickly understand all available MCP tools and their usage
  • ✅ Find clear examples for common migration workflows
  • ✅ Troubleshoot issues using provided guidance
  • ✅ Follow best practices for migration development

Detailed Acceptance Criteria

1. Comprehensive API Documentation

Update CLAUDE.md with complete MCP tool documentation:

# Graphile Migrate MCP Server

## Quick Start for Claude Agents

### Essential Tools
- `get_migration_status` - Check project status and migration state
- `create_migration` - Create new migration with templates  
- `analyze_migration_safety` - Validate migration for safety and idempotency
- `test_migration_idempotency` - Test migration by running multiple times
- `setup_shadow_database` - Create shadow database for safe testing

### Typical Workflow
1. Check project status: `get_migration_status({projectPath})`
2. Create migration: `create_migration({projectPath, migrationName, template})`
3. Validate migration: `analyze_migration_safety({projectPath})`
4. Test idempotency: `test_migration_idempotency({projectPath, iterations: 3})`
5. Commit when ready: `commit_migration({projectPath, message})`

API Reference Structure:

  • Tool-by-tool comprehensive documentation
  • Input/output schemas with examples
  • Error codes and troubleshooting for each tool
  • Performance characteristics and limitations
  • Integration patterns and workflows

2. Workflow Examples & Use Cases

Create detailed examples for common scenarios:

Creating Idempotent Migrations:

// Example: Adding a new table with proper idempotency
const migration = await tools.create_migration({
  projectPath: "/path/to/project",
  migrationName: "add_user_profiles_table",
  template: "table"
});

// Validate the migration
const validation = await tools.analyze_migration_safety({
  projectPath: "/path/to/project"
});

if (validation.data.idempotency.score < 90) {
  const fixes = await tools.suggest_idempotency_fixes({
    projectPath: "/path/to/project", 
    migrationContent: migration.data.content
  });
  // Apply suggested fixes...
}

Shadow Database Testing Workflow:

// Example: Complete shadow database testing cycle
const shadowSetup = await tools.setup_shadow_database({
  projectPath: "/path/to/project",
  recreate: true,
  seedData: true
});

const shadowTest = await tools.test_against_shadow({
  projectPath: "/path/to/project"
});

if (shadowTest.success && shadowTest.data.test.execution.successful) {
  // Safe to proceed with main database
  const commit = await tools.commit_migration({
    projectPath: "/path/to/project",
    message: "Add user profiles with validated schema"
  });
}
  • Complete workflow examples for major use cases
  • Error handling and recovery patterns
  • Best practices for each development phase
  • Performance optimization examples
  • Integration with existing development tools

3. Troubleshooting Guide

Comprehensive troubleshooting documentation:

Common Issues & Solutions:

## Database Connection Issues

**Problem**: "Cannot connect to database"
**Symptoms**: Tools return connection errors
**Solutions**:
1. Check connection string in `.gmrc` file
2. Verify database credentials and permissions  
3. Ensure PostgreSQL is running and accessible
4. Test connection: `get_migration_status({projectPath})`

## Idempotency Failures

**Problem**: "Migration fails idempotency test"
**Symptoms**: `test_migration_idempotency` returns failures
**Solutions**:
1. Use `analyze_migration_safety` to identify issues
2. Apply `suggest_idempotency_fixes` recommendations
3. Add IF NOT EXISTS / IF EXISTS clauses
4. Use CREATE OR REPLACE for functions

Error Code Reference:

  • Complete error code catalog with descriptions
  • Step-by-step resolution procedures
  • Common root causes and prevention
  • Integration-specific troubleshooting
  • Performance troubleshooting guides

4. Best Practices Guide

Comprehensive best practices for Claude agents:

Migration Development:

## Migration Development Best Practices

### 1. Always Start with Status Check
```typescript
const status = await tools.get_migration_status({projectPath});
if (!status.data.project.configValid) {
  // Fix configuration before proceeding
  const config = await tools.validate_project_config({projectPath});
  // Address configuration issues...
}

2. Use Templates for Consistency

// Use templates to ensure idempotent patterns
const migration = await tools.create_migration({
  projectPath: "/path/to/project",
  migrationName: "add_indexes",
  template: "index" // Ensures IF NOT EXISTS patterns
});

3. Validate Before Committing

// Always validate migrations before committing
const safety = await tools.analyze_migration_safety({projectPath});
const idempotency = await tools.test_migration_idempotency({
  projectPath,
  iterations: 3
});

if (safety.data.idempotency.score >= 90 && idempotency.data.test.passed) {
  await tools.commit_migration({projectPath, message: "Validated migration"});
}

- [ ] Development workflow best practices
- [ ] Testing and validation guidelines
- [ ] Performance optimization strategies
- [ ] Security considerations
- [ ] Team collaboration patterns

### 5. Integration Examples
Show how to integrate with common development patterns:

**CI/CD Integration:**
```typescript
// Example: Pre-commit validation script
async function validateMigrations(projectPath: string) {
  // 1. Validate all migrations
  const validation = await tools.validate_all_migrations({
    projectPath,
    includeIdempotencyTest: true,
    includeSafetyAnalysis: true
  });

  // 2. Check for issues
  if (!validation.success || validation.data.issues.length > 0) {
    console.error("Migration validation failed:", validation.data.issues);
    process.exit(1);
  }

  // 3. Test against shadow database
  const shadowTest = await tools.test_against_shadow({projectPath});
  if (!shadowTest.success) {
    console.error("Shadow database test failed:", shadowTest.data.errors);
    process.exit(1);
  }

  console.log("✅ All migrations validated successfully");
}

Development Workflow Integration:

// Example: Watch-driven development workflow
async function startDevelopmentWorkflow(projectPath: string) {
  // Start file watching for real-time feedback
  const watchSession = await tools.watch_migrations({
    projectPath,
    autoValidate: true,
    notificationLevel: "warning"
  });

  // Check workflow status regularly
  setInterval(async () => {
    const status = await tools.development_workflow_status({projectPath});
    if (status.data.currentMigration.estimatedReadiness >= 90) {
      console.log("✅ Migration appears ready for testing");
    }
  }, 30000); // Check every 30 seconds
}
  • CI/CD pipeline integration examples
  • Development tool integration patterns
  • Team workflow coordination examples
  • Monitoring and alerting integration
  • Backup and recovery procedures

6. Performance Guidelines

Performance optimization guide for Claude agents:

Large Database Handling:

## Performance Optimization

### Working with Large Databases
- Use `analyze_schema({includeConstraints: false})` for faster analysis
- Implement progressive validation with `validate_all_migrations({parallelExecution: true})`
- Use shadow database sparingly for large datasets
- Monitor resource usage with development tools

### Batch Operations
```typescript
// Efficient batch validation
const migrations = await listMigrations(projectPath);
const results = await Promise.all(
  migrations.map(migration => 
    tools.analyze_migration_safety({
      projectPath,
      migrationFile: migration.path
    })
  )
);

- [ ] Performance benchmarks and expectations
- [ ] Scalability guidelines for large projects
- [ ] Resource usage optimization
- [ ] Caching and efficiency patterns
- [ ] Monitoring and profiling guidance

### 7. Claude Agent-Specific Features
Document features specifically designed for AI agents:

**Structured Responses:**
```markdown
## Claude Agent Integration Features

### Consistent Response Format
All tools return structured responses:
```typescript
interface ToolResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    suggestions: string[];
  };
}

Error Recovery Patterns

// Automatic error recovery example
async function robustMigrationCreation(projectPath: string, name: string) {
  try {
    return await tools.create_migration({projectPath, migrationName: name});
  } catch (error) {
    if (error.code === 'PROJECT_NOT_FOUND') {
      // Auto-fix: initialize project
      await tools.graphile_migrate_execute({
        command: 'init',
        workingDirectory: projectPath
      });
      return await tools.create_migration({projectPath, migrationName: name});
    }
    throw error;
  }
}

- [ ] AI-optimized response formats
- [ ] Structured error handling patterns
- [ ] Automated recovery suggestions
- [ ] Context-aware recommendations
- [ ] Integration with Claude Code workflows

## Testing Requirements

### Documentation Tests
- [ ] Test all code examples in documentation
- [ ] Verify all API examples work correctly
- [ ] Test troubleshooting procedures
- [ ] Validate performance claims with benchmarks

### Example Validation
- [ ] Create automated tests for workflow examples
- [ ] Test integration patterns with real scenarios
- [ ] Verify error handling examples
- [ ] Test CI/CD integration examples

## Claude Agent Guidance

### Documentation Development Workflow
```bash
# Generate API documentation from code
npm run docs:generate

# Test all documentation examples
npm run docs:test

# Validate example code
npm run examples:validate

# Check documentation coverage
npm run docs:coverage

Expected Documentation Quality

  • All examples should be copy-pasteable and functional
  • Error scenarios should include specific solutions
  • Performance guidelines should include measurable targets
  • Integration examples should work with common tools

Common Documentation Issues

  • Outdated examples: Use automated testing to keep examples current
  • Missing error cases: Document all common error scenarios
  • Performance claims: Back all performance claims with benchmarks

Definition of Done

  • Complete API documentation in CLAUDE.md
  • All workflow examples tested and functional
  • Comprehensive troubleshooting guide complete
  • Best practices guide covers all major scenarios
  • Integration examples work with common tools
  • Performance guidelines include benchmarks
  • Claude agent-specific features documented
  • Documentation tests pass automatically

Estimated Effort

2-3 days

Dependencies

  • All previous issues (documents the complete system)

Technical Notes for Claude Agents

Key Files to Create/Update

  • CLAUDE.md - Main documentation file
  • docs/api-reference.md - Detailed API documentation
  • docs/examples/ - Workflow example files
  • docs/troubleshooting.md - Comprehensive troubleshooting guide
  • docs/best-practices.md - Development best practices
  • scripts/test-docs.js - Documentation testing script

Documentation Standards

  • Use clear, action-oriented language
  • Include working code examples for every feature
  • Provide context for when to use each tool
  • Include expected outputs and error scenarios
  • Structure information for quick scanning and reference

Example Testing Strategy

  • Extract code examples automatically for testing
  • Use real project fixtures for example validation
  • Test examples across different environments
  • Monitor example performance and update benchmarks
  • Validate troubleshooting procedures regularly