@allourthings/mcp-server 0.2.0 → 0.4.0

package/README.md

@@ -6,7 +6,7 @@ An [MCP server](https://modelcontextprotocol.io) that gives your AI assistant na
 
 ## Requirements
 
-**Desktop only** — macOS, Windows, or Linux with [Claude Desktop](https://claude.ai/download) or another MCP-compatible client. The MCP server runs as a local process; mobile AI assistant access is not currently supported. An iOS app for add/browse on mobile is in development.
+**Desktop only** — macOS, Windows, or Linux with [Claude Desktop](https://claude.ai/download) or another MCP-compatible client. The MCP server runs as a local process.
 
 ## Setup
 
@@ -45,6 +45,8 @@ Once connected, ask your AI assistant things like:
 - *"What's in the kitchen?"*
 - *"When does my TV warranty expire?"*
 - *"Search for anything Samsung"*
+- *"Find and attach the manual for my Dyson V15"*
+- *"Attach this receipt to my MacBook"*
 
 ## Tools
 
@@ -56,6 +58,10 @@ Once connected, ask your AI assistant things like:
 | `update_item` | Update fields on an existing item |
 | `delete_item` | Delete an item by ID |
 | `search_items` | Full-text search across all item fields |
+| `add_attachment` | Attach a file (manual, receipt, photo, warranty) to an item |
+| `attach_from_url` | Download a file from a URL and attach it to an item |
+| `get_attachment` | Retrieve an attachment's contents |
+| `delete_attachment` | Remove an attachment from an item |
 
 ## Vault structure
 

package/dist/index.js

@@ -11168,6 +11168,24 @@ class NativeBackend {
   async searchItems(query) {
     return this.store.searchItems(query);
   }
+  async addAttachment(itemId, filename, kind, data, label) {
+    const result = this.store.addAttachment(itemId, filename, kind, data, label ?? null);
+    if (result instanceof Error)
+      throw result;
+    return result;
+  }
+  async getAttachment(itemId, filename) {
+    const result = this.store.getAttachment(itemId, filename);
+    if (result instanceof Error)
+      throw result;
+    return result;
+  }
+  async deleteAttachment(itemId, filename) {
+    const result = this.store.deleteAttachment(itemId, filename);
+    if (result instanceof Error)
+      throw result;
+    return result;
+  }
 }
 
 // ../../node_modules/zod/v3/external.js
@@ -17791,20 +17809,19 @@ class Server extends Protocol {
 // src/tools/add-item.ts
 var addItemInputSchema = exports_external.object({
   name: exports_external.string().describe("Name of the item"),
-  category: exports_external.string().optional().describe("Category (e.g. appliance, furniture, subscription)"),
-  brand: exports_external.string().optional(),
-  model: exports_external.string().optional(),
-  purchase_date: exports_external.string().optional().describe("ISO date string"),
-  purchase_price: exports_external.number().optional(),
-  currency: exports_external.string().optional().describe("e.g. USD, GBP"),
-  warranty_expires: exports_external.string().optional().describe("ISO date string"),
-  retailer: exports_external.string().optional(),
-  location: exports_external.string().optional().describe("Where the item is kept"),
-  features: exports_external.array(exports_external.string()).optional(),
-  notes: exports_external.string().optional(),
-  tags: exports_external.array(exports_external.string()).optional(),
-  manual_ref: exports_external.string().optional().describe("URL or filename of the manual"),
-  images: exports_external.array(exports_external.string()).optional().describe("Image file paths or URLs")
+  category: exports_external.string().optional().describe("Category (e.g. appliance, electronics, furniture, subscription)"),
+  brand: exports_external.string().optional().describe("Manufacturer or brand name"),
+  model: exports_external.string().optional().describe("Model name or number"),
+  purchase_date: exports_external.string().optional().describe("Date of purchase (ISO date, e.g. 2024-01-15)"),
+  purchase_price: exports_external.number().optional().describe("Price paid for the item"),
+  currency: exports_external.string().optional().describe("Currency code (e.g. GBP, USD, EUR)"),
+  warranty_expires: exports_external.string().optional().describe("Warranty expiry date (ISO date, e.g. 2026-01-15)"),
+  retailer: exports_external.string().optional().describe("Where the item was purchased"),
+  location: exports_external.string().optional().describe("Where the item is kept (e.g. kitchen, garage, office)"),
+  features: exports_external.array(exports_external.string()).optional().describe("Key features or specifications"),
+  notes: exports_external.string().optional().describe("Any additional notes about the item"),
+  tags: exports_external.array(exports_external.string()).optional().describe("Tags for grouping or searching (e.g. ['white goods', 'laundry'])"),
+  serial_number: exports_external.string().optional().describe("Serial number of the item")
 }).passthrough();
 async function addItem(backend, input) {
   const item = await backend.addItem(input);
@@ -17820,7 +17837,7 @@ async function addItem(backend, input) {
 
 // src/tools/get-item.ts
 var getItemInputSchema = exports_external.object({
-  id_or_name: exports_external.string().describe("Item ID or name (fuzzy match)")
+  id_or_name: exports_external.string().describe("Item ID or name. Tries exact ID match first, then exact name match, then substring match.")
 });
 async function getItem(backend, input) {
   const item = await backend.getItem(input.id_or_name);
@@ -17860,8 +17877,8 @@ ${summary}` }]
 
 // src/tools/update-item.ts
 var updateItemInputSchema = exports_external.object({
-  id: exports_external.string().regex(/^[0-9a-f]{8}$/).describe("Item ID to update"),
-  updates: exports_external.record(exports_external.unknown()).describe("Fields to update")
+  id: exports_external.string().regex(/^[0-9a-f]{8}$/).describe("Item ID to update (8-character hex, from the id field on the item)"),
+  updates: exports_external.record(exports_external.unknown()).describe("Fields to update. Any item field can be updated: name, category, brand, model, purchase_date, purchase_price, currency, warranty_expires, retailer, location, features, notes, tags, serial_number. Custom fields are also accepted.")
 });
 async function updateItem(backend, input) {
   const item = await backend.updateItem(input.id, input.updates);
@@ -17871,7 +17888,7 @@ async function updateItem(backend, input) {
     };
   }
   return {
-    content: [{ type: "text", text: `Updated: ${item.name}` }]
+    content: [{ type: "text", text: JSON.stringify(item, null, 2) }]
   };
 }
 
@@ -17913,6 +17930,118 @@ ${summary}` }]
   };
 }
 
+// src/tools/add-attachment.ts
+var addAttachmentInputSchema = exports_external.object({
+  item_id: exports_external.string().describe("ID of the item to attach the file to"),
+  filename: exports_external.string().describe("Filename to store the attachment as (e.g. manual.pdf)"),
+  kind: exports_external.enum(["manual", "receipt", "photo", "warranty", "other"]).describe("Type of attachment"),
+  data_base64: exports_external.string().describe("Base64-encoded file contents"),
+  label: exports_external.string().optional().describe("Human-readable label (e.g. 'Washing machine manual')")
+});
+async function addAttachment(backend, input) {
+  const data = Buffer.from(input.data_base64, "base64");
+  const item = await backend.addAttachment(input.item_id, input.filename, input.kind, data, input.label);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(item, null, 2)
+      }
+    ]
+  };
+}
+
+// src/tools/get-attachment.ts
+var getAttachmentInputSchema = exports_external.object({
+  item_id: exports_external.string().describe("ID of the item"),
+  filename: exports_external.string().describe("Filename of the attachment to retrieve")
+});
+async function getAttachment(backend, input) {
+  const data = await backend.getAttachment(input.item_id, input.filename);
+  return {
+    content: [
+      {
+        type: "text",
+        text: data.toString("base64")
+      }
+    ]
+  };
+}
+
+// src/tools/delete-attachment.ts
+var deleteAttachmentInputSchema = exports_external.object({
+  item_id: exports_external.string().describe("ID of the item"),
+  filename: exports_external.string().describe("Filename of the attachment to delete")
+});
+async function deleteAttachment(backend, input) {
+  const item = await backend.deleteAttachment(input.item_id, input.filename);
+  return {
+    content: [
+      {
+        type: "text",
+        text: item ? JSON.stringify(item, null, 2) : "Attachment deleted (item not found)"
+      }
+    ]
+  };
+}
+
+// src/tools/attach-from-url.ts
+import { basename } from "path";
+var TIMEOUT_MS = 30000;
+var MAX_BYTES = 50 * 1024 * 1024;
+var attachFromUrlInputSchema = exports_external.object({
+  item_id: exports_external.string().describe("ID of the item to attach the file to"),
+  url: exports_external.string().url().describe("URL of the file to download and attach"),
+  kind: exports_external.enum(["manual", "receipt", "photo", "warranty", "other"]).describe("Type of attachment"),
+  filename: exports_external.string().optional().describe("Filename to store the attachment as — inferred from URL if omitted"),
+  label: exports_external.string().optional().describe("Human-readable label (e.g. 'User Manual')")
+});
+function errorResult(message) {
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true
+  };
+}
+async function attachFromUrl(backend, input) {
+  const abort = new AbortController;
+  const timer = setTimeout(() => abort.abort(), TIMEOUT_MS);
+  let response;
+  try {
+    response = await fetch(input.url, { signal: abort.signal });
+  } catch (err) {
+    clearTimeout(timer);
+    const isTimeout = err instanceof Error && err.name === "AbortError";
+    return errorResult(isTimeout ? `Download timed out after ${TIMEOUT_MS / 1000}s. The server may be blocking automated requests or the file is too slow to respond. Try a different direct download URL.` : `Network error fetching URL: ${err instanceof Error ? err.message : String(err)}. Check the URL is correct and publicly accessible.`);
+  }
+  clearTimeout(timer);
+  if (!response.ok) {
+    const hint = response.status === 403 || response.status === 401 ? " The server is blocking automated downloads. Try finding a direct PDF link from a different source." : response.status === 404 ? " The file was not found at this URL. It may have moved — try searching for an updated link." : "";
+    return errorResult(`Download failed: HTTP ${response.status} ${response.statusText}.${hint}`);
+  }
+  const contentType = response.headers.get("content-type") ?? "";
+  const contentLength = Number(response.headers.get("content-length") ?? 0);
+  if (contentLength > MAX_BYTES) {
+    return errorResult(`File is too large to attach (${Math.round(contentLength / 1024 / 1024)} MB — limit is ${MAX_BYTES / 1024 / 1024} MB). Try finding a compressed or alternative version.`);
+  }
+  if (contentType.startsWith("text/html")) {
+    return errorResult("The URL returned an HTML page rather than a file. This is likely a product page or login wall, not a direct download link. Try right-clicking the download button on the page and copying the direct PDF link.");
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  if (buffer.byteLength > MAX_BYTES) {
+    return errorResult(`File is too large to attach (${Math.round(buffer.byteLength / 1024 / 1024)} MB — limit is ${MAX_BYTES / 1024 / 1024} MB).`);
+  }
+  const filename = input.filename ?? (basename(new URL(input.url).pathname) || "attachment");
+  const item = await backend.addAttachment(input.item_id, filename, input.kind, buffer, input.label);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(item, null, 2)
+      }
+    ]
+  };
+}
+
 // src/server.ts
 function createServer(backend) {
   const server = new Server({ name: "allourthings", version: "0.1.0" }, { capabilities: { tools: {} } });
@@ -17947,6 +18076,26 @@ function createServer(backend) {
         name: "search_items",
         description: "Full-text search across all item fields",
         inputSchema: zodToJsonSchema(searchItemsInputSchema)
+      },
+      {
+        name: "add_attachment",
+        description: "Attach a file (manual, receipt, photo, warranty, etc.) to an item. File contents must be base64-encoded.",
+        inputSchema: zodToJsonSchema(addAttachmentInputSchema)
+      },
+      {
+        name: "get_attachment",
+        description: "Retrieve an attachment's contents as a base64-encoded string. Useful for checking an attachment exists. Note: binary files like PDFs cannot be read or displayed directly.",
+        inputSchema: zodToJsonSchema(getAttachmentInputSchema)
+      },
+      {
+        name: "delete_attachment",
+        description: "Delete an attachment from an item",
+        inputSchema: zodToJsonSchema(deleteAttachmentInputSchema)
+      },
+      {
+        name: "attach_from_url",
+        description: "Download a file from a URL and attach it to an item (e.g. a PDF manual or warranty document)",
+        inputSchema: zodToJsonSchema(attachFromUrlInputSchema)
       }
     ]
   }));
@@ -17965,6 +18114,14 @@ function createServer(backend) {
         return deleteItem(backend, deleteItemInputSchema.parse(args));
       case "search_items":
         return searchItems(backend, searchItemsInputSchema.parse(args));
+      case "add_attachment":
+        return addAttachment(backend, addAttachmentInputSchema.parse(args));
+      case "get_attachment":
+        return getAttachment(backend, getAttachmentInputSchema.parse(args));
+      case "delete_attachment":
+        return deleteAttachment(backend, deleteAttachmentInputSchema.parse(args));
+      case "attach_from_url":
+        return attachFromUrl(backend, attachFromUrlInputSchema.parse(args));
       default:
         throw new Error(`Unknown tool: ${name}`);
     }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@allourthings/mcp-server",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "mcpName": "io.allourthings/mcp-server",
-  "description": "MCP server for All Our Things — AI-powered household inventory",
+  "description": "AllOurThings — Your things, understood by AI.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@allourthings/core": "^0.1.0",
+    "@allourthings/core": "^0.1.10",
     "zod": "^3.24.0",
     "zod-to-json-schema": "^3.25.1"
   },