@whattio/mcp-server 1.0.0

package/build/tools/v2/product.js

@@ -0,0 +1,99 @@
+export const productTools = [
+    {
+        name: "v2_list_products",
+        description: "Retrieve a paginated list of all products belonging to the authenticated user's current team. Also use this tool whenever the user mentions 'DPP', 'Digital Product Passports', 'digital twins', or wants to search their whatt.io catalog.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                page: { type: "number", description: "The page number to retrieve" },
+                per_page: { type: "number", description: "Number of items per page" }
+            }
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.get('/api/v2/product', { params: args });
+            return response.data;
+        }
+    },
+    {
+        name: "v2_create_product",
+        description: "Create a new product",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string" },
+                product_number: { type: "string" },
+                description: { type: "string" },
+                gtin_number: { type: "string" },
+                category_id: { type: "number" },
+                ai_description: { type: "string" },
+                buy_link: { type: "string" },
+                video_url: { type: "string" },
+                primaryMaterial: { type: "number" },
+                secondaryMaterial: { type: "number" },
+                public: { type: "boolean" }
+            },
+            required: ["name", "product_number", "description"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.post('/api/v2/product/create', args);
+            return response.data;
+        }
+    },
+    {
+        name: "v2_show_product",
+        description: "Get detailed information about a specific product",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "Product ID" }
+            },
+            required: ["id"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.get(`/api/v2/product/${args.id}/show`);
+            return response.data;
+        }
+    },
+    {
+        name: "v2_update_product",
+        description: "Update the details of an existing product",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "Product ID" },
+                name: { type: "string" },
+                product_number: { type: "string" },
+                description: { type: "string" },
+                gtin_number: { type: "string" },
+                category_id: { type: "number" },
+                ai_description: { type: "string" },
+                buy_link: { type: "string" },
+                video_url: { type: "string" },
+                primaryMaterial: { type: "number" },
+                secondaryMaterial: { type: "number" },
+                public: { type: "boolean" }
+            },
+            required: ["id"]
+        },
+        handler: async (args, apiClient) => {
+            const { id, ...data } = args;
+            const response = await apiClient.post(`/api/v2/product/${id}/update`, { ...data, _method: 'PUT' });
+            return response.data;
+        }
+    },
+    {
+        name: "v2_delete_product",
+        description: "Delete a product from the system",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "Product ID" }
+            },
+            required: ["id"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.delete(`/api/v2/product/${args.id}/delete`);
+            return response.data;
+        }
+    }
+];

package/build/tools/v2/unit.js

@@ -0,0 +1,86 @@
+export const unitTools = [
+    {
+        name: "v2_list_units",
+        description: "Retrieve a paginated list of all product units",
+        inputSchema: {
+            type: "object",
+            properties: {
+                page: { type: "number", description: "The page number to retrieve" },
+                per_page: { type: "number", description: "Number of items per page" }
+            }
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.get('/api/v2/unit', { params: args });
+            return response.data;
+        }
+    },
+    {
+        name: "v2_create_unit",
+        description: "Create a new product unit",
+        inputSchema: {
+            type: "object",
+            properties: {
+                serial: { type: "string" },
+                product_id: { type: "number" },
+                parts: { type: "string", description: "JSON string of component parts used in this unit" },
+                public: { type: "boolean" }
+            },
+            required: ["serial", "product_id"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.post('/api/v2/unit/create', args);
+            return response.data;
+        }
+    },
+    {
+        name: "v2_show_unit",
+        description: "Get detailed information about a specific unit",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "Unit ID" }
+            },
+            required: ["id"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.get(`/api/v2/unit/${args.id}/show`);
+            return response.data;
+        }
+    },
+    {
+        name: "v2_update_unit",
+        description: "Update the details of an existing product unit instance",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "Unit ID" },
+                serial: { type: "string" },
+                product_id: { type: "number" },
+                parts: { type: "string" },
+                public: { type: "boolean" }
+            },
+            required: ["id"]
+        },
+        handler: async (args, apiClient) => {
+            const { id, ...data } = args;
+            // The openapi explicitly shows PUT for this endpoint for v2
+            const response = await apiClient.put(`/api/v2/unit/${id}/update`, data);
+            return response.data;
+        }
+    },
+    {
+        name: "v2_delete_unit",
+        description: "Permanently delete a unit from the system",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "Unit ID" }
+            },
+            required: ["id"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.delete(`/api/v2/unit/${args.id}/delete`);
+            return response.data;
+        }
+    }
+];

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@whattio/mcp-server",
+  "version": "1.0.0",
+  "description": "The official Model Context Protocol (MCP) server for whatt.io",
+  "main": "build/index.js",
+  "bin": {
+    "whattio-mcp": "build/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js"
+  },
+  "keywords": ["mcp", "whattio", "dpp", "ai", "llm"],
+  "author": "whatt.io",
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "axios": "^1.13.6",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
+  }
+}

package/src/api.ts

@@ -0,0 +1,24 @@
+import axios from 'axios';
+
+// The base URL for whatt.io API. Can be overridden via environment variables.
+const API_BASE_URL = process.env.WHATTIO_API_BASE_URL || 'https://whatt.io';
+
+export const createApiClient = () => {
+  const apiKey = process.env.WHATTIO_API_KEY;
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'Accept': 'application/json',
+  };
+
+  if (apiKey) {
+    headers['Authorization'] = `Bearer ${apiKey}`;
+  }
+
+  const client = axios.create({
+    baseURL: API_BASE_URL,
+    headers,
+  });
+
+  return client;
+};

package/src/index.ts

@@ -0,0 +1,13 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { server } from "./server.js";
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("whatt.io MCP Server running on stdio.");
+}
+
+main().catch((error) => {
+  console.error("Fatal error running server:", error);
+  process.exit(1);
+});

package/src/server.ts

@@ -0,0 +1,165 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError,
+} from '@modelcontextprotocol/sdk/types.js';
+import { createApiClient } from './api.js';
+import { allTools } from './tools/registry.js';
+import axios from 'axios';
+
+// Initialize the API Client natively so it's ready. If the token is missing,
+// endpoints that don't need it will work. Others will fail with 401 as expected.
+const apiClient = createApiClient();
+
+const server = new Server(
+  {
+    name: 'whattio-mcp-server',
+    version: '2.0.0', // We bumped the version to 2.0.0 to signify V2 tool support
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Register all tools from the registry dynamically
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: allTools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+    })),
+  };
+});
+
+// Handle tool execution requests
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const toolName = request.params.name;
+  const targetTool = allTools.find((t) => t.name === toolName);
+
+  if (!targetTool) {
+    throw new McpError(ErrorCode.MethodNotFound, `Tool not found: ${toolName}`);
+  }
+
+  try {
+    const args = request.params.arguments || {};
+    let result = await targetTool.handler(args, apiClient);
+    
+    if (result && result._isNativeMedia) {
+      return {
+        content: [
+          {
+            type: result.type,
+            data: result.data,
+            mimeType: result.mimeType
+          }
+        ]
+      };
+    }
+
+    // Recursively normalize relative URLs or raw filenames so Claude's Artifact UIs don't get broken <img> paths
+    const cdnBase = 'https://whattio-files.fra1.digitaloceanspaces.com';
+    
+    // Helper to format a string into a fully qualified DO Spaces URL
+    const tryToFormatUrl = (val: string, keyName: string = ''): string => {
+      if (!val) return val;
+      if (val.startsWith('http')) return val; // already absolute
+      
+      const isLogo = keyName.toLowerCase().includes('logo');
+      const folder = isLogo ? 'team_images' : 'product_photos';
+      
+      let cleanVal = val;
+      if (cleanVal.startsWith('/storage/')) cleanVal = cleanVal.replace('/storage/', '');
+      else if (cleanVal.startsWith('storage/')) cleanVal = cleanVal.replace('storage/', '');
+      else if (cleanVal.startsWith('/')) cleanVal = cleanVal.slice(1);
+
+      return `${cdnBase}/${folder}/${cleanVal}`;
+    };
+
+    const normalizeUrls = (obj: any, parentKey: string = ''): any => {
+      if (typeof obj === 'string') {
+        // Broad check: if a loose string looks like an image/document file, format it
+        if (/\.(png|jpe?g|gif|webp|pdf)$/i.test(obj)) {
+           return tryToFormatUrl(obj, parentKey);
+        }
+        return obj;
+      }
+      if (Array.isArray(obj)) {
+        return obj.map(item => normalizeUrls(item, parentKey));
+      }
+      if (obj !== null && typeof obj === 'object') {
+        const newObj: any = {};
+        for (const key in obj) {
+          let val = obj[key];
+          
+          if (['logo', 'image', 'video', 'video_url', 'pdf', 'document'].includes(key.toLowerCase())) {
+            if (typeof val === 'string') {
+               newObj[key] = tryToFormatUrl(val, key);
+               continue;
+            }
+          }
+          // The API returns 'images' as an array of strings. Handling that case explicitly:
+          if (key.toLowerCase() === 'images' && Array.isArray(val)) {
+             newObj[key] = val.map(item => (typeof item === 'string' ? tryToFormatUrl(item, key) : normalizeUrls(item, key)));
+             continue;
+          }
+
+          newObj[key] = normalizeUrls(val, key);
+        }
+        return newObj;
+      }
+      return obj;
+    };
+
+    result = normalizeUrls(result);
+    
+    const stringifiedResult = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+    
+    const mediaHint = "\n\n🤖 AI FORMATTING HINT: If this data contains images, logos, or PDFs, display them! CRITICAL: Due to strict Content Security Policy (CSP), images WILL BREAK if you try to render them inside a React Artifact. To show product or team images, ALWAYS use standard markdown `![Alt](url)` in the regular chat text OUTSIDE and BEFORE you create any React Artifacts. Do not put `<img src>` tags in React code. ALSO: When you present a direct external link to a Digital Product Passport (DPP), do not constrain your React UI. Instead, provide a React component with a 'Launch DPP' button that executes `window.open(url, '_blank', 'width=450,height=850')` so the external whatt.io site opens in a mobile-proportioned popup window.";
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: stringifiedResult + mediaHint,
+        },
+      ],
+    };
+  } catch (error: any) {
+    if (axios.isAxiosError(error)) {
+      const statusCode = error.response?.status || 500;
+      const responseData = error.response?.data ? JSON.stringify(error.response.data) : error.message;
+
+      let extraHint = "";
+      if (statusCode === 404 || statusCode === 403) {
+        extraHint = "\n\n🤖 AI HINT: You received a 404/403 error. This usually happens because the item belongs to a different Team context on whatt.io. You MUST use the `v2_switch_team` or `v1_switch_team` tool to change the Active Team, and then retry your request.";
+      }
+
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: `Whatt.io API Error (${statusCode}): ${responseData}${extraHint}`,
+          },
+        ],
+      };
+    }
+
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: `Unexpected Error: ${error.message || String(error)}`,
+        },
+      ],
+    };
+  }
+});
+
+export { server };

package/src/tools/media.ts

@@ -0,0 +1,36 @@
+import { McpTool } from './types.js';
+import axios from 'axios';
+
+export const mediaTools: McpTool[] = [
+  {
+    name: "fetch_media",
+    description: "Fetch an image from a whatt.io URL (or any URL) and render it directly in the chat. Use this whenever the user wants to visually see a product image, logo, or diagram from the JSON data you retrieved. Pass the absolute URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "The absolute URL of the image to fetch" }
+      },
+      required: ["url"]
+    },
+    handler: async (args, apiClient) => {
+      // We don't necessarily use the apiClient since the URL could be absolute to S3 or elsewhere,
+      // but we will use axios natively to fetch the arraybuffer.
+      try {
+        const response = await axios.get(args.url, { responseType: 'arraybuffer' });
+        
+        const mimeType = response.headers['content-type'] || 'image/jpeg';
+        const base64Data = Buffer.from(response.data, 'binary').toString('base64');
+        
+        // Return in native MCP image format so Claude renders it immediately without a privacy button
+        return {
+          _isNativeMedia: true,
+          type: 'image',
+          data: base64Data,
+          mimeType: mimeType
+        };
+      } catch (error: any) {
+        throw new Error(`Failed to fetch media from ${args.url}: ${error.message}`);
+      }
+    }
+  }
+];

package/src/tools/registry.ts

@@ -0,0 +1,10 @@
+import { v1Tools } from './v1/index.js';
+import { v2Tools } from './v2/index.js';
+import { mediaTools } from './media.js';
+import { McpTool } from './types.js';
+
+export const allTools: McpTool[] = [
+  ...v1Tools,
+  ...v2Tools,
+  ...mediaTools
+];

package/src/tools/types.ts

@@ -0,0 +1,12 @@
+import { AxiosInstance } from 'axios';
+
+export interface McpTool {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: "object";
+    properties: Record<string, any>;
+    required?: string[];
+  };
+  handler: (args: any, apiClient: AxiosInstance) => Promise<any>;
+}

package/src/tools/v1/category.ts

@@ -0,0 +1,67 @@
+import { McpTool } from '../types.js';
+
+export const categoryTools: McpTool[] = [
+  {
+    name: "v1_list_categories",
+    description: "Show all categories within a team",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    },
+    handler: async (_args, apiClient) => {
+      const response = await apiClient.get('/api/categories');
+      return response.data;
+    }
+  },
+  {
+    name: "v1_create_category",
+    description: "Add a new category",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        country: { type: "string" },
+        city: { type: "string" },
+        email: { type: "string" },
+        phone: { type: "string" },
+        website: { type: "string" },
+        ai_description: { type: "string" }
+      },
+      required: ["name", "country", "city", "email"]
+    },
+    handler: async (args, apiClient) => {
+      const response = await apiClient.post('/api/category', null, { params: args });
+      return response.data;
+    }
+  },
+  {
+    name: "v1_get_category",
+    description: "Get information about a specific category",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "number" }
+      },
+      required: ["id"]
+    },
+    handler: async (args, apiClient) => {
+      const response = await apiClient.get(`/api/category/${args.id}`);
+      return response.data;
+    }
+  },
+  {
+    name: "v1_delete_category",
+    description: "Delete a specific category",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "number" }
+      },
+      required: ["id"]
+    },
+    handler: async (args, apiClient) => {
+      const response = await apiClient.delete(`/api/category/${args.id}`);
+      return response.data;
+    }
+  }
+];

package/src/tools/v1/incendo.ts

@@ -0,0 +1,68 @@
+import { McpTool } from '../types.js';
+
+export const incendoTools: McpTool[] = [
+  {
+    name: "v1_incendo_ping",
+    description: "Check Incendo connectivity",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    },
+    handler: async (_args, apiClient) => {
+      const response = await apiClient.get('/api/incendo/ping');
+      return response.data;
+    }
+  },
+  {
+    name: "v1_incendo_setup",
+    description: "Setup Incendo integration",
+    inputSchema: {
+      type: "object",
+      properties: {
+        printer_id: { type: "string" },
+        status: { type: "number" }
+      },
+      required: ["printer_id"]
+    },
+    handler: async (args, apiClient) => {
+      const response = await apiClient.post('/api/incendo/setup', null, { params: args });
+      return response.data;
+    }
+  },
+  {
+    name: "v1_incendo_write",
+    description: "Write data to Incendo",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "number" },
+        serial: { type: "string" },
+        url: { type: "string" },
+        data: { type: "string" },
+        token: { type: "string" },
+        password: { type: "string" }
+      },
+      required: ["id", "serial", "url", "data", "token", "password"]
+    },
+    handler: async (args, apiClient) => {
+      const response = await apiClient.post('/api/incendo', null, { params: args });
+      return response.data;
+    }
+  },
+  {
+    name: "v1_incendo_read",
+    description: "Read data from Incendo using serial and token",
+    inputSchema: {
+      type: "object",
+      properties: {
+        serial: { type: "string" },
+        token: { type: "string" }
+      },
+      required: ["serial", "token"]
+    },
+    handler: async (args, apiClient) => {
+      const response = await apiClient.get(`/api/incendo/read/${args.serial}/${args.token}`);
+      return response.data;
+    }
+  }
+];

package/src/tools/v1/index.ts

@@ -0,0 +1,18 @@
+import { userTools } from './user.js';
+import { categoryTools } from './category.js';
+import { materialTools } from './material.js';
+import { productTools } from './product.js';
+import { unitTools } from './unit.js';
+import { incendoTools } from './incendo.js';
+import { simplyprintTools } from './simplyprint.js';
+import { McpTool } from '../types.js';
+
+export const v1Tools: McpTool[] = [
+  ...userTools,
+  ...categoryTools,
+  ...materialTools,
+  ...productTools,
+  ...unitTools,
+  ...incendoTools,
+  ...simplyprintTools
+];