Skip to content

feat: add reliability, dx, and tooling improvements#12

Open
brijr wants to merge 1 commit intomainfrom
feat/reliability-dx-improvements
Open

feat: add reliability, dx, and tooling improvements#12
brijr wants to merge 1 commit intomainfrom
feat/reliability-dx-improvements

Conversation

@brijr
Copy link
Owner

@brijr brijr commented Jan 10, 2026

Summary

This PR adds comprehensive improvements across reliability, developer experience, tooling, and testing.

Reliability

  • Structured error envelopes with consistent codes (META_AUTH_EXPIRED, META_RATE_LIMIT_USER, etc.) and human-readable messages
  • Idempotency key system for write operations to prevent accidental duplicates
  • Centralized Meta API error parsing with parseMetaApiError() and getHumanReadableError()
  • Upload timeouts with AbortSignal support for uploadImageFromUrl()
  • Enhanced retry with cancellation support via AbortSignal

Developer Experience

  • Structured logging via META_MCP_LOG_LEVEL (debug/info/warn/error/silent) and META_MCP_LOG_FORMAT (json/text)
  • CLI commands:
    • meta-ads-mcp config --client claude|cursor - Generate ready-to-use config JSON
    • meta-ads-mcp doctor - Validate environment, token scopes, and permissions

Tooling/UX

  • get_account_context - Get accounts, currency, timezone, permissions in one call
  • validate_campaign - Pre-creation validation for campaigns
  • validate_ad_set - Pre-creation validation for ad sets
  • validate_creative - Pre-creation validation for creatives
  • summarize_errors - Convert Meta API errors to human-readable explanations with fix suggestions

Testing

  • Jest configuration updated for TypeScript with ts-jest
  • Mock fixtures using @faker-js/faker
  • Contract tests for error-handler and rate-limiter

Files Changed

Category Files
Types src/types/error-envelope.ts
Utils src/utils/logger.ts, src/utils/idempotency.ts, src/utils/error-handler.ts
CLI src/cli/index.ts, src/cli/commands/config.ts, src/cli/commands/doctor.ts
Tools src/tools/validation.ts
Core src/server.ts, src/index.ts, src/meta-client.ts
Tests __tests__/setup.ts, __tests__/fixtures/, __tests__/unit/
Config package.json, jest.config.js

Test plan

  • Run npm run build (may need NODE_OPTIONS="--max-old-space-size=8192" for large heap)
  • Run npm test for unit tests
  • Run npm run doctor to validate environment
  • Run npm run config to generate Claude config
  • Test new validation tools via MCP client

Reliability:
- Add structured error envelopes with consistent codes and messages
- Add idempotency key system for write operations
- Add centralized Meta API error parsing with human-readable messages
- Add timeout and cancellation support to image uploads
- Enhance retryWithBackoff with AbortSignal support

Developer Experience:
- Add structured logging with META_MCP_LOG_LEVEL and JSON format support
- Add CLI commands: config (generate Claude/Cursor config), doctor (validate env)
- Refactor entry point to support CLI subcommands

Tooling/UX:
- Add get_account_context tool for comprehensive account info
- Add validate_campaign, validate_ad_set, validate_creative tools
- Add summarize_errors tool for human-readable error explanations

Testing:
- Set up Jest with TypeScript support
- Add mock fixtures using Faker.js
- Add contract tests for error-handler and rate-limiter
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant