Skip to content

Setup MCP Server Foundation & TypeScript Configuration

Overview

Establish the basic MCP server infrastructure with proper TypeScript configuration, build system, and core dependencies. This creates the foundation that Claude agents will build upon.

Claude Agent Success Criteria

A Claude agent should be able to:

  • ✅ Run npm run build and get a successful compilation
  • ✅ Run npm run health-check and verify MCP server starts correctly
  • ✅ See clear TypeScript types for all core interfaces
  • ✅ Find comprehensive development commands in package.json

Detailed Acceptance Criteria

1. Core MCP Server Setup

  • Install and configure @modelcontextprotocol/sdk-typescript
  • Create src/index.ts as the main entry point
  • Implement basic MCP server initialization
  • Add proper error handling and logging
  • Ensure server responds to MCP protocol initialize requests

2. TypeScript Configuration

  • Configure tsconfig.json for strict mode with all checks enabled
  • Set up proper source maps for debugging
  • Configure module resolution for MCP SDK imports
  • Add TypeScript build scripts to package.json

3. Build System

  • Configure npm run build to compile TypeScript to dist/
  • Make compiled scripts executable (chmod +x)
  • Add npm run watch for development mode
  • Add npm run prepare for automatic builds

4. Core Type Definitions

Create comprehensive TypeScript interfaces in src/types.ts:

// Core Graphile Migrate interfaces
interface GraphileMigrateConfig {
  connectionString?: string;
  shadowConnectionString?: string;
  rootConnectionString?: string;
  placeholders?: Record<string, string>;
  afterReset?: string[];
  afterAllMigrations?: string[];
}

interface MigrationFile {
  filename: string;
  path: string;
  content: string;
  hash: string;
  appliedAt?: Date;
}

interface MigrationStatus {
  current: MigrationFile | null;
  committed: MigrationFile[];
  pending: MigrationFile[];
  isClean: boolean;
  hasUncommittedChanges: boolean;
}

// MCP Tool response types
interface ToolResponse<T = any> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: any;
  };
}

5. Environment Setup

  • Add dotenv for environment variable loading
  • Create .env.example with required variables
  • Add environment validation with clear error messages
  • Support both local development and MCP client usage

6. Health Check System

  • Implement npm run health-check command
  • Verify MCP server starts and responds to initialize
  • Check Graphile Migrate CLI availability
  • Validate environment configuration
  • Test basic database connectivity (if configured)

7. Development Commands

Update package.json with comprehensive scripts:

{
  "scripts": {
    "build": "tsc && chmod +x dist/index.js",
    "watch": "tsc --watch",
    "dev": "npm run watch",
    "health-check": "node dist/index.js --health-check",
    "test": "vitest",
    "test:run": "vitest run",
    "prepare": "npm run build"
  }
}

Testing Requirements

Unit Tests

  • Test MCP server initialization
  • Test environment variable validation
  • Test TypeScript compilation
  • Test health check functionality

Integration Tests

  • Test MCP protocol compliance
  • Test with actual Claude Code MCP client
  • Test error handling scenarios

Claude Agent Guidance

How to Verify Success

# 1. Build the project
npm run build

# 2. Run health check
npm run health-check

# 3. Test MCP protocol
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | node dist/index.js

Expected Outputs

  • Build should complete without errors
  • Health check should report "MCP Server: Ready"
  • MCP protocol test should return valid initialize response

Common Issues & Solutions

  • "Cannot find module": Run npm install to install dependencies
  • "Permission denied": Build script should make dist/index.js executable
  • "MCP protocol error": Check server initialization in src/index.ts

Definition of Done

  • All acceptance criteria completed
  • Tests passing with >80% coverage
  • Health check command working
  • Documentation in CLAUDE.md updated
  • Claude agent can successfully build and test the project

Estimated Effort

2-3 days

Dependencies

None - this is the foundation issue

Technical Notes for Claude Agents

Key Files to Create/Modify

  • src/index.ts - Main MCP server entry point
  • src/types.ts - Core TypeScript interfaces
  • src/core.ts - Shared utilities and helpers
  • tsconfig.json - TypeScript configuration
  • package.json - Build scripts and dependencies

Essential Dependencies

{
  "@modelcontextprotocol/sdk": "^0.4.0",
  "dotenv": "^16.0.0",
  "zod": "^3.22.0"
}

Architecture Patterns to Follow

  • Use dependency injection for testability
  • Implement proper error boundaries
  • Follow MCP specification exactly
  • Use Zod for runtime type validation
  • Implement comprehensive logging