woo-mcp-server 1.0.0

package/dist/server.d.cts

@@ -0,0 +1,151 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { WooCommerceApiResponse } from 'woocommerce-rest-ts-api';
+
+/**
+ * Environment-based configuration for the WooCommerce MCP server.
+ * Validates required credentials at startup — no silent fallbacks.
+ */
+
+/**
+ * Zod schema for MCP server environment configuration.
+ * WC_URL, WC_KEY, and WC_SECRET are mandatory; the server refuses to start without them.
+ */
+declare const ConfigSchema: z.ZodObject<{
+    WC_URL: z.ZodString;
+    WC_KEY: z.ZodString;
+    WC_SECRET: z.ZodString;
+    WC_VERSION: z.ZodDefault<z.ZodString>;
+    WC_RATE_LIMIT_PER_SECOND: z.ZodDefault<z.ZodNumber>;
+    WC_QUERY_STRING_AUTH: z.ZodEffects<z.ZodOptional<z.ZodEnum<["true", "false", "1", "0", ""]>>, boolean, "" | "0" | "true" | "false" | "1" | undefined>;
+}, "strip", z.ZodTypeAny, {
+    WC_URL: string;
+    WC_KEY: string;
+    WC_SECRET: string;
+    WC_VERSION: string;
+    WC_RATE_LIMIT_PER_SECOND: number;
+    WC_QUERY_STRING_AUTH: boolean;
+}, {
+    WC_URL: string;
+    WC_KEY: string;
+    WC_SECRET: string;
+    WC_VERSION?: string | undefined;
+    WC_RATE_LIMIT_PER_SECOND?: number | undefined;
+    WC_QUERY_STRING_AUTH?: "" | "0" | "true" | "false" | "1" | undefined;
+}>;
+type McpConfig = z.infer<typeof ConfigSchema>;
+/**
+ * Load and validate config from process.env.
+ * Throws a clear, actionable error if required vars are missing.
+ */
+declare function loadConfig(env?: NodeJS.ProcessEnv): McpConfig;
+
+/**
+ * WooCommerce API client factory with rate limiting.
+ *
+ * Uses the library's built-in Throttler (via maxConcurrentRequests) and an
+ * additional token-bucket style limiter driven by WC_RATE_LIMIT_PER_SECOND.
+ * Does NOT rewrite OAuth/HTTP — delegates entirely to WooCommerceRestApi.
+ */
+
+/**
+ * Rate limiter: enforces a maximum number of operations per second
+ * using a sliding window + the Throttler concurrency gate.
+ */
+declare class RateLimiter {
+    private readonly intervalMs;
+    private readonly throttler;
+    private lastRequestAt;
+    private chain;
+    constructor(requestsPerSecond: number, maxConcurrent?: number);
+    /**
+     * Schedule `fn` to run respecting both rate and concurrency limits.
+     */
+    schedule<T>(fn: () => Promise<T>): Promise<T>;
+}
+/** Minimal surface we need from WooCommerceRestApi (avoids default-export type issues). */
+interface WooApi {
+    get<T = unknown>(endpoint: string, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+    post<T = unknown>(endpoint: string, data: Record<string, unknown>, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+    put<T = unknown>(endpoint: string, data: Record<string, unknown>, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+    delete<T = unknown>(endpoint: string, data?: {
+        force?: boolean;
+    }, params?: {
+        id?: number;
+    }): Promise<WooCommerceApiResponse<T>>;
+    options<T = unknown>(endpoint: string, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+}
+interface WooClient {
+    api: WooApi;
+    rateLimiter: RateLimiter;
+    config: McpConfig;
+    /** Rate-limited GET */
+    get<T = unknown>(endpoint: string, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+    /** Rate-limited POST */
+    post<T = unknown>(endpoint: string, data: Record<string, unknown>, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+    /** Rate-limited PUT */
+    put<T = unknown>(endpoint: string, data: Record<string, unknown>, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+    /** Rate-limited DELETE */
+    delete<T = unknown>(endpoint: string, data?: {
+        force?: boolean;
+    }, params?: {
+        id?: number;
+    }): Promise<WooCommerceApiResponse<T>>;
+    /** Extract pagination meta from a list response */
+    pagination(response: WooCommerceApiResponse<unknown>, page: number, perPage: number): {
+        total: number;
+        totalPages: number;
+        currentPage: number;
+        perPage: number;
+    };
+}
+/**
+ * Create a rate-limited WooCommerce client from validated config.
+ */
+declare function createWooClient(config: McpConfig): WooClient;
+
+/**
+ * Registers all MCP tools, resources, and prompts on the server instance.
+ */
+
+/**
+ * Auto-register every tool, resource, and prompt.
+ */
+declare function registerAll(server: McpServer, client: WooClient): void;
+
+/**
+ * WooCommerce MCP server bootstrap (STDIO transport).
+ *
+ * Creates a configured McpServer, wires the WooCommerce client, and registers
+ * all tools/resources/prompts. The CLI entrypoint connects STDIO transport.
+ */
+
+declare const SERVER_NAME = "woo-mcp-server";
+declare const SERVER_VERSION = "1.0.0";
+interface CreateServerOptions {
+    /** Pre-validated config; if omitted, loaded from process.env */
+    config?: McpConfig;
+    /** Inject a pre-built client (tests) */
+    client?: WooClient;
+}
+interface CreatedServer {
+    server: McpServer;
+    client: WooClient;
+    config: McpConfig;
+}
+/**
+ * Build an MCP server instance with all capabilities registered.
+ * Does not connect transport — call connectStdio() or use startServer().
+ */
+declare function createServer(options?: CreateServerOptions): CreatedServer;
+/**
+ * Connect the server to STDIO transport (Claude Desktop compatible).
+ */
+declare function connectStdio(server: McpServer): Promise<void>;
+/**
+ * Full startup: validate env, create server, connect STDIO.
+ * Exits process with code 1 on configuration failure.
+ */
+declare function startServer(): Promise<CreatedServer>;
+
+export { type CreateServerOptions, type CreatedServer, type McpConfig, SERVER_NAME, SERVER_VERSION, type WooClient, connectStdio, createServer, createWooClient, loadConfig, registerAll, startServer };

package/dist/server.d.ts

@@ -0,0 +1,151 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { WooCommerceApiResponse } from 'woocommerce-rest-ts-api';
+
+/**
+ * Environment-based configuration for the WooCommerce MCP server.
+ * Validates required credentials at startup — no silent fallbacks.
+ */
+
+/**
+ * Zod schema for MCP server environment configuration.
+ * WC_URL, WC_KEY, and WC_SECRET are mandatory; the server refuses to start without them.
+ */
+declare const ConfigSchema: z.ZodObject<{
+    WC_URL: z.ZodString;
+    WC_KEY: z.ZodString;
+    WC_SECRET: z.ZodString;
+    WC_VERSION: z.ZodDefault<z.ZodString>;
+    WC_RATE_LIMIT_PER_SECOND: z.ZodDefault<z.ZodNumber>;
+    WC_QUERY_STRING_AUTH: z.ZodEffects<z.ZodOptional<z.ZodEnum<["true", "false", "1", "0", ""]>>, boolean, "" | "0" | "true" | "false" | "1" | undefined>;
+}, "strip", z.ZodTypeAny, {
+    WC_URL: string;
+    WC_KEY: string;
+    WC_SECRET: string;
+    WC_VERSION: string;
+    WC_RATE_LIMIT_PER_SECOND: number;
+    WC_QUERY_STRING_AUTH: boolean;
+}, {
+    WC_URL: string;
+    WC_KEY: string;
+    WC_SECRET: string;
+    WC_VERSION?: string | undefined;
+    WC_RATE_LIMIT_PER_SECOND?: number | undefined;
+    WC_QUERY_STRING_AUTH?: "" | "0" | "true" | "false" | "1" | undefined;
+}>;
+type McpConfig = z.infer<typeof ConfigSchema>;
+/**
+ * Load and validate config from process.env.
+ * Throws a clear, actionable error if required vars are missing.
+ */
+declare function loadConfig(env?: NodeJS.ProcessEnv): McpConfig;
+
+/**
+ * WooCommerce API client factory with rate limiting.
+ *
+ * Uses the library's built-in Throttler (via maxConcurrentRequests) and an
+ * additional token-bucket style limiter driven by WC_RATE_LIMIT_PER_SECOND.
+ * Does NOT rewrite OAuth/HTTP — delegates entirely to WooCommerceRestApi.
+ */
+
+/**
+ * Rate limiter: enforces a maximum number of operations per second
+ * using a sliding window + the Throttler concurrency gate.
+ */
+declare class RateLimiter {
+    private readonly intervalMs;
+    private readonly throttler;
+    private lastRequestAt;
+    private chain;
+    constructor(requestsPerSecond: number, maxConcurrent?: number);
+    /**
+     * Schedule `fn` to run respecting both rate and concurrency limits.
+     */
+    schedule<T>(fn: () => Promise<T>): Promise<T>;
+}
+/** Minimal surface we need from WooCommerceRestApi (avoids default-export type issues). */
+interface WooApi {
+    get<T = unknown>(endpoint: string, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+    post<T = unknown>(endpoint: string, data: Record<string, unknown>, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+    put<T = unknown>(endpoint: string, data: Record<string, unknown>, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+    delete<T = unknown>(endpoint: string, data?: {
+        force?: boolean;
+    }, params?: {
+        id?: number;
+    }): Promise<WooCommerceApiResponse<T>>;
+    options<T = unknown>(endpoint: string, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+}
+interface WooClient {
+    api: WooApi;
+    rateLimiter: RateLimiter;
+    config: McpConfig;
+    /** Rate-limited GET */
+    get<T = unknown>(endpoint: string, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+    /** Rate-limited POST */
+    post<T = unknown>(endpoint: string, data: Record<string, unknown>, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+    /** Rate-limited PUT */
+    put<T = unknown>(endpoint: string, data: Record<string, unknown>, params?: Record<string, unknown>): Promise<WooCommerceApiResponse<T>>;
+    /** Rate-limited DELETE */
+    delete<T = unknown>(endpoint: string, data?: {
+        force?: boolean;
+    }, params?: {
+        id?: number;
+    }): Promise<WooCommerceApiResponse<T>>;
+    /** Extract pagination meta from a list response */
+    pagination(response: WooCommerceApiResponse<unknown>, page: number, perPage: number): {
+        total: number;
+        totalPages: number;
+        currentPage: number;
+        perPage: number;
+    };
+}
+/**
+ * Create a rate-limited WooCommerce client from validated config.
+ */
+declare function createWooClient(config: McpConfig): WooClient;
+
+/**
+ * Registers all MCP tools, resources, and prompts on the server instance.
+ */
+
+/**
+ * Auto-register every tool, resource, and prompt.
+ */
+declare function registerAll(server: McpServer, client: WooClient): void;
+
+/**
+ * WooCommerce MCP server bootstrap (STDIO transport).
+ *
+ * Creates a configured McpServer, wires the WooCommerce client, and registers
+ * all tools/resources/prompts. The CLI entrypoint connects STDIO transport.
+ */
+
+declare const SERVER_NAME = "woo-mcp-server";
+declare const SERVER_VERSION = "1.0.0";
+interface CreateServerOptions {
+    /** Pre-validated config; if omitted, loaded from process.env */
+    config?: McpConfig;
+    /** Inject a pre-built client (tests) */
+    client?: WooClient;
+}
+interface CreatedServer {
+    server: McpServer;
+    client: WooClient;
+    config: McpConfig;
+}
+/**
+ * Build an MCP server instance with all capabilities registered.
+ * Does not connect transport — call connectStdio() or use startServer().
+ */
+declare function createServer(options?: CreateServerOptions): CreatedServer;
+/**
+ * Connect the server to STDIO transport (Claude Desktop compatible).
+ */
+declare function connectStdio(server: McpServer): Promise<void>;
+/**
+ * Full startup: validate env, create server, connect STDIO.
+ * Exits process with code 1 on configuration failure.
+ */
+declare function startServer(): Promise<CreatedServer>;
+
+export { type CreateServerOptions, type CreatedServer, type McpConfig, SERVER_NAME, SERVER_VERSION, type WooClient, connectStdio, createServer, createWooClient, loadConfig, registerAll, startServer };