From 018bd4ec23add6cf52c1b46134bd6bed077d64bd Mon Sep 17 00:00:00 2001 From: Jack Arturo Date: Sat, 6 Jun 2026 16:21:44 +0200 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20adopt=20house=20standard=20?= =?UTF-8?q?=E2=80=94=20CLAUDE.md=20imports=20AGENTS.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Promote CLAUDE.md's content to AGENTS.md (canonical, read by all agents) and reduce CLAUDE.md to the bare `@AGENTS.md` import. Mechanical only; the freshness pass follows in the next commit. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 53 +---------------------------------------------------- 2 files changed, 53 insertions(+), 52 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..26cab96 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,52 @@ +# CLAUDE.md + +Development guidance for Claude Code when working on mcp-edd. + +## Project Overview + +MCP server for Easy Digital Downloads REST API. Provides 12 tools for accessing EDD store data including sales, customers, products, discounts, and statistics. + +## Architecture + +``` +src/ +├── index.ts # MCP server entry, tool definitions +├── edd-client.ts # EDD REST API client with retry logic +├── types.ts # Zod schemas and TypeScript types +└── env.ts # Environment variable validation +``` + +## Common Commands + +```bash +npm run build # Compile TypeScript +npm run dev # Watch mode development +npm test # Unit tests only +npm run test:integration # Integration tests (needs credentials) +npm run test:all # All tests +npm run lint # ESLint +``` + +## Testing + +Unit tests use Jest with mocked fetch. Integration tests require environment variables: + +```bash +EDD_API_URL=https://example.com/edd-api/ +EDD_API_KEY=your-key +EDD_API_TOKEN=your-token +``` + +## Key Patterns + +- Uses modern McpServer class from SDK 1.x +- Zod schemas for input validation +- Exponential backoff retry (3 attempts) +- Products endpoint is public (no auth), all others require auth + +## EDD API Notes + +- Auth via query params: `?key=xxx&token=xxx` +- Stats endpoint returns data directly (not wrapped in `stats` object) +- Date format for ranges: YYYYMMDD +- Product and date filters cannot be combined on stats endpoint diff --git a/CLAUDE.md b/CLAUDE.md index 26cab96..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,52 +1 @@ -# CLAUDE.md - -Development guidance for Claude Code when working on mcp-edd. - -## Project Overview - -MCP server for Easy Digital Downloads REST API. Provides 12 tools for accessing EDD store data including sales, customers, products, discounts, and statistics. - -## Architecture - -``` -src/ -├── index.ts # MCP server entry, tool definitions -├── edd-client.ts # EDD REST API client with retry logic -├── types.ts # Zod schemas and TypeScript types -└── env.ts # Environment variable validation -``` - -## Common Commands - -```bash -npm run build # Compile TypeScript -npm run dev # Watch mode development -npm test # Unit tests only -npm run test:integration # Integration tests (needs credentials) -npm run test:all # All tests -npm run lint # ESLint -``` - -## Testing - -Unit tests use Jest with mocked fetch. Integration tests require environment variables: - -```bash -EDD_API_URL=https://example.com/edd-api/ -EDD_API_KEY=your-key -EDD_API_TOKEN=your-token -``` - -## Key Patterns - -- Uses modern McpServer class from SDK 1.x -- Zod schemas for input validation -- Exponential backoff retry (3 attempts) -- Products endpoint is public (no auth), all others require auth - -## EDD API Notes - -- Auth via query params: `?key=xxx&token=xxx` -- Stats endpoint returns data directly (not wrapped in `stats` object) -- Date format for ranges: YYYYMMDD -- Product and date filters cannot be combined on stats endpoint +@AGENTS.md From 4e1012f32d781f71783199d0955293a97c412f23 Mon Sep 17 00:00:00 2001 From: Jack Arturo Date: Sat, 6 Jun 2026 16:26:55 +0200 Subject: [PATCH 2/3] docs: freshen AGENTS.md against current code - Correct tool count 12 -> 16 and list all registered edd_* tool names - Add missing src/stdio.ts to architecture; cite verified path:line refs - Generalize intro to coding agents; align env vars and npm scripts with code Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 65 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 46 insertions(+), 19 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 26cab96..0e65766 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,35 +1,52 @@ -# CLAUDE.md +# AGENTS.md -Development guidance for Claude Code when working on mcp-edd. +Development guidance for coding agents (Claude Code, Cursor, Codex, and others) when working on mcp-edd. ## Project Overview -MCP server for Easy Digital Downloads REST API. Provides 12 tools for accessing EDD store data including sales, customers, products, discounts, and statistics. +MCP server for the Easy Digital Downloads REST API. Registers 16 tools for accessing EDD store data including products, sales, customers, statistics, discounts, and download logs, plus a connection validator. ## Architecture ``` src/ -├── index.ts # MCP server entry, tool definitions +├── index.ts # MCP server entry, tool registrations ├── edd-client.ts # EDD REST API client with retry logic ├── types.ts # Zod schemas and TypeScript types -└── env.ts # Environment variable validation +├── env.ts # Environment loading + validation +└── stdio.ts # Redirects console.log/info/debug to stderr so they can't corrupt the stdio protocol stream ``` +`src/stdio.ts` is imported first thing in `src/index.ts:2` so the console patch is applied before anything can write to stdout. + +## Tools + +All 16 tools are registered via `server.registerTool(...)` in `src/index.ts`: + +- `edd_list_products`, `edd_get_product` +- `edd_list_sales`, `edd_get_sale` +- `edd_list_customers`, `edd_get_customer` +- `edd_get_stats`, `edd_get_stats_by_date`, `edd_get_stats_by_product`, `edd_get_stats_by_preset` +- `edd_list_discounts`, `edd_get_discount`, `edd_get_discount_by_code`, `edd_list_active_discounts` +- `edd_get_download_logs` +- `edd_validate_connection` + ## Common Commands ```bash -npm run build # Compile TypeScript -npm run dev # Watch mode development -npm test # Unit tests only +npm run build # Compile TypeScript (tsc) + chmod +x dist/index.js +npm run dev # Watch mode (tsx watch src/index.ts) +npm start # Run compiled server (node dist/index.js) +npm test # Unit tests only npm run test:integration # Integration tests (needs credentials) -npm run test:all # All tests -npm run lint # ESLint +npm run test:all # All tests +npm run lint # ESLint over src/ +npm run format # Prettier write over src/ ``` ## Testing -Unit tests use Jest with mocked fetch. Integration tests require environment variables: +Unit tests use Jest with mocked fetch (`tests/unit/`). Integration tests (`tests/integration/`) require environment variables: ```bash EDD_API_URL=https://example.com/edd-api/ @@ -37,16 +54,26 @@ EDD_API_KEY=your-key EDD_API_TOKEN=your-token ``` +## Environment Variables + +Validated in `src/env.ts:81` (`validateEnv`); all three are required: + +- `EDD_API_URL` — EDD store API base URL (normalized to `.../edd-api/` form) +- `EDD_API_KEY` — EDD API public key +- `EDD_API_TOKEN` — EDD API token + +`loadEnv` (`src/env.ts:9`) also reads a `.env` file, searching `./.env`, `$HOME/.mcp-edd.env`, and `$HOME/.config/mcp-edd/.env`. + ## Key Patterns -- Uses modern McpServer class from SDK 1.x -- Zod schemas for input validation -- Exponential backoff retry (3 attempts) -- Products endpoint is public (no auth), all others require auth +- Uses the modern `McpServer` class from the MCP SDK 1.x (`src/index.ts:3`). +- Zod schemas for input validation. +- Exponential backoff retry, 3 attempts by default (`src/edd-client.ts:147`). +- The V2 products endpoint is public (no auth required for public products); all other endpoints require auth (`src/edd-client.ts:231`). ## EDD API Notes -- Auth via query params: `?key=xxx&token=xxx` -- Stats endpoint returns data directly (not wrapped in `stats` object) -- Date format for ranges: YYYYMMDD -- Product and date filters cannot be combined on stats endpoint +- Auth via query params: `?key=xxx&token=xxx`. +- Stats endpoint returns data directly (not wrapped in a `stats` object); the client normalizes the flat response. +- Date format for ranges: YYYYMMDD. +- Product and date filters are issued via separate client methods (`getStatsByProduct` vs `getStatsByDateRange`) and are not combined in a single stats request. From ec276b065f99c1273d48fed53545cec887758c53 Mon Sep 17 00:00:00 2001 From: Jack Arturo Date: Sat, 6 Jun 2026 17:20:43 +0200 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20address=20Copilot=20review=20?= =?UTF-8?q?=E2=80=94=20fix=20tool-count=20phrasing?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 0e65766..feb7631 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ Development guidance for coding agents (Claude Code, Cursor, Codex, and others) ## Project Overview -MCP server for the Easy Digital Downloads REST API. Registers 16 tools for accessing EDD store data including products, sales, customers, statistics, discounts, and download logs, plus a connection validator. +MCP server for the Easy Digital Downloads REST API. Registers 16 tools for accessing EDD store data including products, sales, customers, statistics, discounts, and download logs, one of which is a connection validator (`edd_validate_connection`). ## Architecture