{"_id":"@ailumia/amazon-sp-api-mcp","name":"@ailumia/amazon-sp-api-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@ailumia/amazon-sp-api-mcp","version":"1.0.0","description":"Production-grade, version-aware Model Context Protocol server for Amazon Selling Partner API","type":"module","bin":{"amazon-sp-api-mcp":"dist/index.js"},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=20"},"scripts":{"build":"tsc -p tsconfig.build.json","dev":"tsx src/index.ts","start":"node dist/index.js","typecheck":"tsc --noEmit","lint":"eslint .","format":"prettier --write .","format:check":"prettier --check .","test":"vitest run --coverage","test:watch":"vitest","check":"npm run format:check && npm run lint && npm run typecheck && npm run test && npm run build && npm run registry:check","registry:sync":"tsx scripts/sync-models.ts","registry:generate":"tsx scripts/generate-registry.ts","registry:check":"tsx scripts/check-registry.ts","prepack":"npm run check"},"keywords":["amazon","sp-api","selling-partner-api","mcp","model-context-protocol"],"author":{"name":"Ailumia","email":"opensource@ailumia.com"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/ailumia/amazon-sp-api-mcp.git"},"bugs":{"url":"https://github.com/ailumia/amazon-sp-api-mcp/issues"},"homepage":"https://github.com/ailumia/amazon-sp-api-mcp#readme","publishConfig":{"access":"public","provenance":true},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","ajv":"^8.17.1","ajv-formats":"^3.0.1","pino":"^10.3.1","zod":"^4.4.3"},"devDependencies":{"@eslint/js":"^9.39.1","@types/express":"^5.0.6","@types/node":"^20.19.1","@vitest/coverage-v8":"^4.1.10","eslint":"^9.39.1","prettier":"^3.7.4","tsx":"^4.21.0","typescript":"^6.0.3","typescript-eslint":"^8.48.1","vitest":"^4.1.10"},"_id":"@ailumia/amazon-sp-api-mcp@1.0.0","gitHead":"c1dd01d95c98c9dd9d89e4667f2f70120bacecd6","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-cHM2KSDuyEnf5hlwhQfB3aHv8yDicjaLfrWHFxXEj48BXETPrHfoZ0q1hnu8F9v1CJSfV7Oo4oHPsgCkODiPAw==","shasum":"12c77699cd456677773f378648180299ba8d8980","tarball":"https://registry.npmjs.org/@ailumia/amazon-sp-api-mcp/-/amazon-sp-api-mcp-1.0.0.tgz","fileCount":68,"unpackedSize":3173117,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCaNF+BfiJpdIL6Hfi1k7Ry6g1xgXvcOmbSo54wJNeF1QIgZwYeEeqDpC3h/HBBWJK0cC9cgPSAeijFn8wkF9Cdm1U="}]},"_npmUser":{"name":"jhsu24","email":"johnny@ailumia.com"},"directories":{},"maintainers":[{"name":"jhsu24","email":"johnny@ailumia.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/amazon-sp-api-mcp_1.0.0_1784542038547_0.7196707390405706"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-20T10:07:18.382Z","1.0.0":"2026-07-20T10:07:18.689Z","modified":"2026-07-20T10:07:18.943Z"},"maintainers":[{"name":"jhsu24","email":"johnny@ailumia.com"}],"description":"Production-grade, version-aware Model Context Protocol server for Amazon Selling Partner API","homepage":"https://github.com/ailumia/amazon-sp-api-mcp#readme","keywords":["amazon","sp-api","selling-partner-api","mcp","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/ailumia/amazon-sp-api-mcp.git"},"author":{"name":"Ailumia","email":"opensource@ailumia.com"},"bugs":{"url":"https://github.com/ailumia/amazon-sp-api-mcp/issues"},"license":"Apache-2.0","readme":"# Amazon SP-API MCP\n\n[![CI](https://github.com/ailumia/amazon-sp-api-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ailumia/amazon-sp-api-mcp/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/ailumia/amazon-sp-api-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/ailumia/amazon-sp-api-mcp/actions/workflows/codeql.yml)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js)](package.json)\n\nA production-grade, version-aware [Model Context Protocol](https://modelcontextprotocol.io/) server for the Amazon Selling Partner API (SP-API), maintained by [Ailumia](https://ailumia.com/).\n\nThe server exposes a small six-tool MCP surface backed by a generated registry of **353 operations across 49 API domains and every model version currently published by Amazon**. Agents discover the right operation at runtime instead of loading hundreds of endpoint schemas into their context.\n\n> [!IMPORTANT]\n> This is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Amazon. Amazon, Selling Partner API, and SP-API are trademarks of Amazon.com, Inc. or its affiliates.\n\n## Why this server\n\n- **Complete model coverage** — generated from [`amzn/selling-partner-api-models`](https://github.com/amzn/selling-partner-api-models), not a hand-maintained endpoint subset.\n- **Version aware** — operation IDs include their API version; upstream model commit metadata is embedded in every registry build.\n- **Small MCP surface** — safe account listing, discovery, description, invocation, artifact retrieval, and a complete Reports workflow.\n- **Safe by default** — remote writes and deletes require explicit confirmation; credentials are injected server-side and never accepted as tool arguments.\n- **Multiple seller accounts** — configure stable account names; credentials remain server-side and multi-account calls must select an account explicitly.\n- **Marketplace safety** — account metadata is loaded from Amazon and account, marketplace, and regional endpoint combinations are validated before execution.\n- **Production controls** — per-account operation rate limiting, bounded concurrency, retries, dry runs, audit events, response size limits, structured errors, and request IDs.\n- **Large result handling** — oversized and binary responses become integrity-checked local artifacts that can be read in bounded chunks.\n- **Two transports** — stdio for local clients and stateless Streamable HTTP for controlled deployments.\n\n## Tools\n\n| Tool                  | Purpose                                                                            |\n| --------------------- | ---------------------------------------------------------------------------------- |\n| `list_accounts`       | List safe account names, regions, metadata status, and marketplace participations. |\n| `discover_operations` | Search operations by intent, domain, version, and access level.                    |\n| `describe_operation`  | Return the exact path, method, parameters, request body, and validation schema.    |\n| `invoke_operation`    | Execute any operation in the registry. Writes and deletes require `confirm=true`.  |\n| `get_artifact`        | Read a bounded chunk from a large or binary result.                                |\n| `run_report`          | Create, poll, download, decompress, and persist an SP-API report.                  |\n\n## Requirements\n\n- Node.js 20 or newer\n- An Amazon SP-API application\n- An LWA client ID, client secret, and seller refresh token for live calls\n\nDiscovery and operation descriptions work without Amazon credentials.\n\n## Install\n\nClone and build the pinned source:\n\n```bash\ngit clone https://github.com/ailumia/amazon-sp-api-mcp.git\ncd amazon-sp-api-mcp\nnpm ci\nnpm run build\n```\n\nThe package is also prepared for public npm publication as `@ailumia/amazon-sp-api-mcp`. Until a release is present on npm, configure clients to run the local `dist/index.js` shown below.\n\n## Configure credentials\n\nSet `SP_API_ACCOUNTS` to a JSON array. Credentials stay in the MCP server environment and are never accepted through tool arguments. `ACCOUNT_NAME` is a stable routing key, not an Amazon store name. It is exposed as `accountName` in MCP tool arguments and responses.\n\nAccount fields:\n\n| Field                  | Required                        | Description                                                                  |\n| ---------------------- | ------------------------------- | ---------------------------------------------------------------------------- |\n| `ACCOUNT_NAME`         | When two or more accounts exist | Stable lowercase name: letters, numbers, `_`, or `-`; maximum 64 characters. |\n| `SP_API_CLIENT_ID`     | Yes                             | LWA application client ID.                                                   |\n| `SP_API_CLIENT_SECRET` | Yes                             | LWA application client secret.                                               |\n| `SP_API_REFRESH_TOKEN` | Yes                             | Seller authorization refresh token.                                          |\n| `SP_API_REGION`        | No                              | `na` by default; also supports `eu` and `fe`.                                |\n\n### Single account\n\nUse an array with one account. `ACCOUNT_NAME` can be omitted; the server assigns the internal name `default`. This explicit example uses all five supported account fields:\n\n```bash\nexport SP_API_ACCOUNTS='[\n  {\n    \"ACCOUNT_NAME\": \"primary\",\n    \"SP_API_CLIENT_ID\": \"amzn1.application-oa2-client...\",\n    \"SP_API_CLIENT_SECRET\": \"...\",\n    \"SP_API_REFRESH_TOKEN\": \"...\",\n    \"SP_API_REGION\": \"na\"\n  }\n]'\n```\n\n### Multiple accounts\n\nEvery account must have a unique `ACCOUNT_NAME` when more than one account is configured:\n\n```bash\nexport SP_API_ACCOUNTS='[\n  {\n    \"ACCOUNT_NAME\": \"hexai-na\",\n    \"SP_API_CLIENT_ID\": \"amzn1.application-oa2-client...\",\n    \"SP_API_CLIENT_SECRET\": \"...\",\n    \"SP_API_REFRESH_TOKEN\": \"...\",\n    \"SP_API_REGION\": \"na\"\n  },\n  {\n    \"ACCOUNT_NAME\": \"hexai-eu\",\n    \"SP_API_CLIENT_ID\": \"amzn1.application-oa2-client...\",\n    \"SP_API_CLIENT_SECRET\": \"...\",\n    \"SP_API_REFRESH_TOKEN\": \"...\",\n    \"SP_API_REGION\": \"eu\"\n  }\n]'\n```\n\nAt startup the server begins loading each account's marketplace participations from Amazon. Use `list_accounts` to inspect the safe result; credentials are never returned:\n\n```json\n{}\n```\n\nAn example response includes `accountName`, `region`, `metadataStatus`, and marketplace objects containing `marketplaceId`, `storeName`, and participation status.\n\nIf metadata discovery fails, `metadataStatus` is `error` and the server logs the reason without exposing credentials. Marketplace-scoped calls fail closed with `ACCOUNT_METADATA_UNAVAILABLE` until discovery succeeds; operations without a Marketplace argument can still run.\n\nSelect an account by its stable name:\n\n```json\n{\n  \"operationId\": \"orders.2026-01-01.searchOrders\",\n  \"accountName\": \"hexai-eu\",\n  \"query\": {\n    \"marketplaceIds\": [\"A1PA6795UKMFR9\"]\n  }\n}\n```\n\nWhen multiple accounts are configured, omitting `accountName` returns `ACCOUNT_NAME_REQUIRED`. With one account it remains optional. The server never guesses an account from a marketplace ID because multiple accounts can participate in the same marketplace.\n\nBefore a marketplace-scoped request, the server verifies that every requested marketplace is active for the selected account. Operations that require a Seller/Merchant ID accept `sellerId` in their normal operation arguments. Every step of `run_report` uses the same selected account.\n\nThe supported regions are:\n\n| Value | Endpoint                                  |\n| ----- | ----------------------------------------- |\n| `na`  | `https://sellingpartnerapi-na.amazon.com` |\n| `eu`  | `https://sellingpartnerapi-eu.amazon.com` |\n| `fe`  | `https://sellingpartnerapi-fe.amazon.com` |\n\nDiscovery and operation descriptions work when `SP_API_ACCOUNTS` is unset. `list_accounts` then returns an empty list and live calls return `ACCOUNT_NOT_FOUND`.\n\n## MCP client configuration\n\nEnvironment values in JSON-based MCP client configuration must escape the account-array JSON:\n\n```json\n{\n  \"mcpServers\": {\n    \"amazon-sp-api\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/amazon-sp-api-mcp/dist/index.js\"],\n      \"env\": {\n        \"SP_API_ACCOUNTS\": \"[{\\\"ACCOUNT_NAME\\\":\\\"hexai-na\\\",\\\"SP_API_CLIENT_ID\\\":\\\"...\\\",\\\"SP_API_CLIENT_SECRET\\\":\\\"...\\\",\\\"SP_API_REFRESH_TOKEN\\\":\\\"...\\\",\\\"SP_API_REGION\\\":\\\"na\\\"}]\"\n      }\n    }\n  }\n}\n```\n\nThe default transport is stdio. Logs are written to stderr so they never corrupt MCP messages on stdout.\n\n## Typical agent flow\n\nFirst list accounts and enabled marketplaces:\n\n```json\n{}\n```\n\nThen discover an operation:\n\n```json\n{\n  \"query\": \"orders updated since a timestamp\",\n  \"domain\": \"orders\",\n  \"access\": \"read\"\n}\n```\n\nThen describe the selected version:\n\n```json\n{\n  \"operationId\": \"orders.2026-01-01.searchOrders\"\n}\n```\n\nFinally invoke it using the returned location-aware schema:\n\n```json\n{\n  \"operationId\": \"orders.2026-01-01.searchOrders\",\n  \"accountName\": \"hexai-na\",\n  \"query\": {\n    \"marketplaceIds\": [\"ATVPDKIKX0DER\"],\n    \"lastUpdatedAfter\": \"2026-07-01T00:00:00Z\"\n  }\n}\n```\n\nExact operation names and arguments evolve with Amazon's models. Always use `discover_operations` and `describe_operation` rather than relying on an example indefinitely.\n\n### State-changing operations\n\nPOST, PUT, and PATCH operations require `confirm=true`. DELETE operations receive the stricter `delete` access classification and also require confirmation.\n\n```json\n{\n  \"operationId\": \"listingsItems.2021-08-01.patchListingsItem\",\n  \"accountName\": \"hexai-na\",\n  \"path\": {\n    \"sellerId\": \"SELLER_ID\",\n    \"sku\": \"SKU-123\"\n  },\n  \"query\": {\n    \"marketplaceIds\": [\"ATVPDKIKX0DER\"]\n  },\n  \"body\": {},\n  \"confirm\": true\n}\n```\n\nPreview the validated regional request without sending the SP-API operation by using `dryRun=true`; confirmation is not required for a dry run:\n\n```json\n{\n  \"operationId\": \"listingsItems.2021-08-01.patchListingsItem\",\n  \"accountName\": \"hexai-na\",\n  \"path\": {\n    \"sellerId\": \"SELLER_ID\",\n    \"sku\": \"SKU-123\"\n  },\n  \"query\": {\n    \"marketplaceIds\": [\"ATVPDKIKX0DER\"]\n  },\n  \"body\": {},\n  \"dryRun\": true\n}\n```\n\nSuccessful, failed, rejected, and dry-run operations emit JSON audit events with the account name, marketplaces, operation, confirmation state, request ID when available, resource identifiers, and a SHA-256 payload hash for writes. Results and structured errors include an `auditId` for correlation. Credentials and raw request bodies are not logged.\n\n## Reports workflow\n\n`run_report` manages the asynchronous Reports API lifecycle and returns an artifact reference:\n\n```json\n{\n  \"reportType\": \"GET_MERCHANT_LISTINGS_ALL_DATA\",\n  \"accountName\": \"hexai-na\",\n  \"marketplaceIds\": [\"ATVPDKIKX0DER\"],\n  \"confirm\": true\n}\n```\n\nThe workflow creates the report, polls `getReport`, fetches the report document, downloads the pre-signed URL, decompresses GZIP content when necessary, and stores the result with SHA-256 integrity metadata.\n\n## Streamable HTTP\n\nLocal HTTP mode:\n\n```bash\nnpm run build\nnode dist/index.js --transport http\n```\n\nEndpoints:\n\n- `POST /mcp` — stateless Streamable HTTP MCP\n- `GET /health` — registry and source-commit health information\n\nThe default bind address is `127.0.0.1`. A non-loopback `HOST` requires `MCP_ALLOWED_HOSTS` to reduce DNS rebinding risk. Set `MCP_BEARER_TOKEN` for shared deployments:\n\n```bash\nHOST=0.0.0.0 \\\nMCP_ALLOWED_HOSTS=mcp.example.com \\\nMCP_BEARER_TOKEN=\"use-at-least-16-random-characters\" \\\nnode dist/index.js --transport http\n```\n\nTLS and internet-facing authorization should be terminated by a trusted reverse proxy or identity-aware gateway. See [Security model](docs/security-model.md).\n\n## Runtime configuration\n\n| Variable                    | Default          | Description                                                           |\n| --------------------------- | ---------------- | --------------------------------------------------------------------- |\n| `SP_API_ACCOUNTS`           | unset            | JSON array containing the five supported per-account fields above.    |\n| `SP_API_MAX_RETRIES`        | `5`              | Retry limit for 429 and transient 5xx responses.                      |\n| `SP_API_MAX_CONCURRENCY`    | `4`              | Maximum concurrent outbound SP-API requests.                          |\n| `SP_API_MAX_RESPONSE_BYTES` | `1048576`        | Maximum inline response size before artifact storage.                 |\n| `SP_API_REQUEST_TIMEOUT_MS` | `60000`          | Per-request timeout.                                                  |\n| `SP_API_ARTIFACT_DIR`       | `./artifacts`    | Local artifact storage directory.                                     |\n| `LOG_LEVEL`                 | `info`           | Pino log level.                                                       |\n| `HOST` / `PORT`             | `127.0.0.1:3000` | Streamable HTTP listener.                                             |\n| `MCP_ALLOWED_HOSTS`         | unset            | Comma-separated HTTP Host allowlist. Required for non-loopback binds. |\n| `MCP_BEARER_TOKEN`          | unset            | Optional HTTP bearer token, minimum 16 characters.                    |\n\n## Registry updates\n\nThe tracked registry is deterministic for an upstream commit and records both the repository and commit SHA.\n\n```bash\nnpm run registry:sync\nnpm run registry:check\n```\n\nThe weekly GitHub workflow runs the same process and opens a pull request when Amazon publishes model changes. Registry generation supports Swagger 2.0 and OpenAPI 3.x.\n\n## Architecture\n\n```text\nMCP tools\n  ├── version-aware operation registry\n  ├── account registry + marketplace validation\n  ├── Reports workflow\n  └── execution pipeline\n        ├── JSON Schema validation\n        ├── write/delete confirmation policy\n        ├── per-account LWA token provider\n        ├── account + region + operation rate limiter\n        ├── bounded concurrency + retry\n        ├── dry-run + structured audit event\n        ├── SP-API HTTP transport\n        └── inline result / artifact store\n```\n\nSee [Architecture](docs/architecture.md) for module boundaries, operation identity, data flow, and extension rules.\n\n## Development\n\n```bash\nnpm ci\nnpm run check\n```\n\n`npm run check` runs formatting verification, ESLint, strict TypeScript, tests with coverage, the production build, and registry contract validation.\n\nUseful commands:\n\n```bash\nnpm run dev\nnpm run test:watch\nnpm run registry:generate -- /path/to/selling-partner-api-models/models\n```\n\nContributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md), the [Code of Conduct](CODE_OF_CONDUCT.md), and [SECURITY.md](SECURITY.md) before opening a pull request or reporting a vulnerability.\n\n## License\n\nApache License 2.0. The generated registry derives structural metadata from Amazon's Apache-2.0-licensed Selling Partner API models; attribution is recorded in [NOTICE](NOTICE).\n","readmeFilename":"README.md","_rev":"1-c49d5fd1f7a7be58492841a3d63ac7bd"}