@trustrails/mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TrustRails
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# TrustRails MCP Server
+
+**Search UK electronics products** - compare prices, find deals, and discover products across multiple retailers.
+
+Built for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install -g @trustrails/mcp-server
+```
+
+### Configuration
+
+Add to your Claude Code config (`~/.config/claude/config.json`):
+
+```json
+{
+  "mcpServers": {
+    "trustrails": {
+      "command": "trustrails-mcp",
+      "env": {
+        "TRUSTRAILS_API_KEY": "mcp-public-2026",
+        "TRUSTRAILS_BASE_URL": "https://www.trustrails.app"
+      }
+    }
+  }
+}
+```
+
+**Or** for Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "trustrails": {
+      "command": "trustrails-mcp",
+      "env": {
+        "TRUSTRAILS_API_KEY": "mcp-public-2026"
+      }
+    }
+  }
+}
+```
+
+That's it! Restart Claude and start searching.
+
+---
+
+## What You Can Do
+
+### Natural Language Product Search
+
+```
+"Find me a gaming laptop under £1000"
+"Compare prices for Sony WH-1000XM5 headphones"
+"Show me the cheapest 4K monitors over 27 inches"
+"What HP laptops are in stock right now between £500-£700?"
+```
+
+Claude will search across multiple UK retailers and show you:
+- Real-time prices
+- Stock availability
+- Product specs
+- Purchase links
+
+---
+
+## Available Tools
+
+### `search_products`
+
+Search UK electronics across multiple retailers.
+
+**Parameters:**
+- `query` (string) - Search term (e.g., "laptop", "USB-C charger")
+- `min_price` (number) - Minimum price in GBP (optional)
+- `max_price` (number) - Maximum price in GBP (optional)
+- `brand` (string) - Filter by brand (optional)
+- `category` (string) - Filter by category (optional)
+
+### `get_product`
+
+Get detailed information about a specific product by ID.
+
+**Parameters:**
+- `product_id` (string) - The product ID from search results
+
+---
+
+## Supported Retailers
+
+Search across **26,000+ products** from:
+
+- **AO** - Major UK electronics retailer
+- **Boxed2Me** - Tech and electronics
+- **Instock** - Computing and office equipment
+- **Back to the Office** - Office tech and supplies
+
+*More retailers added regularly*
+
+---
+
+## Rate Limits
+
+- **20 requests per hour** per IP address
+- Rate limit info included in response headers (`X-RateLimit-Remaining`, `X-RateLimit-Reset`)
+- Limits reset every hour
+
+Plenty for normal use - just prevents abuse.
+
+---
+
+## Environment Variables
+
+- `TRUSTRAILS_API_KEY` - API key (use `mcp-public-2026` for shared access)
+- `TRUSTRAILS_BASE_URL` - API endpoint (defaults to `https://www.trustrails.app`)
+
+---
+
+## Example Usage
+
+**Price comparison:**
+```
+"Compare prices for Sony WH-1000XM5 headphones across all retailers"
+```
+
+**Budget shopping:**
+```
+"Find the cheapest gaming laptops with at least 16GB RAM under £800"
+```
+
+**Brand research:**
+```
+"Show me all Apple products between £500 and £1000 currently in stock"
+```
+
+**Stock checking:**
+```
+"Which retailers have the HP Envy x360 in stock right now?"
+```
+
+---
+
+## Why TrustRails?
+
+- ✅ **Real-time data** - Updated daily
+- ✅ **Multiple retailers** - Compare prices in one search
+- ✅ **Stock info** - See what's actually available
+- ✅ **Direct purchase links** - Buy immediately
+- ✅ **Zero setup** - Works out of the box with shared key
+
+---
+
+## Support & Links
+
+- **Website:** https://www.trustrails.app
+- **GitHub:** https://github.com/james-webdev/trustrails
+- **Issues:** https://github.com/james-webdev/trustrails/issues
+- **NPM:** https://www.npmjs.com/package/@trustrails/mcp-server
+
+---
+
+## License
+
+MIT
+
+---
+
+## About MCP
+
+This server implements the [Model Context Protocol](https://modelcontextprotocol.io), allowing Claude to search products directly. Learn more about building MCP servers at [modelcontextprotocol.io](https://modelcontextprotocol.io).

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,181 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+// TrustRails API configuration
+const API_KEY = process.env.TRUSTRAILS_API_KEY || "mcp-public-2026";
+const BASE_URL = process.env.TRUSTRAILS_BASE_URL || "https://www.trustrails.app";
+// Create server instance
+const server = new Server({
+    name: "trustrails",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+/**
+ * Search for products across UK electronics retailers
+ */
+async function searchProducts(params) {
+    const searchParams = new URLSearchParams();
+    if (params.query) {
+        searchParams.append("query", params.query);
+    }
+    if (params.min_price && params.min_price > 0) {
+        searchParams.append("min_price", params.min_price.toString());
+    }
+    if (params.max_price && params.max_price > 0) {
+        searchParams.append("max_price", params.max_price.toString());
+    }
+    if (params.brand) {
+        searchParams.append("brand", params.brand);
+    }
+    if (params.category) {
+        searchParams.append("category", params.category);
+    }
+    const url = `${BASE_URL}/api/search?${searchParams.toString()}`;
+    const response = await fetch(url, {
+        headers: {
+            ...(API_KEY && { "Authorization": `Bearer ${API_KEY}` }),
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Search failed: ${response.statusText}`);
+    }
+    return await response.json();
+}
+/**
+ * Get detailed information about a specific product
+ */
+async function getProduct(productId) {
+    const url = `${BASE_URL}/api/product/${productId}`;
+    const response = await fetch(url, {
+        headers: {
+            ...(API_KEY && { "Authorization": `Bearer ${API_KEY}` }),
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 404) {
+            throw new Error(`Product not found: ${productId}`);
+        }
+        throw new Error(`Failed to get product: ${response.statusText}`);
+    }
+    return await response.json();
+}
+// Handle tool listing
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "search_products",
+                description: "Search for UK electronics products across multiple retailers (AO, Boxed, etc). " +
+                    "Returns product details including prices, availability, specs, and purchase links. " +
+                    "Perfect for price comparison, product research, or building shopping assistants.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "Search query (e.g., 'laptop', 'USB-C charger', 'wireless headphones')",
+                        },
+                        min_price: {
+                            type: "number",
+                            description: "Minimum price filter in GBP (e.g., 100 for products over £100)",
+                        },
+                        max_price: {
+                            type: "number",
+                            description: "Maximum price filter in GBP (e.g., 500 for products under £500)",
+                        },
+                        brand: {
+                            type: "string",
+                            description: "Filter by brand name (e.g., 'Sony', 'Apple', 'HP')",
+                        },
+                        category: {
+                            type: "string",
+                            description: "Filter by product category (e.g., 'Laptops', 'Headphones', 'Monitors')",
+                        },
+                    },
+                },
+            },
+            {
+                name: "get_product",
+                description: "Get detailed information about a specific product by ID. " +
+                    "Returns complete product details including specs, availability, pricing, and retailer information.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        product_id: {
+                            type: "string",
+                            description: "The unique product ID",
+                        },
+                    },
+                    required: ["product_id"],
+                },
+            },
+        ],
+    };
+});
+// Handle tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        const { name, arguments: args } = request.params;
+        switch (name) {
+            case "search_products": {
+                const searchArgs = args;
+                const results = await searchProducts(searchArgs);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(results, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "get_product": {
+                const { product_id } = args;
+                if (!product_id) {
+                    throw new Error("product_id is required");
+                }
+                const product = await getProduct(product_id);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(product, null, 2),
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${errorMessage}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr (stdout is used for MCP protocol)
+    console.error("TrustRails MCP Server running");
+    console.error(`Base URL: ${BASE_URL}`);
+    console.error(`API Key: ${API_KEY ? "configured" : "not configured"}`);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@trustrails/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for searching UK electronics products across multiple retailers",
+  "type": "module",
+  "bin": {
+    "trustrails-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "model-context-protocol",
+    "electronics",
+    "uk",
+    "shopping",
+    "products",
+    "price-comparison",
+    "trustrails"
+  ],
+  "author": "TrustRails",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/james-webdev/trustrails.git",
+    "directory": "packages/mcp-server"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4.20.5",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}