cost-management-mcp: Instructions file for Claude Code

Claude Development Guidelines for Cost Management MCP

Project Overview

This is a Model Context Protocol (MCP) server that provides unified cost monitoring across multiple cloud and API providers (AWS, OpenAI). The server allows users to retrieve cost data, monitor usage, and track expenses across different services through a consistent interface.

Key Commands

Development

• npm run dev - Start development server with hot reload
• npm run build - Build TypeScript to JavaScript
• npm run test - Run all tests
• npm run lint - Check code style
• npm run typecheck - Check TypeScript types

Before Committing

Pre-commit hooks are configured to automatically run checks:

• ESLint - Automatically fixes code style issues
• Prettier - Formats code for consistency

The hooks run automatically on git commit. To run checks manually:

npm run lint
npm run typecheck
npm test

If you need to bypass hooks temporarily (not recommended):

git commit --no-verify -m "your message"

Architecture Overview

Provider Structure

Each provider (AWS, OpenAI) has:

• client.ts - API client implementation
• types.ts - TypeScript type definitions
• transformer.ts - Transforms provider data to unified format

Unified Data Model

interface UnifiedCostData {
  provider: 'aws' | 'openai';
  period: { start: Date; end: Date };
  costs: {
    total: number;
    currency: string;
    breakdown: Array<{
      service: string;
      amount: number;
      usage?: { quantity: number; unit: string };
    }>;
  };
  metadata: {
    lastUpdated: Date;
    source: 'api' | 'cache' | 'manual';
  };
}

Implementation Guidelines

Error Handling

• Always use custom error classes from src/common/errors.ts
• Implement retry logic with exponential backoff for API calls
• Log errors appropriately without exposing sensitive data
• Provide meaningful error messages to users

Caching Strategy

• Cache all API responses to minimize costs (especially AWS at $0.01/request)
• Default TTL: 1 hour (configurable via CACHE_TTL env var)
• Implement cache invalidation on demand
• Use separate cache keys for each provider/query combination