quack-mcp: Instructions file for Claude Code

Quack MCP Development Guidelines

This document outlines the development guidelines, coding conventions, and best practices for the Quack MCP server project.

Project Overview

Quack MCP is a Model Context Protocol (MCP) server that provides CSV analysis capabilities using DuckDB. The project emphasizes type safety, performance, and maintainability through strict TypeScript configuration and clear architectural patterns.

TypeScript Configuration

Strict Mode Requirements

The project uses the strictest possible TypeScript configuration:

{
  "compilerOptions": {
    "noEmit": true,
    "target": "esnext", 
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Key Rules:

• All type annotations must be explicit - No implicit any types
• Strict null checks enabled - Handle undefined and null explicitly
• No unused variables or imports - Clean, minimal code only
• Consistent file naming - Use kebab-case for files, PascalCase for classes

Architecture Guidelines

Class Structure

All classes follow a consistent structure:

class QuackMCPServer {
  // 1. Private properties first
  private server: Server;
  private db: Database.Database;
  private loadedTables: Map<string, string> = new Map();

  // 2. Constructor
  constructor() {
    // Initialize properties
    this.setupToolHandlers();
  }

  // 3. Private setup methods
  private setupToolHandlers() {
    // Configuration logic
  }

  // 4. Public methods (tool handlers)
  async loadCSV(args: any) {
    // Implementation
  }

  // 5. Private utility methods
  private async executeQuery(query: string): Promise<any[]> {
    // Implementation
  }
}

Method Naming Conventions

• Tool handlers: Use camelCase matching the tool name (loadCSV, queryCSV)
• Private methods: Use camelCase with descriptive names (executeQuery, inspectTableSchema)
• Async methods: Always mark as async and return Promise<T>