swagmanager-mcp 1.0.0

package/README.md

@@ -0,0 +1,95 @@
+# @swagmanager/mcp
+
+MCP (Model Context Protocol) server for SwagManager — manage inventory, orders, analytics, customers, and more from Claude Code or Claude Desktop.
+
+## Setup
+
+```bash
+npm install -g @swagmanager/mcp
+```
+
+### Environment Variables
+
+Create a `.env` file or set these environment variables:
+
+```
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
+DEFAULT_STORE_ID=your-store-uuid
+```
+
+### Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "swagmanager": {
+      "command": "swagmanager-mcp",
+      "env": {
+        "SUPABASE_URL": "https://your-project.supabase.co",
+        "SUPABASE_SERVICE_ROLE_KEY": "your-key",
+        "DEFAULT_STORE_ID": "your-store-uuid"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to your Claude Desktop MCP config:
+
+```json
+{
+  "mcpServers": {
+    "swagmanager": {
+      "command": "npx",
+      "args": ["@swagmanager/mcp"],
+      "env": {
+        "SUPABASE_URL": "https://your-project.supabase.co",
+        "SUPABASE_SERVICE_ROLE_KEY": "your-key",
+        "DEFAULT_STORE_ID": "your-store-uuid"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+Tools are loaded dynamically from the `ai_tool_registry` database table. The default set includes:
+
+| Tool | Description |
+|------|-------------|
+| `analytics` | Sales analytics with flexible date ranges |
+| `inventory` | Adjust quantities, set stock, transfer between locations |
+| `inventory_query` | Query inventory summary, velocity, by location |
+| `inventory_audit` | Start, count, complete inventory audits |
+| `orders` | Find orders, get details, purchase orders |
+| `purchase_orders` | Create, approve, receive, cancel purchase orders |
+| `transfers` | Transfer inventory between locations |
+| `products` | Find, create, update products and pricing |
+| `customers` | Find, create, update customers |
+| `collections` | Manage product collections |
+| `suppliers` | Find and list suppliers |
+| `locations` | Find store locations |
+| `email` | Send emails, manage inbox |
+| `alerts` | Low stock and pending order alerts |
+| `documents` | Generate COAs and documents |
+| `audit_trail` | View audit logs |
+
+## Development
+
+```bash
+git clone https://github.com/floradistro/whale-mcp.git
+cd whale-mcp
+npm install
+cp .env.example .env  # fill in your credentials
+npm run dev
+```
+
+## License
+
+MIT

package/bin/swagmanager-mcp.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+/**
+ * SwagManager MCP Server CLI
+ *
+ * Usage:
+ *   npx @swagmanager/mcp
+ *   swagmanager-mcp
+ *
+ * Environment variables:
+ *   SUPABASE_URL              - Your Supabase project URL
+ *   SUPABASE_SERVICE_ROLE_KEY - Your Supabase service role key
+ *   STORE_ID                  - Default store ID (optional)
+ *   SWAG_API_KEY              - API key for auth (future)
+ */
+
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Import and run the server
+const serverPath = join(__dirname, "..", "dist", "index.js");
+await import(serverPath);

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * SwagManager MCP Server
+ *
+ * Standalone MCP server for managing inventory, orders, analytics,
+ * customers, products, and more from any MCP client (Claude Code,
+ * Claude Desktop, Cursor, etc.)
+ *
+ * Connects to your Supabase backend. Tools are loaded dynamically
+ * from the ai_tool_registry table.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * SwagManager MCP Server
+ *
+ * Standalone MCP server for managing inventory, orders, analytics,
+ * customers, products, and more from any MCP client (Claude Code,
+ * Claude Desktop, Cursor, etc.)
+ *
+ * Connects to your Supabase backend. Tools are loaded dynamically
+ * from the ai_tool_registry table.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createClient } from "@supabase/supabase-js";
+import { executeTool, getImplementedTools } from "./tools/executor.js";
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+const SUPABASE_URL = process.env.SUPABASE_URL || "";
+const SUPABASE_KEY = process.env.SUPABASE_SERVICE_ROLE_KEY || "";
+const STORE_ID = process.env.STORE_ID || "";
+if (!SUPABASE_URL || !SUPABASE_KEY) {
+    console.error("Error: SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY environment variables required");
+    console.error("");
+    console.error("Set them in your MCP client config:");
+    console.error('  "env": {');
+    console.error('    "SUPABASE_URL": "https://your-project.supabase.co",');
+    console.error('    "SUPABASE_SERVICE_ROLE_KEY": "your-key-here"');
+    console.error("  }");
+    process.exit(1);
+}
+const supabase = createClient(SUPABASE_URL, SUPABASE_KEY);
+// Session ID for tracing — links all tool calls in one conversation
+const SESSION_ID = crypto.randomUUID();
+let toolDefinitions = [];
+let toolsLoadedAt = 0;
+const TOOL_CACHE_TTL = 60_000; // 1 minute
+async function loadToolDefinitions(force = false) {
+    if (!force && toolDefinitions.length > 0 && Date.now() - toolsLoadedAt < TOOL_CACHE_TTL) {
+        return toolDefinitions;
+    }
+    try {
+        const { data, error } = await supabase
+            .from("ai_tool_registry")
+            .select("name, description, definition")
+            .eq("is_active", true);
+        if (error) {
+            console.error("[MCP] Failed to load tools from registry:", error.message);
+            return toolDefinitions; // Return stale cache on error
+        }
+        toolDefinitions = (data || []).map(t => ({
+            name: t.name,
+            description: t.description || t.definition?.description || `Execute ${t.name}`,
+            inputSchema: t.definition?.input_schema || { type: "object", properties: {} }
+        }));
+        toolsLoadedAt = Date.now();
+        return toolDefinitions;
+    }
+    catch (err) {
+        console.error("[MCP] Error loading tool definitions:", err);
+        return toolDefinitions;
+    }
+}
+// ============================================================================
+// MCP SERVER
+// ============================================================================
+const server = new Server({ name: "swagmanager", version: "1.0.0" }, { capabilities: { tools: {} } });
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const tools = await loadToolDefinitions();
+    console.error(`[MCP] Returning ${tools.length} tools`);
+    return {
+        tools: tools.map(t => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        })),
+    };
+});
+// Execute a tool
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const toolName = request.params.name;
+    const toolArgs = (request.params.arguments || {});
+    console.error(`[MCP] Executing: ${toolName}`);
+    // Validate tool is implemented
+    const implementedTools = getImplementedTools();
+    if (!implementedTools.includes(toolName)) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ error: `Tool "${toolName}" not implemented` }),
+                }],
+            isError: true,
+        };
+    }
+    // Execute with telemetry context
+    const result = await executeTool(supabase, toolName, toolArgs, STORE_ID || undefined, {
+        source: "mcp",
+        requestId: SESSION_ID
+    });
+    if (result.success) {
+        return {
+            content: [{
+                    type: "text",
+                    text: typeof result.data === "string"
+                        ? result.data
+                        : JSON.stringify(result.data, null, 2),
+                }],
+        };
+    }
+    else {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ error: result.error }),
+                }],
+            isError: true,
+        };
+    }
+});
+// ============================================================================
+// STARTUP
+// ============================================================================
+async function main() {
+    console.error("[MCP] SwagManager MCP Server v1.0.0");
+    console.error(`[MCP] Supabase: ${SUPABASE_URL}`);
+    console.error(`[MCP] Store: ${STORE_ID || "(default)"}`);
+    console.error(`[MCP] Session: ${SESSION_ID}`);
+    // Pre-load tools
+    const tools = await loadToolDefinitions(true);
+    console.error(`[MCP] Loaded ${tools.length} tools`);
+    // Connect via stdio
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[MCP] Ready");
+}
+main().catch((err) => {
+    console.error("[MCP] Fatal:", err);
+    process.exit(1);
+});

package/dist/services/tool-registry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Tool Registry
+ *
+ * Loads tools from Supabase ai_tool_registry.
+ * Used by the agent server to know which tools are available.
+ */
+export interface ToolRegistryEntry {
+    id: string;
+    name: string;
+    category: string;
+    description: string | null;
+    definition: {
+        name: string;
+        description: string;
+        input_schema: {
+            type: "object";
+            properties: Record<string, any>;
+            required?: string[];
+        };
+    };
+    rpc_function: string | null;
+    edge_function: string | null;
+    requires_store_id: boolean;
+    requires_user_id: boolean;
+    is_read_only: boolean;
+    is_active: boolean;
+    tool_mode: string;
+}
+export interface ClientToolMetadata {
+    id: string;
+    name: string;
+    description: string;
+    category: string;
+}
+export declare function invalidateToolCache(): void;
+export declare function loadToolRegistry(supabaseUrl: string, supabaseKey: string, forceRefresh?: boolean): Promise<ToolRegistryEntry[]>;
+export declare function getToolMetadata(tools: ToolRegistryEntry[]): ClientToolMetadata[];

package/dist/services/tool-registry.js

@@ -0,0 +1,49 @@
+/**
+ * Tool Registry
+ *
+ * Loads tools from Supabase ai_tool_registry.
+ * Used by the agent server to know which tools are available.
+ */
+import { createClient } from "@supabase/supabase-js";
+// ============================================================================
+// TOOL REGISTRY LOADER
+// ============================================================================
+let cachedTools = null;
+let cacheTimestamp = 0;
+const CACHE_TTL = 60000; // 1 minute cache
+export function invalidateToolCache() {
+    cachedTools = null;
+    cacheTimestamp = 0;
+}
+export async function loadToolRegistry(supabaseUrl, supabaseKey, forceRefresh = false) {
+    // Return cached if fresh
+    if (!forceRefresh && cachedTools && Date.now() - cacheTimestamp < CACHE_TTL) {
+        return cachedTools;
+    }
+    const supabase = createClient(supabaseUrl, supabaseKey);
+    const { data, error } = await supabase
+        .from("ai_tool_registry")
+        .select("*")
+        .eq("is_active", true)
+        .order("category", { ascending: true });
+    if (error) {
+        console.error("[ToolRegistry] Failed to load tools:", error.message);
+        return cachedTools || [];
+    }
+    cachedTools = data;
+    cacheTimestamp = Date.now();
+    // Import dynamically to avoid circular dependency
+    const { getImplementedTools } = await import("../tools/executor.js");
+    const implementedTools = getImplementedTools();
+    const implementedCount = cachedTools.filter(t => implementedTools.includes(t.name)).length;
+    console.log(`[ToolRegistry] Loaded ${cachedTools.length} tools from registry (${implementedCount} implemented locally)`);
+    return cachedTools;
+}
+export function getToolMetadata(tools) {
+    return tools.map(t => ({
+        id: t.name,
+        name: t.definition?.name || t.name,
+        description: t.description || t.definition?.description || "",
+        category: t.category
+    }));
+}

package/dist/tools/executor.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Consolidated Tool Executor
+ *
+ * Following Anthropic's best practices for tool design:
+ * - "More tools don't always lead to better outcomes"
+ * - "Claude Code uses about a dozen tools"
+ * - "Consolidate multi-step operations into single tool calls"
+ *
+ * 39 tools → 12 consolidated tools:
+ *
+ * 1. inventory      - manage inventory (adjust, set, transfer, bulk operations)
+ * 2. inventory_query - query inventory (summary, velocity, by_location, in_stock)
+ * 3. inventory_audit - audit workflow (start, count, complete, summary)
+ * 4. collections    - manage collections (find, create, get_theme, set_theme, set_icon)
+ * 5. customers      - manage customers (find, create, update)
+ * 6. products       - manage products (find, create, update, pricing)
+ * 7. analytics      - analytics & intelligence (summary, by_location, detailed, discover, employee, customers, products, inventory_intelligence, marketing, fraud, employee_performance, behavior, full)
+ * 8. locations      - find/list locations
+ * 9. orders         - manage orders (find, get, create)
+ * 10. suppliers     - find suppliers
+ * 11. email         - unified email (send, send_template, list, get, templates)
+ * 12. documents     - document generation
+ * 13. alerts        - system alerts
+ * 14. audit_trail   - audit logs
+ */
+import { SupabaseClient } from "@supabase/supabase-js";
+export declare enum ToolErrorType {
+    RECOVERABLE = "recoverable",// Retry with same input (transient failure)
+    PERMANENT = "permanent",// Don't retry (invalid input, business logic error)
+    RATE_LIMIT = "rate_limit",// Exponential backoff needed
+    AUTH = "auth",// User permission issue
+    VALIDATION = "validation",// Bad input from AI
+    NOT_FOUND = "not_found"
+}
+export interface ToolResult {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+    errorType?: ToolErrorType;
+    retryable?: boolean;
+    timedOut?: boolean;
+}
+export type SpanKind = "CLIENT" | "SERVER" | "INTERNAL" | "PRODUCER" | "CONSUMER";
+export interface ExecutionContext {
+    source: "claude_code" | "swag_manager" | "api" | "edge_function" | "mcp" | "test";
+    userId?: string;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    traceFlags?: number;
+    requestId?: string;
+    parentId?: string;
+    serviceName?: string;
+    serviceVersion?: string;
+    agentId?: string;
+    agentName?: string;
+    conversationId?: string;
+    turnNumber?: number;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalCost?: number;
+    costBefore?: number;
+    turnCost?: number;
+}
+export declare function executeTool(supabase: SupabaseClient, toolName: string, args: Record<string, unknown>, storeId?: string, context?: ExecutionContext): Promise<ToolResult>;
+export declare function getImplementedTools(): string[];