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 diff --git a/README.md b/README.md index b738851..06c6046 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 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/) -[![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-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,9 +44,14 @@ 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: -![DataDoe MCP Banner](/assets/datadoe-mcp-banner.png) +- **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 - 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? @@ -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-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: write to Amazon + +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: + +- **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. + +How it works - the agent runs each Action through these MCP tools: + +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` - 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). + +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 `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 + } + ] + } +} +``` + +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 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,12 +286,13 @@ 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 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) --- @@ -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..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'; @@ -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 @@ -424,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 => @@ -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; }