@amazon-sp-api-release/dev-mcp 0.0.1

package/README.md

@@ -0,0 +1,82 @@
+# Amazon SP-API Developer MCP Server
+
+A Model Context Protocol (MCP) server that provides tools for interacting with Amazon's Selling Partner API (SP-API), specifically focused on Orders API operations and migration assistance.
+
+## Features
+
+### Migration Assistant
+
+- `migration_assistant` - Assists with API version migrations
+  - Provides general migration guidance (without source code)
+  - Analyzes existing code and generates refactored implementations
+  - Supports: Orders API v0 → v2026-01-01
+
+### Orders API Tools
+
+**V1 API (2026-01-01)**
+- `search_orders` - Search orders with various filters (date, status, marketplace, etc.)
+- `get_order` - Get detailed information for a specific order
+- `cancel_order` - Cancel an order with a reason code
+
+**V0 API (Legacy)**
+- `update_shipment_status` - Update shipment status for an order
+- `update_verification_status` - Update verification status for regulated orders
+- `confirm_shipment` - Confirm shipment for an order
+- `get_order_regulated_info` - Get regulated information for compliance-related orders
+
+## Usage with MCP Clients
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "sp-api-dev": {
+      "command": "npx",
+      "args": ["-y", "@amazon-sp-api-release/dev-mcp-test"],
+      /**env variablea are optional, The migration assistant tool does not require credentials and can be used without API access.*/
+      "env": {
+        "SP_API_CLIENT_ID": "your_client_id",
+        "SP_API_CLIENT_SECRET": "your_client_secret",
+        "SP_API_REFRESH_TOKEN": "your_refresh_token",
+        "SP_API_BASE_URL": "https://sellingpartnerapi-na.amazon.com"
+      }
+    }
+  }
+}
+```
+
+## Usage Examples
+
+### Migration Assistant - General Guidance
+
+#### Prompt:
+```
+Guide me through the processes to migrate from orders V0 to V1.
+```
+
+#### Tool args:
+```typescript
+{
+  "source_version": "orders-v0",
+  "target_version": "orders-2026-01-01"
+}
+```
+
+### Migration Assistant - Code Analysis
+
+#### Prompt:
+```
+Help me refactor my orders V0 code
+<Code snippet>
+```
+
+#### Tool args:
+```typescript
+{
+  "source_code": "your existing code here",
+  "source_version": "orders-v0",
+  "target_version": "orders-2026-01-01",
+  "language": "javascript"
+}
+```

package/dist/auth/sp-api-auth.d.ts

@@ -0,0 +1,17 @@
+import { AxiosResponse } from "axios";
+export interface SPAPIConfig {
+    clientId?: string;
+    clientSecret?: string;
+    refreshToken?: string;
+    baseUrl?: string;
+}
+export declare class SPAPIAuth {
+    private config;
+    private accessToken;
+    private tokenExpiry;
+    private axiosInstance;
+    constructor(config: SPAPIConfig);
+    private getAccessToken;
+    makeAuthenticatedRequest<T = any>(method: string, url: string, params?: Record<string, string>, data?: any): Promise<AxiosResponse<T>>;
+}
+//# sourceMappingURL=sp-api-auth.d.ts.map

package/dist/auth/sp-api-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sp-api-auth.d.ts","sourceRoot":"","sources":["../../src/auth/sp-api-auth.ts"],"names":[],"mappings":"AAAA,OAAc,EAAqC,aAAa,EAAE,MAAM,OAAO,CAAC;AAEhF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,aAAa,CAAgB;gBAEzB,MAAM,EAAE,WAAW;YAKjB,cAAc;IAmCtB,wBAAwB,CAAC,CAAC,GAAG,GAAG,EACpC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EACnC,IAAI,GAAE,GAAU,GACf,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;CAqB7B"}

package/dist/auth/sp-api-auth.js

@@ -0,0 +1,55 @@
+import axios from "axios";
+export class SPAPIAuth {
+    config;
+    accessToken = null;
+    tokenExpiry = null;
+    axiosInstance;
+    constructor(config) {
+        this.config = config;
+        this.axiosInstance = axios.create();
+    }
+    async getAccessToken() {
+        // Check if we have a valid token
+        if (this.accessToken && this.tokenExpiry && Date.now() < this.tokenExpiry) {
+            return this.accessToken;
+        }
+        // Refresh the access token using LWA refresh token
+        try {
+            const response = await this.axiosInstance.post("https://api.amazon.com/auth/o2/token", {
+                grant_type: "refresh_token",
+                client_id: this.config.clientId,
+                client_secret: this.config.clientSecret,
+                refresh_token: this.config.refreshToken,
+            }, {
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+            });
+            this.accessToken = response.data.access_token;
+            // Set expiry 5 minutes before actual expiry to be safe
+            this.tokenExpiry = Date.now() + (response.data.expires_in - 300) * 1000;
+            return this.accessToken;
+        }
+        catch (error) {
+            throw new Error(`Failed to get access token: ${error.response?.data?.error_description || error.message}`);
+        }
+    }
+    async makeAuthenticatedRequest(method, url, params = {}, data = null) {
+        const accessToken = await this.getAccessToken();
+        const config = {
+            method,
+            url,
+            headers: {
+                "x-amz-access-token": accessToken,
+                "Content-Type": "application/json",
+                "User-Agent": "SP-API-Orders-V1-MCP/1.1.0",
+            },
+            params,
+            timeout: 30000,
+        };
+        if (data && (method === "POST" || method === "PUT")) {
+            config.data = data;
+        }
+        return this.axiosInstance.request(config);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { OrdersApiTool, } from "./tools/api-tools/orders-api-tools.js";
+import { SPAPIMigrationAssistantTool } from "./tools/migration-assistant-tools/migration-tools.js";
+import { searchOrdersSchema, getOrderSchema, cancelOrderSchema, updateShipmentStatusSchema, updateVerificationStatusSchema, confirmShipmentSchema, getOrderRegulatedInfoSchema, } from "./zod-schemas/orders-schemas.js";
+import { migrationAssistantSchema } from "./zod-schemas/migration-schemas.js";
+import { config } from "dotenv";
+config();
+class SPAPIDevMCPServer {
+    server;
+    ordersApiTool;
+    migrationAssistantTool;
+    constructor() {
+        this.server = new McpServer({
+            name: "selling-partner-api-dev-mcp",
+            version: "1.1.0",
+        });
+        const config = this.getAuthFromEnv();
+        this.ordersApiTool = new OrdersApiTool(config);
+        this.migrationAssistantTool = new SPAPIMigrationAssistantTool();
+        this.setupTools();
+    }
+    setupTools() {
+        // Register Orders API V1 Tools
+        this.server.registerTool("search_orders", {
+            description: "Search orders with various filters and include specific data sets. Use this to get orders by date, status, marketplace, etc.",
+            inputSchema: searchOrdersSchema,
+        }, async (args) => {
+            return await this.ordersApiTool.searchOrders(args);
+        });
+        this.server.registerTool("get_order", {
+            description: "Get detailed information for a specific order by order ID",
+            inputSchema: getOrderSchema,
+        }, async (args) => {
+            return await this.ordersApiTool.getOrder(args);
+        });
+        this.server.registerTool("cancel_order", {
+            description: "Cancel a specific order with a reason code",
+            inputSchema: cancelOrderSchema,
+        }, async (args) => {
+            return await this.ordersApiTool.cancelOrder(args);
+        });
+        // Register Orders API V0 Tools
+        this.server.registerTool("update_shipment_status", {
+            description: "Update shipment status for an order (V0 API - for orders that require shipment status updates)",
+            inputSchema: updateShipmentStatusSchema,
+        }, async (args) => {
+            return await this.ordersApiTool.updateShipmentStatus(args);
+        });
+        this.server.registerTool("update_verification_status", {
+            description: "Update verification status for regulated orders (V0 API - for compliance-related orders)",
+            inputSchema: updateVerificationStatusSchema,
+        }, async (args) => {
+            return await this.ordersApiTool.updateVerificationStatus(args);
+        });
+        this.server.registerTool("confirm_shipment", {
+            description: "Confirm shipment for an order (V0 API - for orders that require shipment confirmation)",
+            inputSchema: confirmShipmentSchema,
+        }, async (args) => {
+            return await this.ordersApiTool.confirmShipment(args);
+        });
+        this.server.registerTool("get_order_regulated_info", {
+            description: "Get regulated information for an order (V0 API - for compliance-related orders)",
+            inputSchema: getOrderRegulatedInfoSchema,
+        }, async (args) => {
+            return await this.ordersApiTool.getOrderRegulatedInfo(args);
+        });
+        // Register Migration Assistant Tool
+        this.server.registerTool("migration_assistant", {
+            description: "Assists with API version migrations. Can provide general migration guidance or analyze existing code and generate refactored implementations. When source_code is provided: returns detailed analysis with deprecated endpoints, breaking changes, refactored code, and migration checklist. When source_code is omitted: returns comprehensive migration guide with API mappings, attribute changes, code examples, and best practices. Supported Migrations: Orders API v0 → v2026-01-01",
+            inputSchema: migrationAssistantSchema,
+        }, async (args) => {
+            return await this.migrationAssistantTool.migrationAssistant(args);
+        });
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+    }
+    getAuthFromEnv() {
+        return {
+            clientId: process.env.SP_API_CLIENT_ID,
+            clientSecret: process.env.SP_API_CLIENT_SECRET,
+            refreshToken: process.env.SP_API_REFRESH_TOKEN,
+            baseUrl: process.env.SP_API_BASE_URL,
+        };
+    }
+}
+try {
+    const server = new SPAPIDevMCPServer();
+    await server.run();
+}
+catch (error) {
+    process.exit(1);
+}

package/dist/tools/api-tools/orders-api-tools.d.ts

@@ -0,0 +1,103 @@
+export interface SPAPIConfig {
+    clientId?: string;
+    clientSecret?: string;
+    refreshToken?: string;
+    baseUrl?: string;
+}
+export interface SearchOrdersArgs {
+    createdAfter?: string;
+    createdBefore?: string;
+    lastUpdatedAfter?: string;
+    lastUpdatedBefore?: string;
+    fulfillmentStatuses?: Array<"PENDING" | "UNSHIPPED" | "PARTIALLY_SHIPPED" | "SHIPPED" | "CANCELLED" | "UNFULFILLABLE">;
+    marketplaceIds?: string[];
+    fulfilledBy?: Array<"AMAZON" | "MERCHANT">;
+    maxResultsPerPage?: number;
+    includedData?: Array<"BUYER" | "RECIPIENT" | "PROCEEDS" | "EXPENSE" | "PROMOTION" | "CANCELLATION" | "FULFILLMENT" | "PACKAGES">;
+    paginationToken?: string;
+}
+export interface GetOrderArgs {
+    orderId: string;
+    includedData?: Array<"BUYER" | "RECIPIENT" | "PROCEEDS" | "EXPENSE" | "PROMOTION" | "CANCELLATION" | "FULFILLMENT" | "PACKAGES">;
+}
+export interface CancelOrderArgs {
+    orderId: string;
+    cancelReasonCode: "NO_INVENTORY" | "BUYER_CANCELLED" | "SHIPPING_ADDRESS_UNDELIVERABLE" | "CUSTOMER_EXCHANGE" | "PRICING_ERROR";
+}
+export interface UpdateShipmentStatusArgs {
+    orderId: string;
+    marketplaceId: string;
+    shipmentStatus: "ReadyForPickup" | "PickedUp" | "RefusedPickup";
+    orderItems?: Array<{
+        orderItemId?: string;
+        quantity?: number;
+    }>;
+}
+export interface UpdateVerificationStatusArgs {
+    orderId: string;
+    marketplaceId: string;
+    regulatedOrderVerificationStatus: {
+        status: "Approved" | "Rejected" | "Expired" | "Cancelled";
+        validUntil?: string;
+        rejectionReason?: {
+            rejectionReasonId: string;
+            rejectionReasonDescription: string;
+        };
+    };
+}
+export interface ConfirmShipmentArgs {
+    orderId: string;
+    marketplaceId: string;
+    packageDetail: {
+        packageReferenceId: string;
+        carrierCode: string;
+        shippingMethod?: string;
+        trackingNumber?: string;
+        shipDate: string;
+        carrierName?: string;
+        shipFrom?: {
+            name: string;
+            addressLine1: string;
+            addressLine2?: string;
+            addressLine3?: string;
+            city: string;
+            county?: string;
+            district?: string;
+            stateOrRegion: string;
+            postalCode: string;
+            countryCode: string;
+            phone: string;
+        };
+    };
+    codCollectionMethod?: "DirectPayment";
+}
+export interface GetOrderRegulatedInfoArgs {
+    orderId: string;
+}
+export interface ToolResponse {
+    content: Array<{
+        type: "text";
+        text: string;
+        meta?: Record<string, unknown>;
+    }>;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+export declare class OrdersApiTool {
+    private config;
+    private auth?;
+    private hasCredentials;
+    constructor(config?: SPAPIConfig);
+    private checkCredentials;
+    searchOrders(args: SearchOrdersArgs): Promise<ToolResponse>;
+    getOrder(args: GetOrderArgs): Promise<ToolResponse>;
+    cancelOrder(args: CancelOrderArgs): Promise<ToolResponse>;
+    updateShipmentStatus(args: UpdateShipmentStatusArgs): Promise<ToolResponse>;
+    updateVerificationStatus(args: UpdateVerificationStatusArgs): Promise<ToolResponse>;
+    confirmShipment(args: ConfirmShipmentArgs): Promise<ToolResponse>;
+    getOrderRegulatedInfo(args: GetOrderRegulatedInfoArgs): Promise<ToolResponse>;
+    private formatOrdersResponse;
+    private formatOrderResponse;
+    private formatRegulatedInfoResponse;
+}
+//# sourceMappingURL=orders-api-tools.d.ts.map

package/dist/tools/api-tools/orders-api-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orders-api-tools.d.ts","sourceRoot":"","sources":["../../../src/tools/api-tools/orders-api-tools.ts"],"names":[],"mappings":"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"}