From 4b77fa70d2f5ab940ff1f4b401011b4fbcc9f53a Mon Sep 17 00:00:00 2001 From: Jakob Wolitzki Date: Fri, 19 Jun 2026 19:16:12 +0300 Subject: [PATCH 1/4] DOE-2131: position DataDoe MCP as read + write (Actions) DataDoe MCP is no longer read-only. Update the public surface that AI assistants and SEO crawlers read so it reflects write capabilities. - README: lead with read + write; new Actions section (dryRun flow, governance, cost, real AMAZON_LISTINGS_UPDATE payload); add 4 Action tools to the table; action-oriented example prompts; "Read + Write" badge. - README: fix broken per-client doc links (data-doe-mcp -> datadoe-mcp), expand to all 20 verified client guides, correct client count. - src/index.ts: advertise the 4 Actions tools (actions_details_schema_get, actions_start, actions_get, actions_list); update server description; bump version to 0.2.0. - server.json: description now mentions write Actions; version 0.2.0. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 113 +++++++++++++++++++++++++------ server.json | 4 +- src/index.ts | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 278 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index b738851..e4cc090 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,17 @@ # Amazon Seller MCP Server - DataDoe -> **Hosted Amazon Seller Central & Vendor Central MCP server.** Connect Claude, ChatGPT, Cursor, Codex, Gemini, and GitHub Copilot to live Amazon SP-API and Amazon Ads API data. DataDoe handles the SP-API developer approval, OAuth, and rate limits so your AI agent starts querying in under a minute. +> **Hosted Amazon Seller Central & Vendor Central MCP server โ€” now read _and_ write.** Connect Claude, ChatGPT, Cursor, Codex, Gemini, and GitHub Copilot to live Amazon SP-API and Amazon Ads API data, then let your AI agent **act**: update listings, manage orders, and optimize Amazon Ads campaigns. DataDoe handles the SP-API developer approval, OAuth, and rate limits so your AI agent starts querying โ€” and acting โ€” in under a minute. [![Amazon Seller & Vendor](https://img.shields.io/badge/Amazon-Seller%20%26%20Vendor-FF9900?style=flat-square)](https://www.datadoe.com/) [![SP-API Selling Partner API](https://img.shields.io/badge/SP--API-Selling%20Partner-FF6F00?style=flat-square)](https://developer-docs.amazon.com/sp-api/) [![Amazon Ads API](https://img.shields.io/badge/Amazon-Ads%20API-232F3E?style=flat-square)](https://advertising.amazon.com/API/docs) [![MCP Server](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-8A2BE2?style=flat-square)](https://modelcontextprotocol.io/) -[![AI clients supported](https://img.shields.io/badge/AI%20clients-6%2B%20supported-D97757?style=flat-square)](#quick-setup-per-ai-client) +[![Read and Write](https://img.shields.io/badge/Amazon-Read%20%2B%20Write-2EA043?style=flat-square)](#actions--let-your-ai-agent-write-to-amazon) +[![AI clients supported](https://img.shields.io/badge/AI%20clients-20%2B%20guides-D97757?style=flat-square)](#quick-setup-per-ai-client) [![smithery badge](https://smithery.ai/badge/jakopv007/datadoe-mcp)](https://smithery.ai/servers/jakopv007/datadoe-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE) -๐Ÿ”— [Start a free trial](https://www.datadoe.com/connect/amazon/mcp) ยท ๐Ÿ“˜ [Documentation](https://app.datadoe.com/hub/docs) ยท ๐Ÿ“Š [Amazon data schema](https://app.datadoe.com/hub/data-scheme) ยท ๐ŸŽฅ [Video demo](https://www.youtube.com/watch?v=9YQd7M2dMyY) +๐Ÿ”— [Start a free trial](https://www.datadoe.com/connect/amazon/mcp) ยท ๐Ÿ“˜ [Documentation](https://www.datadoe.com/hub/docs) ยท โšก [Actions](https://www.datadoe.com/hub/docs/datadoe-features/actions) ยท ๐Ÿ“Š [Amazon data schema](https://www.datadoe.com/hub/data-scheme) ยท ๐ŸŽฅ [Video demo](https://www.youtube.com/watch?v=9YQd7M2dMyY) --- @@ -43,7 +44,12 @@ That's it. DataDoe runs the MCP server on hosted infrastructure, so your team do **DataDoe MCP** is a hosted [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for **Amazon sellers, vendors, and agencies**. It exposes your live Amazon Selling Partner API (SP-API) and Amazon Ads API data through MCP tools that work with Claude, ChatGPT, Cursor, Codex CLI, Gemini CLI, GitHub Copilot, Claude Desktop, n8n, NanoClaw, and any other MCP-capable client. -Building your own Amazon SP-API integration typically requires SP-API developer registration, OAuth refresh-token flow, marketplace-specific endpoints, throttling logic, and 2-4 weeks of Amazon approval. DataDoe takes care of all of that. You get a single authenticated MCP URL, and SKU-level Amazon data - orders, sales, ads spend, traffic, inventory, listings, returns, settlements, brand analytics, catalog - comes back as structured tool responses or downloadable CSV and JSON exports. +DataDoe MCP gives your AI agent two layers over your Amazon account: + +- **A read layer** - SKU-level orders, sales, ads spend, traffic, inventory, listings, returns, settlements, brand analytics, and catalog, returned as structured tool responses or downloadable CSV and JSON exports. +- **A write layer (Actions)** - your agent can change your Amazon account through the SP-API and Amazon Ads API: update listings, cancel orders, confirm shipments, and manage Amazon Ads campaigns, ad groups, targets, and ads. + +Building your own Amazon SP-API integration typically requires SP-API developer registration, OAuth refresh-token flow, marketplace-specific endpoints, throttling logic, and 2-4 weeks of Amazon approval. DataDoe takes care of all of that. You get a single authenticated MCP URL for both reading and acting on your Amazon data. ![DataDoe MCP Banner](/assets/datadoe-mcp-banner.png) @@ -59,10 +65,11 @@ Building your own Amazon SP-API integration typically requires SP-API developer - โœ… **No SP-API approval needed** - DataDoe handles SP-API developer registration, OAuth, refresh tokens, and rate limits on your behalf. - โœ… **30-second setup** - paste the MCP URL and your API key into your AI client config. DataDoe runs the server on hosted infrastructure. -- โœ… **6+ AI clients supported** out of the box: Claude, ChatGPT, Cursor, Codex CLI, Gemini CLI, GitHub Copilot, plus any MCP-capable client. +- โœ… **20+ documented integrations** out of the box: Claude, ChatGPT, Cursor, Codex, Gemini CLI, GitHub Copilot, n8n, CrewAI, the Claude & OpenAI Agent SDKs, Excel / Word / PowerPoint via Claude, and any other MCP-capable client. - โœ… **SKU-level resolution** - drill into individual ASINs, parent listings, marketplaces, time periods, ad campaigns, keyword reports, settlements, returns. - โœ… **Multi-marketplace, multi-account** - one MCP server covers every Amazon marketplace (US, UK, DE, FR, IT, ES, CA, AU, JP, MX, and more) across Seller Central and Vendor Central. - โœ… **AI-native by design** - `exports_create` accepts SQL-like filter groups, GROUP BY, aggregations, and date intervals, so your AI agent can build complex reports from one tool call. +- โœ… **Read _and_ write** - with [Actions](#actions--let-your-ai-agent-write-to-amazon), your agent doesn't just report - it updates listings, manages orders, and optimizes Amazon Ads, with a `dryRun` validation step and per-type controls. - โœ… **Always-on hosted infrastructure** - DataDoe manages SP-API rate limits, token rotation, and ongoing maintenance. ## What can you ask DataDoe MCP? @@ -78,6 +85,56 @@ Example questions your AI agent can answer with DataDoe MCP connected: - *"Pull every Amazon return for SKU ABC-123 in the last 60 days and summarize the return reasons."* - *"Compare my brand analytics search term share-of-voice month over month."* +And with **Actions** enabled, your agent can act on what it finds: + +- *"Raise the daily budget on my top-ACoS Sponsored Products campaign by 20%."* +- *"Pause every campaign with ACoS over 50% last week."* +- *"Update the price of SKU ABC-123 to 19.99 and refresh its bullet points."* +- *"Confirm shipment for order 123-4567890-1234567 with UPS tracking 1Z999..."* + +## Actions โ€” let your AI agent write to Amazon + +DataDoe MCP is not read-only. **Actions** let your AI agent make changes on your connected Amazon Seller Central, Vendor Central, and Amazon Ads accounts through the SP-API and Amazon Ads API โ€” all monitored and auditable. + +**What your agent can do:** + +- **Listings** - update the title, bullet points, description, price, generic keyword, and item-type keyword of an Amazon listing (`AMAZON_LISTINGS_UPDATE`). +- **Orders** - cancel an order item with a reason (`AMAZON_ORDERS_CANCEL`) and confirm shipment with tracking info (`AMAZON_ORDERS_CONFIRM_SHIPMENT`). +- **Amazon Ads** - add, update, remove, and find campaigns, ad groups, targets, ads, and ad associations across Sponsored Products, Sponsored Brands, Sponsored Display, Sponsored TV, and Amazon DSP. + +**Safe-by-design flow** โ€” the agent runs each Action through these MCP tools: + +1. `actions_details_schema_get` - fetch the exact payload schema for the Action type. +2. `actions_start` with `dryRun=true` - validate the payload without executing. +3. `actions_start` - execute the Action and get an action id. +4. `actions_get` - poll until the Action completes, then read the `result`. + +Use `actions_list` to review past Actions (filter by status, type, creator, and date). + +**You stay in control.** All Action types are **disabled by default** and enabled per-type in [Settings โ†’ Actions](https://app.datadoe.com/settings?tab=actions). When a type is disabled, `actions_start` rejects live runs but still allows `dryRun` validation. Every Action is recorded and auditable. + +**Example** โ€” update a listing's price and title (the `details` payload for `AMAZON_LISTINGS_UPDATE`): + +```json +{ + "type": "AMAZON_LISTINGS_UPDATE", + "sellerOrVendorId": "", + "dryRun": true, + "details": { + "changes": [ + { + "sku": "ABC-123", + "language_tag": "en_US", + "name": "Stainless Steel Water Bottle 750ml", + "price": 19.99 + } + ] + } +} +``` + +**Cost** โ€” running an Action costs 2 AI tokens (covers up to 100 entities), plus 1 token per additional 100 entities. See [Actions docs](https://www.datadoe.com/hub/docs/datadoe-features/actions) for the full Action catalog and payload schemas. + ## Available MCP tools DataDoe MCP exposes the following tools to your AI client: @@ -93,6 +150,10 @@ DataDoe MCP exposes the following tools to your AI client: | `exports_raw_download` | Data | Returns the raw export content (CSV or JSON) inline in the tool response. | | `datadoe_user_docs_table_of_contents_get` | Docs | Returns the table of contents of the DataDoe user documentation, useful when an agent needs to look up features or capabilities on demand. | | `datadoe_user_docs_page_get` | Docs | Returns the full content of a named DataDoe documentation page. | +| `actions_details_schema_get` | Actions | Returns the JSON Schema of the `details` payload required to start a given Action type. | +| `actions_start` | Actions | Starts an Action that changes your Amazon account (listings, orders, Amazon Ads). Set `dryRun=true` to validate without executing. Returns an action id. | +| `actions_get` | Actions | Returns the status and `result` of an Action by id โ€” poll after `actions_start`. | +| `actions_list` | Actions | Returns paginated Action history, filterable by status, type, creator, and date. | --- @@ -170,17 +231,28 @@ DataDoe MCP works as a **generic remote MCP server**. Configure your client with For step-by-step setup guides per AI client, see the dedicated DataDoe documentation pages: -- [Using Claude](https://app.datadoe.com/hub/docs/data-doe-mcp/claude) -- [Using ChatGPT](https://app.datadoe.com/hub/docs/data-doe-mcp/chatgpt) -- [Using Claude Code](https://app.datadoe.com/hub/docs/data-doe-mcp/claude-code) -- [Using Codex](https://app.datadoe.com/hub/docs/data-doe-mcp/codex) -- [Using Cursor](https://app.datadoe.com/hub/docs/data-doe-mcp/cursor) -- [Using Gemini CLI](https://app.datadoe.com/hub/docs/data-doe-mcp/gemini-cli) -- [Using VS Code](https://app.datadoe.com/hub/docs/data-doe-mcp/vs-code) -- [Using n8n](https://app.datadoe.com/hub/docs/data-doe-mcp/n8n) -- [Using NanoClaw](https://app.datadoe.com/hub/docs/data-doe-mcp/nanoclaw) - -Full documentation root: [app.datadoe.com/hub/docs](https://app.datadoe.com/hub/docs) +- [Using Claude](https://www.datadoe.com/hub/docs/datadoe-mcp/claude) +- [Using ChatGPT](https://www.datadoe.com/hub/docs/datadoe-mcp/chatgpt) +- [Using Claude Code](https://www.datadoe.com/hub/docs/datadoe-mcp/claude-code) +- [Using Claude Agent SDK](https://www.datadoe.com/hub/docs/datadoe-mcp/claude-agents-sdk) +- [Using Codex](https://www.datadoe.com/hub/docs/datadoe-mcp/codex) +- [Using Codex Sites](https://www.datadoe.com/hub/docs/datadoe-mcp/codex-sites) +- [Using CrewAI](https://www.datadoe.com/hub/docs/datadoe-mcp/crewai) +- [Using Cursor](https://www.datadoe.com/hub/docs/datadoe-mcp/cursor) +- [Using Excel + Claude](https://www.datadoe.com/hub/docs/datadoe-mcp/excel) +- [Using Gemini CLI](https://www.datadoe.com/hub/docs/datadoe-mcp/gemini-cli) +- [Using Gumloop](https://www.datadoe.com/hub/docs/datadoe-mcp/gumloop) +- [Using Hermes Agent](https://www.datadoe.com/hub/docs/datadoe-mcp/hermes) +- [Using n8n](https://www.datadoe.com/hub/docs/datadoe-mcp/n8n) +- [Using NanoClaw](https://www.datadoe.com/hub/docs/datadoe-mcp/nanoclaw) +- [Using OpenAI Agents SDK](https://www.datadoe.com/hub/docs/datadoe-mcp/openai-agents-sdk) +- [Using OpenClaw](https://www.datadoe.com/hub/docs/datadoe-mcp/openclaw) +- [Using OpenCode](https://www.datadoe.com/hub/docs/datadoe-mcp/opencode) +- [Using PowerPoint + Claude](https://www.datadoe.com/hub/docs/datadoe-mcp/powerpoint) +- [Using VS Code](https://www.datadoe.com/hub/docs/datadoe-mcp/vs-code) +- [Using Word + Claude](https://www.datadoe.com/hub/docs/datadoe-mcp/word) + +Full documentation root: [www.datadoe.com/hub/docs](https://www.datadoe.com/hub/docs) --- @@ -197,7 +269,7 @@ DataDoe MCP exposes every Amazon data table available in DataDoe, including: - **Brand analytics**: search query performance, market basket, repeat purchase, demographics - **Traffic**: sessions, page views, conversion rate, by ASIN, by marketplace -Full schema: [app.datadoe.com/hub/data-scheme](https://app.datadoe.com/hub/data-scheme) +Full schema: [www.datadoe.com/hub/data-scheme](https://www.datadoe.com/hub/data-scheme) --- @@ -214,8 +286,9 @@ To avoid confusion when evaluating Amazon MCP servers: ## Documentation & resources - [DataDoe homepage](https://www.datadoe.com/) -- [DataDoe documentation](https://app.datadoe.com/hub/docs) -- [Amazon data schema reference](https://app.datadoe.com/hub/data-scheme) +- [DataDoe documentation](https://www.datadoe.com/hub/docs) +- [DataDoe Actions (write to Amazon)](https://www.datadoe.com/hub/docs/datadoe-features/actions) +- [Amazon data schema reference](https://www.datadoe.com/hub/data-scheme) - [DataDoe MCP product page](https://www.datadoe.com/connect/amazon/mcp) - [DataDoe vs Amazon MCP comparison](https://datadoe.com/compare/datadoe-vs-amazon-mcp) - [DataDoe MCP video demo](https://www.youtube.com/watch?v=9YQd7M2dMyY) @@ -234,7 +307,7 @@ To avoid confusion when evaluating Amazon MCP servers: > This server is just a schema facade of the actual DataDoe MCP server, made for exposing DataDoe MCP to various MCP registries. > It is a no-op server: it does not do anything beyond exposing the schema of DataDoe MCP. -> If you want to actually use DataDoe MCP, see the [DataDoe MCP documentation](https://app.datadoe.com/hub/docs). +> If you want to actually use DataDoe MCP, see the [DataDoe MCP documentation](https://www.datadoe.com/hub/docs). #### 1. Install dependencies diff --git a/server.json b/server.json index db92d79..74b8006 100644 --- a/server.json +++ b/server.json @@ -2,8 +2,8 @@ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "com.datadoe/amazon-seller-mcp", "title": "DataDoe MCP", - "description": "Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.", - "version": "0.1.0", + "description": "Hosted Amazon Seller & Vendor MCP server: query live SP-API & Amazon Ads data and run write Actions (update listings, manage orders, optimize Amazon Ads). Works with Claude, ChatGPT, Cursor, Codex, Gemini, Copilot, n8n, and more.", + "version": "0.2.0", "websiteUrl": "https://www.datadoe.com/connect/amazon/mcp", "repository": { "id": "1242545912", diff --git a/src/index.ts b/src/index.ts index 2308cbf..78f15d5 100644 --- a/src/index.ts +++ b/src/index.ts @@ -40,8 +40,8 @@ export interface McpToolDefinition { export const MCP_SERVER_NAME = 'DataDoe MCP' as const; export const MCP_SERVER_DESCRIPTION = - 'DataDoe is one place to connect, view, analyze, and work with Amazon data.' as const; -export const MCP_SERVER_VERSION = '0.0.1' as const; + 'DataDoe is one place to connect, analyze, and act on Amazon data: query Seller Central, Vendor Central, and Amazon Ads data, then run write Actions like updating listings, managing orders, and optimizing Amazon Ads campaigns.' as const; +export const MCP_SERVER_VERSION = '0.2.0' as const; export const MCP_SERVER_WEBSITE_URL = 'https://app.datadoe.com/integrations/mcp' as const; export const PublicFilterOperators = [ @@ -213,6 +213,93 @@ export const DatadoeUserDocsPageInputSchema: z.ZodType }) .strict(); +export const ActionTypes = [ + 'AMAZON_LISTINGS_UPDATE', + 'AMAZON_ORDERS_CANCEL', + 'AMAZON_ORDERS_CONFIRM_SHIPMENT', + 'AMAZON_ADS_CAMPAIGNS_ADD', + 'AMAZON_ADS_CAMPAIGNS_REMOVE', + 'AMAZON_ADS_CAMPAIGNS_UPDATE', + 'AMAZON_ADS_AD_GROUPS_ADD', + 'AMAZON_ADS_AD_GROUPS_REMOVE', + 'AMAZON_ADS_AD_GROUPS_UPDATE', + 'AMAZON_ADS_TARGETS_ADD', + 'AMAZON_ADS_TARGETS_REMOVE', + 'AMAZON_ADS_TARGETS_UPDATE', + 'AMAZON_ADS_ADS_ADD', + 'AMAZON_ADS_ADS_REMOVE', + 'AMAZON_ADS_ADS_UPDATE', + 'AMAZON_ADS_AD_ASSOCIATIONS_ADD', + 'AMAZON_ADS_AD_ASSOCIATIONS_REMOVE', + 'AMAZON_ADS_AD_ASSOCIATIONS_UPDATE', + 'AMAZON_ADS_CAMPAIGNS_FIND', + 'AMAZON_ADS_AD_GROUPS_FIND', + 'AMAZON_ADS_TARGETS_FIND', + 'AMAZON_ADS_ADS_FIND', + 'AMAZON_ADS_AD_ASSOCIATIONS_FIND' +] as const; +export type ActionType = (typeof ActionTypes)[number]; + +export const ActionStatuses = [ + 'PENDING', + 'IN_PROGRESS', + 'WAITING_EXTERNAL_PROCESSING', + 'COMPLETED', + 'PARTIALLY_COMPLETED', + 'COMPLETED_WITH_ISSUES', + 'ERROR', + 'BLOCKED_NO_TOKENS', + 'BLOCKED_INVALID_INPUT', + 'VALIDATED', + 'CANCELED' +] as const; + +export const ActionCreators = ['API', 'MCP', 'SYSTEM'] as const; + +export const ActionsDetailsSchemaGetInputSchema = z + .object({ + type: z.enum(ActionTypes).describe('Action type to retrieve the details payload schema for.') + }) + .strict(); + +export const ActionsStartInputSchema = z + .object({ + type: z + .enum(ActionTypes) + .describe('Type of the action to start. The details field must match this action type.'), + sellerOrVendorId: ZodUUID, + details: z + .record(z.string(), z.unknown()) + .describe( + 'Action payload, specific to the action type. Retrieve the exact schema with actions_details_schema_get.' + ), + dryRun: z + .boolean() + .optional() + .describe('When true, the action is validated without being executed.') + }) + .strict(); + +export const ActionsGetInputSchema = z + .object({ + actionId: ZodUUID + }) + .strict(); + +export const ActionsListInputSchema = z + .object({ + page: z.number().int().min(1).optional().describe('Page number, starting at 1.'), + pageSize: z.number().int().min(1).max(5).optional().describe('Page size, max 5.'), + statuses: z.array(z.enum(ActionStatuses)).min(1).optional(), + types: z.array(z.enum(ActionTypes)).min(1).optional(), + creators: z.array(z.enum(ActionCreators)).min(1).optional(), + createdAtFrom: z.iso.datetime().optional(), + createdAtTo: z.iso.datetime().optional(), + updatedAtFrom: z.iso.datetime().optional(), + updatedAtTo: z.iso.datetime().optional() + }) + .strict(); + export const GENERIC_MCP_TOOL_RESPONSE_SCHEMA = buildMcpToolResponseSchema(); export const EXPORT_MCP_TOOL_RESPONSE_SCHEMA = buildMcpToolResponseSchema(ExportResultsSchema); @@ -223,6 +310,13 @@ const READONLY_ANNOTATIONS = { readOnlyHint: true } as const; +const WRITE_ACTION_ANNOTATIONS = { + destructiveHint: true, + idempotentHint: false, + openWorldHint: true, + readOnlyHint: false +} as const; + const NOOP_GENERIC_DATA = {} as const; const NOOP_RAW_EXPORT_RESULT = { completed: false @@ -509,11 +603,97 @@ function createExportsMcpToolDefinitions(): readonly McpToolDefinition[] { ] as const; } +function createActionsMcpToolDefinitions(): readonly McpToolDefinition[] { + return [ + { + name: 'actions_details_schema_get', + title: 'Get action details payload schema', + description: + 'Returns the JSON Schema of the details payload required to start an action of the given type. Use it to build a valid payload before calling actions_start.', + inputSchema: ActionsDetailsSchemaGetInputSchema, + outputSchema: GENERIC_MCP_TOOL_RESPONSE_SCHEMA, + execute: (input: unknown): Promise => + executeWithErrorHandling( + 'actions_details_schema_get', + async (): Promise => { + ActionsDetailsSchemaGetInputSchema.parse(input); + return toMcpToolSuccessResult({ + toolName: 'actions_details_schema_get', + summary: + 'DataDoe MCP facade is a no-op server for actions_details_schema_get.', + data: NOOP_GENERIC_DATA, + outputSchema: GENERIC_MCP_TOOL_RESPONSE_SCHEMA + }); + } + ), + annotations: READONLY_ANNOTATIONS + }, + { + name: 'actions_start', + title: 'Start (or validate) an action on Amazon', + description: + 'Starts an action that changes the connected Amazon Seller or Vendor account (e.g. update listings, cancel orders, confirm shipments, manage Amazon Ads). Requires the action type, a sellerOrVendorId (from sellers_and_vendors_list), and a details payload matching the action type (see actions_details_schema_get). Set dryRun=true to validate the payload without executing. Returns an action id; poll actions_get for status and result.', + inputSchema: ActionsStartInputSchema, + outputSchema: GENERIC_MCP_TOOL_RESPONSE_SCHEMA, + execute: (input: unknown): Promise => + executeWithErrorHandling('actions_start', async (): Promise => { + ActionsStartInputSchema.parse(input); + return toMcpToolSuccessResult({ + toolName: 'actions_start', + summary: 'DataDoe MCP facade is a no-op server for actions_start.', + data: NOOP_GENERIC_DATA, + outputSchema: GENERIC_MCP_TOOL_RESPONSE_SCHEMA + }); + }), + annotations: WRITE_ACTION_ANNOTATIONS + }, + { + name: 'actions_get', + title: 'Get action status and result', + description: + 'Returns the current status and result of a single action by id. Poll this after actions_start until the action reaches a terminal status, then read the result field.', + inputSchema: ActionsGetInputSchema, + outputSchema: GENERIC_MCP_TOOL_RESPONSE_SCHEMA, + execute: (input: unknown): Promise => + executeWithErrorHandling('actions_get', async (): Promise => { + ActionsGetInputSchema.parse(input); + return toMcpToolSuccessResult({ + toolName: 'actions_get', + summary: 'DataDoe MCP facade is a no-op server for actions_get.', + data: NOOP_GENERIC_DATA, + outputSchema: GENERIC_MCP_TOOL_RESPONSE_SCHEMA + }); + }), + annotations: READONLY_ANNOTATIONS + }, + { + name: 'actions_list', + title: 'List past actions', + description: + 'Returns paginated action history for the organization. Supports filtering by status, type, creator (API/MCP/SYSTEM), and createdAt/updatedAt ranges. Max page size is 5.', + inputSchema: ActionsListInputSchema, + outputSchema: GENERIC_MCP_TOOL_RESPONSE_SCHEMA, + execute: (input: unknown): Promise => + executeWithErrorHandling('actions_list', async (): Promise => { + ActionsListInputSchema.parse(input); + return toMcpToolSuccessResult({ + toolName: 'actions_list', + summary: 'DataDoe MCP facade is a no-op server for actions_list.', + data: NOOP_GENERIC_DATA, + outputSchema: GENERIC_MCP_TOOL_RESPONSE_SCHEMA + }); + }), + annotations: READONLY_ANNOTATIONS + } + ] as const; +} + export function createMcpToolDefinitions(): readonly McpToolDefinition[] { return [ ...createDocsMcpToolDefinitions(), ...createUtilityMcpToolDefinitions(), - ...createExportsMcpToolDefinitions() + ...createExportsMcpToolDefinitions(), + ...createActionsMcpToolDefinitions() ] as const; } From f443d4c2d007dff376a623763fc2344207e1284e Mon Sep 17 00:00:00 2001 From: Jakob Wolitzki Date: Fri, 19 Jun 2026 19:18:21 +0300 Subject: [PATCH 2/4] DOE-2131: fix stale doc links and typo in facade source Full-repo review follow-up: - Fix broken data-doe-mcp slug + app host in the file header comment (-> www.datadoe.com/hub/docs/datadoe-mcp/overview). - Use canonical www host for the data-scheme link in exports_create. - Fix "unitily" -> "utility" typo in the exports_create description. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/index.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/index.ts b/src/index.ts index 78f15d5..9db608c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,7 +1,7 @@ /** * This server is just a scheme of the actual DataDoe MCP server made for exposing DataDoe MCP to various MCP registries. * It is a No-Op server, it does not do anything beside exposing the schema of DataDoe MCP. - * If you want to use DataDoe MCP, learn how to set it up here: https://app.datadoe.com/hub/docs/data-doe-mcp/overview. + * If you want to use DataDoe MCP, learn how to set it up here: https://www.datadoe.com/hub/docs/datadoe-mcp/overview. */ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; @@ -518,7 +518,7 @@ function createExportsMcpToolDefinitions(): readonly McpToolDefinition[] { { name: 'exports_create', title: 'Create a new export', - description: `Creates an export job that runs a structured query against DataDoe's Amazon dataset for one or more sellers/vendors and produces a downloadable file (CSV or JSON). Required inputs: sellerOrVendorIds (from sellers_and_vendors_list), sourceId and columns (from exports_sources_get - each source exposes its own column set), and outputType (CSV or JSON). Optional inputs shape the query like SQL: filters (WHERE - applied to raw rows before aggregation, with and/or combinators and per-rule operators including =, >, in, between, contains, null, etc.), groupBy and aggregations (GROUP BY + sum/avg/count/min/max with optional aliases), from/to (inclusive date range on the source's primary date column), dateInterval (DAY/WEEK/MONTH - collapses a date group-by to that bucket), orderByColumn + orderByDirection, and limit/skip (pagination; limit is capped at ${MCP_EXPORT_MAX_ROW_LIMIT} rows per export). Returns an export id and a status. Exports run asynchronously; status transitions from PENDING/PROCESSING to COMPLETED or FAILED. Poll exports_get to track status, then read the result with exports_raw_download (inline content) or exports_raw_url_get (presigned URL). If a query would naturally exceed ${MCP_EXPORT_MAX_ROW_LIMIT} rows, narrow it via higher-level aggregation, filters, or top-N ordering, or paginate with skip. Column names and source schemas are defined per source - see exports_sources_get and the public DataDoe API reference at https://app.datadoe.com/hub/data-scheme. For easier analysis, the tool may add unitily columns to the resulting Export.`, + description: `Creates an export job that runs a structured query against DataDoe's Amazon dataset for one or more sellers/vendors and produces a downloadable file (CSV or JSON). Required inputs: sellerOrVendorIds (from sellers_and_vendors_list), sourceId and columns (from exports_sources_get - each source exposes its own column set), and outputType (CSV or JSON). Optional inputs shape the query like SQL: filters (WHERE - applied to raw rows before aggregation, with and/or combinators and per-rule operators including =, >, in, between, contains, null, etc.), groupBy and aggregations (GROUP BY + sum/avg/count/min/max with optional aliases), from/to (inclusive date range on the source's primary date column), dateInterval (DAY/WEEK/MONTH - collapses a date group-by to that bucket), orderByColumn + orderByDirection, and limit/skip (pagination; limit is capped at ${MCP_EXPORT_MAX_ROW_LIMIT} rows per export). Returns an export id and a status. Exports run asynchronously; status transitions from PENDING/PROCESSING to COMPLETED or FAILED. Poll exports_get to track status, then read the result with exports_raw_download (inline content) or exports_raw_url_get (presigned URL). If a query would naturally exceed ${MCP_EXPORT_MAX_ROW_LIMIT} rows, narrow it via higher-level aggregation, filters, or top-N ordering, or paginate with skip. Column names and source schemas are defined per source - see exports_sources_get and the public DataDoe API reference at https://www.datadoe.com/hub/data-scheme. For easier analysis, the tool may add utility columns to the resulting Export.`, inputSchema: ExportsCreateInputSchema, outputSchema: EXPORT_MCP_TOOL_RESPONSE_SCHEMA, execute: (input: unknown): Promise => From 8f6df346ceddc364a9b6c3b32aff6477ae123f46 Mon Sep 17 00:00:00 2001 From: Jakob Wolitzki Date: Fri, 19 Jun 2026 19:23:48 +0300 Subject: [PATCH 3/4] Update README.md --- .DS_Store | Bin 0 -> 8196 bytes README.md | 40 ++++++++++++++++++++-------------------- 2 files changed, 20 insertions(+), 20 deletions(-) create mode 100644 .DS_Store diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..e8d45f7312e3480c4b30f39c6b6da4d2ed07ab00 GIT binary patch literal 8196 zcmeHM&rcIU6n<0Cb_HZnP{f!t^kSkSDlr&iCp{#6Yn%M;eLef7# z4|>GnA7zPXjhJpRS0G`>hBz8IX z^{8nL1BQYBk^#9tB(X}Fj$~C!wRK>lQUH{#*sTicm?R<%@6^r^E4547oAP(L zlrmTceyF0r4Yq~#pc3W!ZweLP3&O#{k0jR8df;F@ZpGW;_jAj9Jr_FRYLIcng1nmH z+%MF0r!ec$^}O9Z##!iij0y$tiWE&2?|Q7r*E4*T6$6FM=>f}1Sb4i|YwO(5rNP0o z$;-pT+h>zoS1zJHbmijqww35foxeJrU-8R~KT-D$B-%KjLtp=DpQ6?hZyzl`yJyx7a4z*E|i2< z%vBuMW2L!}J`QuAu1=rN+ns?c zxbIK#zzaRj<`)BGI~&q+mMw9NxQ0wmR^(7HOGSWk2WD>G5yD|5n%TJTI|b@bvJ4MH zUY_$@&h(vkDz|t!C8%_n8u_NFOr>wul+#+VA*B_3$Ly|YktC^ir7udKVVqGbm7dZg z79Ip=U=(h{EUdsLJcAeT3f{td_yk|!JBbsU^pi7Wh+HEh!C=5toUeu+5*CGc@6l(7!LBU}(1Sl#C=xg1_&tzQmtxCL1lg9*3; zIhbg)CjCv;?NCAAF3!urSai22X6>r(yklwW;MSU=5>) z-QvU~WA&&OLT_%_S3!u@qzV z2y_19BQnJ>uon!pXs5k0|DV|X`~O~qHa-mlhJk&;0BIf1jmsDP+M84JeaW|rB-V#m sWs!DOEfoYCX(IboI*#(!ABLzWqp@@(t6Jg+7V{xM(O??Gz&~Z+C*3MVk^lez literal 0 HcmV?d00001 diff --git a/README.md b/README.md index e4cc090..06c6046 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # Amazon Seller MCP Server - DataDoe -> **Hosted Amazon Seller Central & Vendor Central MCP server โ€” now read _and_ write.** Connect Claude, ChatGPT, Cursor, Codex, Gemini, and GitHub Copilot to live Amazon SP-API and Amazon Ads API data, then let your AI agent **act**: update listings, manage orders, and optimize Amazon Ads campaigns. DataDoe handles the SP-API developer approval, OAuth, and rate limits so your AI agent starts querying โ€” and acting โ€” in under a minute. +> **Hosted Amazon Seller Central & Vendor Central MCP server with read and write access.** Connect Claude, ChatGPT, Cursor, Codex, Gemini, and GitHub Copilot to live Amazon SP-API and Amazon Ads API data, then let your AI agent act on it: update listings, manage orders, and optimize Amazon Ads campaigns. DataDoe handles the SP-API developer approval, OAuth, and rate limits so your AI agent starts working in under a minute. [![Amazon Seller & Vendor](https://img.shields.io/badge/Amazon-Seller%20%26%20Vendor-FF9900?style=flat-square)](https://www.datadoe.com/) [![SP-API Selling Partner API](https://img.shields.io/badge/SP--API-Selling%20Partner-FF6F00?style=flat-square)](https://developer-docs.amazon.com/sp-api/) [![Amazon Ads API](https://img.shields.io/badge/Amazon-Ads%20API-232F3E?style=flat-square)](https://advertising.amazon.com/API/docs) [![MCP Server](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-8A2BE2?style=flat-square)](https://modelcontextprotocol.io/) -[![Read and Write](https://img.shields.io/badge/Amazon-Read%20%2B%20Write-2EA043?style=flat-square)](#actions--let-your-ai-agent-write-to-amazon) +[![Read and Write](https://img.shields.io/badge/Amazon-Read%20%2B%20Write-2EA043?style=flat-square)](#actions-write-to-amazon) [![AI clients supported](https://img.shields.io/badge/AI%20clients-20%2B%20guides-D97757?style=flat-square)](#quick-setup-per-ai-client) [![smithery badge](https://smithery.ai/badge/jakopv007/datadoe-mcp)](https://smithery.ai/servers/jakopv007/datadoe-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE) @@ -51,7 +51,7 @@ DataDoe MCP gives your AI agent two layers over your Amazon account: Building your own Amazon SP-API integration typically requires SP-API developer registration, OAuth refresh-token flow, marketplace-specific endpoints, throttling logic, and 2-4 weeks of Amazon approval. DataDoe takes care of all of that. You get a single authenticated MCP URL for both reading and acting on your Amazon data. -![DataDoe MCP Banner](/assets/datadoe-mcp-banner.png) +![DataDoe MCP - Amazon Seller Central, Vendor Central, and Amazon Ads data for AI agents via SP-API](/assets/datadoe-mcp-banner.png) ## Who is DataDoe MCP for? @@ -69,7 +69,7 @@ Building your own Amazon SP-API integration typically requires SP-API developer - โœ… **SKU-level resolution** - drill into individual ASINs, parent listings, marketplaces, time periods, ad campaigns, keyword reports, settlements, returns. - โœ… **Multi-marketplace, multi-account** - one MCP server covers every Amazon marketplace (US, UK, DE, FR, IT, ES, CA, AU, JP, MX, and more) across Seller Central and Vendor Central. - โœ… **AI-native by design** - `exports_create` accepts SQL-like filter groups, GROUP BY, aggregations, and date intervals, so your AI agent can build complex reports from one tool call. -- โœ… **Read _and_ write** - with [Actions](#actions--let-your-ai-agent-write-to-amazon), your agent doesn't just report - it updates listings, manages orders, and optimizes Amazon Ads, with a `dryRun` validation step and per-type controls. +- โœ… **Read and write** - with [Actions](#actions-write-to-amazon), your agent doesn't just report, it updates listings, manages orders, and optimizes Amazon Ads, with a `dryRun` validation step and per-type controls. - โœ… **Always-on hosted infrastructure** - DataDoe manages SP-API rate limits, token rotation, and ongoing maintenance. ## What can you ask DataDoe MCP? @@ -92,28 +92,28 @@ And with **Actions** enabled, your agent can act on what it finds: - *"Update the price of SKU ABC-123 to 19.99 and refresh its bullet points."* - *"Confirm shipment for order 123-4567890-1234567 with UPS tracking 1Z999..."* -## Actions โ€” let your AI agent write to Amazon +## Actions: write to Amazon -DataDoe MCP is not read-only. **Actions** let your AI agent make changes on your connected Amazon Seller Central, Vendor Central, and Amazon Ads accounts through the SP-API and Amazon Ads API โ€” all monitored and auditable. +Actions let your AI agent make changes on your connected Amazon Seller Central, Vendor Central, and Amazon Ads accounts through the SP-API and Amazon Ads API. Every Action is recorded and auditable. -**What your agent can do:** +What your agent can do: -- **Listings** - update the title, bullet points, description, price, generic keyword, and item-type keyword of an Amazon listing (`AMAZON_LISTINGS_UPDATE`). -- **Orders** - cancel an order item with a reason (`AMAZON_ORDERS_CANCEL`) and confirm shipment with tracking info (`AMAZON_ORDERS_CONFIRM_SHIPMENT`). -- **Amazon Ads** - add, update, remove, and find campaigns, ad groups, targets, ads, and ad associations across Sponsored Products, Sponsored Brands, Sponsored Display, Sponsored TV, and Amazon DSP. +- **Listings** - update the title, bullet points, description, price, generic keyword, and item-type keyword (`AMAZON_LISTINGS_UPDATE`). +- **Orders** - cancel an order item with a reason (`AMAZON_ORDERS_CANCEL`) or confirm shipment and upload tracking (`AMAZON_ORDERS_CONFIRM_SHIPMENT`). +- **Amazon Ads** - add, update, remove, and find campaigns, ad groups, targets, ads, and ad associations across Sponsored Products, Brands, Display, TV, and Amazon DSP. -**Safe-by-design flow** โ€” the agent runs each Action through these MCP tools: +How it works - the agent runs each Action through these MCP tools: -1. `actions_details_schema_get` - fetch the exact payload schema for the Action type. +1. `actions_details_schema_get` - get the payload schema for the Action type. 2. `actions_start` with `dryRun=true` - validate the payload without executing. -3. `actions_start` - execute the Action and get an action id. -4. `actions_get` - poll until the Action completes, then read the `result`. +3. `actions_start` - run the Action and get an action id. +4. `actions_get` - poll until it completes, then read the `result`. Use `actions_list` to review past Actions (filter by status, type, creator, and date). -**You stay in control.** All Action types are **disabled by default** and enabled per-type in [Settings โ†’ Actions](https://app.datadoe.com/settings?tab=actions). When a type is disabled, `actions_start` rejects live runs but still allows `dryRun` validation. Every Action is recorded and auditable. +Action types are disabled by default and enabled per type in [Settings > Actions](https://app.datadoe.com/settings?tab=actions). When a type is disabled, `actions_start` rejects live runs but still allows `dryRun` validation. -**Example** โ€” update a listing's price and title (the `details` payload for `AMAZON_LISTINGS_UPDATE`): +Example `details` payload for `AMAZON_LISTINGS_UPDATE`: ```json { @@ -133,7 +133,7 @@ Use `actions_list` to review past Actions (filter by status, type, creator, and } ``` -**Cost** โ€” running an Action costs 2 AI tokens (covers up to 100 entities), plus 1 token per additional 100 entities. See [Actions docs](https://www.datadoe.com/hub/docs/datadoe-features/actions) for the full Action catalog and payload schemas. +Running an Action costs 2 AI tokens for up to 100 entities, plus 1 token per additional 100. See the [Actions docs](https://www.datadoe.com/hub/docs/datadoe-features/actions) for the full catalog and payload schemas. ## Available MCP tools @@ -152,7 +152,7 @@ DataDoe MCP exposes the following tools to your AI client: | `datadoe_user_docs_page_get` | Docs | Returns the full content of a named DataDoe documentation page. | | `actions_details_schema_get` | Actions | Returns the JSON Schema of the `details` payload required to start a given Action type. | | `actions_start` | Actions | Starts an Action that changes your Amazon account (listings, orders, Amazon Ads). Set `dryRun=true` to validate without executing. Returns an action id. | -| `actions_get` | Actions | Returns the status and `result` of an Action by id โ€” poll after `actions_start`. | +| `actions_get` | Actions | Returns the status and `result` of an Action by id; poll after `actions_start`. | | `actions_list` | Actions | Returns paginated Action history, filterable by status, type, creator, and date. | --- @@ -290,9 +290,9 @@ To avoid confusion when evaluating Amazon MCP servers: - [DataDoe Actions (write to Amazon)](https://www.datadoe.com/hub/docs/datadoe-features/actions) - [Amazon data schema reference](https://www.datadoe.com/hub/data-scheme) - [DataDoe MCP product page](https://www.datadoe.com/connect/amazon/mcp) -- [DataDoe vs Amazon MCP comparison](https://datadoe.com/compare/datadoe-vs-amazon-mcp) +- [DataDoe vs Amazon MCP comparison](https://www.datadoe.com/compare/datadoe-vs-amazon-mcp) - [DataDoe MCP video demo](https://www.youtube.com/watch?v=9YQd7M2dMyY) -- [DataDoe blog: Amazon SP-API, Ads API, and MCP explainers](https://datadoe.com/blog) +- [DataDoe blog: Amazon SP-API, Ads API, and MCP explainers](https://www.datadoe.com/blog) - [Create a DataDoe MCP API key](https://app.datadoe.com/integrations/mcp) --- From b0d49bcbaa179a20e4c4712ed46c5144b304017b Mon Sep 17 00:00:00 2001 From: Jakob Wolitzki Date: Fri, 19 Jun 2026 19:25:13 +0300 Subject: [PATCH 4/4] Remove accidentally committed .DS_Store and gitignore it Co-Authored-By: Claude Opus 4.8 (1M context) --- .DS_Store | Bin 8196 -> 0 bytes .gitignore | 4 +++- 2 files changed, 3 insertions(+), 1 deletion(-) delete mode 100644 .DS_Store diff --git a/.DS_Store b/.DS_Store deleted file mode 100644 index e8d45f7312e3480c4b30f39c6b6da4d2ed07ab00..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 8196 zcmeHM&rcIU6n<0Cb_HZnP{f!t^kSkSDlr&iCp{#6Yn%M;eLef7# z4|>GnA7zPXjhJpRS0G`>hBz8IX z^{8nL1BQYBk^#9tB(X}Fj$~C!wRK>lQUH{#*sTicm?R<%@6^r^E4547oAP(L zlrmTceyF0r4Yq~#pc3W!ZweLP3&O#{k0jR8df;F@ZpGW;_jAj9Jr_FRYLIcng1nmH z+%MF0r!ec$^}O9Z##!iij0y$tiWE&2?|Q7r*E4*T6$6FM=>f}1Sb4i|YwO(5rNP0o z$;-pT+h>zoS1zJHbmijqww35foxeJrU-8R~KT-D$B-%KjLtp=DpQ6?hZyzl`yJyx7a4z*E|i2< z%vBuMW2L!}J`QuAu1=rN+ns?c zxbIK#zzaRj<`)BGI~&q+mMw9NxQ0wmR^(7HOGSWk2WD>G5yD|5n%TJTI|b@bvJ4MH zUY_$@&h(vkDz|t!C8%_n8u_NFOr>wul+#+VA*B_3$Ly|YktC^ir7udKVVqGbm7dZg z79Ip=U=(h{EUdsLJcAeT3f{td_yk|!JBbsU^pi7Wh+HEh!C=5toUeu+5*CGc@6l(7!LBU}(1Sl#C=xg1_&tzQmtxCL1lg9*3; zIhbg)CjCv;?NCAAF3!urSai22X6>r(yklwW;MSU=5>) z-QvU~WA&&OLT_%_S3!u@qzV z2y_19BQnJ>uon!pXs5k0|DV|X`~O~qHa-mlhJk&;0BIf1jmsDP+M84JeaW|rB-V#m sWs!DOEfoYCX(IboI*#(!ABLzWqp@@(t6Jg+7V{xM(O??Gz&~Z+C*3MVk^lez diff --git a/.gitignore b/.gitignore index 9a7ec7d..ec85802 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,6 @@ !.yarn/versions node_modules -dist \ No newline at end of file +dist + +.DS_Store \ No newline at end of file