feat: add reliability, dx, and tooling improvements#12
Open
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds comprehensive improvements across reliability, developer experience, tooling, and testing.
Reliability
META_AUTH_EXPIRED,META_RATE_LIMIT_USER, etc.) and human-readable messagesparseMetaApiError()andgetHumanReadableError()uploadImageFromUrl()Developer Experience
META_MCP_LOG_LEVEL(debug/info/warn/error/silent) andMETA_MCP_LOG_FORMAT(json/text)meta-ads-mcp config --client claude|cursor- Generate ready-to-use config JSONmeta-ads-mcp doctor- Validate environment, token scopes, and permissionsTooling/UX
get_account_context- Get accounts, currency, timezone, permissions in one callvalidate_campaign- Pre-creation validation for campaignsvalidate_ad_set- Pre-creation validation for ad setsvalidate_creative- Pre-creation validation for creativessummarize_errors- Convert Meta API errors to human-readable explanations with fix suggestionsTesting
Files Changed
src/types/error-envelope.tssrc/utils/logger.ts,src/utils/idempotency.ts,src/utils/error-handler.tssrc/cli/index.ts,src/cli/commands/config.ts,src/cli/commands/doctor.tssrc/tools/validation.tssrc/server.ts,src/index.ts,src/meta-client.ts__tests__/setup.ts,__tests__/fixtures/,__tests__/unit/package.json,jest.config.jsTest plan
npm run build(may needNODE_OPTIONS="--max-old-space-size=8192"for large heap)npm testfor unit testsnpm run doctorto validate environmentnpm run configto generate Claude config