@whattio/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,48 @@
+# whatt.io MCP Server
+
+A Model Context Protocol (MCP) server for integrating Language Models with the whatt.io API.
+
+## Installation
+
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+2. Build the server:
+   ```bash
+   npm run build
+   ```
+
+## Configuration
+
+Set the environment variable `WHATTIO_API_KEY` before running the server or connecting an MCP Client to it.
+
+```bash
+export WHATTIO_API_KEY="your-whatt-io-api-key"
+```
+
+You can also override the base URL (defaults to `https://api.whatt.io/v1`):
+```bash
+export WHATTIO_API_BASE_URL="https://analytics.whattio.com/api"
+```
+
+## Running the Server
+
+Run the server natively via the CLI interface (stdio):
+
+```bash
+npm start
+```
+
+### Using Model Context Protocol Inspector
+
+To debug and test tools interactively:
+
+```bash
+npx @modelcontextprotocol/inspector node build/index.js
+```
+
+## Available Tools
+
+- `get_whattio_data`: Send GET requests to any whatt.io API endpoint. 

package/build/api.js

@@ -0,0 +1,18 @@
+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 = {
+        '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/build/index.js

@@ -0,0 +1,11 @@
+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/build/server.js

@@ -0,0 +1,140 @@
+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, keyName = '') => {
+            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, parentKey = '') => {
+            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 = {};
+                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) {
+        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/build/tools/media.js

@@ -0,0 +1,33 @@
+import axios from 'axios';
+export const mediaTools = [
+    {
+        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) {
+                throw new Error(`Failed to fetch media from ${args.url}: ${error.message}`);
+            }
+        }
+    }
+];

package/build/tools/registry.js

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

package/build/tools/types.js

@@ -0,0 +1 @@
+export {};

package/build/tools/v1/category.js

@@ -0,0 +1,65 @@
+export const categoryTools = [
+    {
+        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/build/tools/v1/incendo.js

@@ -0,0 +1,66 @@
+export const incendoTools = [
+    {
+        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/build/tools/v1/index.js

@@ -0,0 +1,16 @@
+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';
+export const v1Tools = [
+    ...userTools,
+    ...categoryTools,
+    ...materialTools,
+    ...productTools,
+    ...unitTools,
+    ...incendoTools,
+    ...simplyprintTools
+];

package/build/tools/v1/material.js

@@ -0,0 +1,79 @@
+export const materialTools = [
+    {
+        name: "v1_list_materials",
+        description: "Show all materials within a team",
+        inputSchema: {
+            type: "object",
+            properties: {}
+        },
+        handler: async (_args, apiClient) => {
+            const response = await apiClient.get('/api/materials');
+            return response.data;
+        }
+    },
+    {
+        name: "v1_create_material",
+        description: "Add a new material",
+        inputSchema: {
+            type: "object",
+            properties: {
+                brand: { type: "string" },
+                name: { type: "string" },
+                code: { type: "string" },
+                color_code: { type: "number" },
+                data_sheet: { type: "string" },
+                safety_sheet: { type: "string" },
+                origin_type: { type: "string" },
+                origin_country: { type: "string" },
+                waste_category: { type: "string" },
+                resin_id: { type: "string" },
+                chem_name: { type: "string" },
+                recycled: { type: "boolean" },
+                bioderived: { type: "boolean" },
+                biodegradable: { type: "string" },
+                biodegrade_comment: { type: "string" },
+                recyclable: { type: "boolean" },
+                recycle_info: { type: "string" },
+                recycle_url: { type: "string" },
+                recycling_img: { type: "string" },
+                bio_derived: { type: "string" },
+                buy_url: { type: "string" }
+            },
+            required: ["brand", "name", "origin_country"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.post('/api/material', null, { params: args });
+            return response.data;
+        }
+    },
+    {
+        name: "v1_get_material",
+        description: "Get information about a specific material",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number" }
+            },
+            required: ["id"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.get(`/api/material/${args.id}`);
+            return response.data;
+        }
+    },
+    {
+        name: "v1_delete_material",
+        description: "Delete a specific material",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number" }
+            },
+            required: ["id"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.delete(`/api/material/${args.id}`);
+            return response.data;
+        }
+    }
+];

package/build/tools/v1/product.js

@@ -0,0 +1,85 @@
+export const productTools = [
+    {
+        name: "v1_list_products",
+        description: "Show all products within a team. Also use this tool whenever the user mentions 'DPP', 'Digital Product Passports', 'digital twins', or wants to search their whatt.io product catalog.",
+        inputSchema: {
+            type: "object",
+            properties: {}
+        },
+        handler: async (_args, apiClient) => {
+            const response = await apiClient.get('/api/products');
+            return response.data;
+        }
+    },
+    {
+        name: "v1_create_product",
+        description: "Add a new product",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string" },
+                product_number: { type: "string" },
+                version: { type: "string" },
+                description: { type: "string" },
+                gtin: { type: "string" },
+                image: { type: "string" },
+                video: { type: "string" },
+                buy_url: { type: "string" },
+                category_id: { type: "number" },
+                ai_description: { type: "string" },
+                type: { type: "string" },
+                public: { type: "number" }
+            },
+            required: ["name", "product_number", "description"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.post('/api/product', null, { params: args });
+            return response.data;
+        }
+    },
+    {
+        name: "v1_get_product",
+        description: "Get information about a specific product",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number" }
+            },
+            required: ["id"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.get(`/api/product/${args.id}`);
+            return response.data;
+        }
+    },
+    {
+        name: "v1_get_ext_product",
+        description: "Get information about a specific product with extended format",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number" }
+            },
+            required: ["id"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.get(`/api/product/ext/${args.id}`);
+            return response.data;
+        }
+    },
+    {
+        name: "v1_delete_product",
+        description: "Delete a specific product",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number" }
+            },
+            required: ["id"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.delete(`/api/product/${args.id}`);
+            return response.data;
+        }
+    }
+];

package/build/tools/v1/simplyprint.js

@@ -0,0 +1,44 @@
+export const simplyprintTools = [
+    {
+        name: "v1_simplyprint_printers",
+        description: "Fetch SimplyPrint printers associated with user",
+        inputSchema: {
+            type: "object",
+            properties: {}
+        },
+        handler: async (_args, apiClient) => {
+            const response = await apiClient.get('/api/simplyprint/printers');
+            return response.data;
+        }
+    },
+    {
+        name: "v1_simplyprint_jobs",
+        description: "Fetch SimplyPrint print jobs for a specific printer",
+        inputSchema: {
+            type: "object",
+            properties: {
+                printer_id: { type: "string", description: "Printer ID" }
+            },
+            required: ["printer_id"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.get(`/api/simplyprint/jobs/${args.printer_id}`);
+            return response.data;
+        }
+    },
+    {
+        name: "v1_simplyprint_filament",
+        description: "Fetch remaining filament info for a specific printer",
+        inputSchema: {
+            type: "object",
+            properties: {
+                printer_id: { type: "string", description: "Printer ID" }
+            },
+            required: ["printer_id"]
+        },
+        handler: async (args, apiClient) => {
+            const response = await apiClient.get(`/api/getFilament/filament/${args.printer_id}`);
+            return response.data;
+        }
+    }
+];