estatehelm 1.0.7 → 1.0.8

package/README.md

@@ -24,19 +24,27 @@ This will:
 
 ### 2. Configure Claude Code
 
-Add to your `~/.claude.json` (or Claude Code settings):
-
-```json
-{
-  "mcpServers": {
-    "estatehelm": {
-      "command": "estatehelm",
-      "args": ["mcp"]
-    }
-  }
-}
+**Windows:**
+```bash
+claude mcp add --transport stdio estatehelm -- cmd /c npx estatehelm mcp
+```
+
+**Mac/Linux:**
+```bash
+claude mcp add --transport stdio estatehelm -- npx estatehelm mcp
+```
+
+**For staging environment:**
+```bash
+# Windows
+claude mcp add --transport stdio estatehelm-staging -- cmd /c npx estatehelm mcp --staging
+
+# Mac/Linux
+claude mcp add --transport stdio estatehelm-staging -- npx estatehelm mcp --staging
 ```
 
+Verify with `claude mcp list`.
+
 ### 3. Use with Claude Code
 
 Start Claude Code and you can now ask questions like:
@@ -122,20 +130,40 @@ The server exposes your EstateHelm data as MCP resources:
 
 - `estatehelm://households` - List all households
 - `estatehelm://households/{id}` - Specific household
-- `estatehelm://households/{id}/pets` - Pets in household
-- `estatehelm://households/{id}/properties` - Properties
-- `estatehelm://households/{id}/vehicles` - Vehicles
-- `estatehelm://households/{id}/contacts` - Contacts
-- `estatehelm://households/{id}/insurance` - Insurance policies
-- `estatehelm://households/{id}/bank_account` - Bank accounts
-- And more...
+- `estatehelm://households/{id}/{entityType}` - Entities by type
+
+**Supported entity types:**
+`pet`, `property`, `vehicle`, `contact`, `insurance`, `bank_account`, `investment`, `subscription`, `maintenance_task`, `password`, `access_code`, `document`, `medical`, `prescription`, `credential`, `utility`
 
 ## MCP Tools
 
-- `search_entities` - Full-text search across entities
-- `get_household_summary` - Overview with counts
-- `get_expiring_items` - Items expiring soon
-- `refresh` - Force re-sync from server
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `search_entities` | Full-text search across entities | `query` (required), `householdId`, `entityType` |
+| `get_household_summary` | Overview with entity counts | `householdId` (required) |
+| `get_expiring_items` | Items expiring within N days | `days` (default: 30), `householdId` |
+| `get_file` | Download and decrypt a file attachment | `fileId`, `householdId`, `entityId`, `entityType` (all required) |
+| `refresh` | Force re-sync from server | none |
+
+**`get_expiring_items` checks:**
+- Insurance policies (`expiration_date`)
+- Vehicle registrations (`registration_expiration`)
+- Vehicle tabs (`tabs_expiration`)
+- Subscriptions (`expiration_date`)
+
+**`get_file` returns:**
+- `fileName`: Original filename
+- `mimeType`: File MIME type
+- `size`: File size in bytes
+- `data`: Base64-encoded decrypted file content
+
+## MCP Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `household_summary` | "Give me an overview of my household" |
+| `expiring_soon` | "What's expiring in the next 30 days?" |
+| `emergency_contacts` | "Show me emergency contacts" |
 
 ## Security
 

package/dist/index.js

@@ -1297,10 +1297,40 @@ async function unwrapHouseholdKey(wrappedKey, privateKey, algorithm = DEFAULT_KE
 // ../encryption/src/webauthnDeviceBound.ts
 var RP_ID = typeof window !== "undefined" ? window.location.hostname : "estatehelm.com";
 
+// ../encryption/src/fileEncryption.ts
+var FILE_IV_SIZE = 12;
+async function decryptFileFromArrayBuffer(householdKey, entityId, entityType, encryptedArrayBuffer, mimeType) {
+  const packed = new Uint8Array(encryptedArrayBuffer);
+  if (packed.length < FILE_IV_SIZE + 16) {
+    throw new Error("Encrypted data too short");
+  }
+  const entityKeyBytes = await deriveEntityKey(householdKey, entityId, entityType);
+  const entityKey = await importEntityKey(entityKeyBytes);
+  const iv = packed.slice(0, FILE_IV_SIZE);
+  const ciphertext = packed.slice(FILE_IV_SIZE);
+  try {
+    const plaintext = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv },
+      entityKey,
+      ciphertext
+    );
+    return {
+      bytes: new Uint8Array(plaintext),
+      mimeType
+    };
+  } catch (error) {
+    if (error instanceof Error && error.name === "OperationError") {
+      throw new Error("Failed to decrypt file: Authentication failed");
+    }
+    throw error;
+  }
+}
+
 // src/config.ts
 var import_env_paths = __toESM(require("env-paths"));
 var path = __toESM(require("path"));
 var fs = __toESM(require("fs"));
+var os = __toESM(require("os"));
 var paths = (0, import_env_paths.default)("estatehelm", { suffix: "" });
 var DATA_DIR = paths.data;
 var CACHE_DB_PATH = path.join(DATA_DIR, "cache.db");
@@ -1367,19 +1397,25 @@ function getDeviceId() {
 }
 function getDevicePlatform() {
   const platform = process.platform;
+  const hostname2 = os.hostname();
+  let osName;
   switch (platform) {
     case "darwin":
-      return "macOS";
+      osName = "macOS";
+      break;
     case "win32":
-      return "Windows";
+      osName = "Windows";
+      break;
     case "linux":
-      return "Linux";
+      osName = "Linux";
+      break;
     default:
-      return platform;
+      osName = platform;
   }
+  return `mcp-${osName}-${hostname2}`;
 }
 function getDeviceUserAgent() {
-  return `estatehelm-mcp/1.0 (${getDevicePlatform()})`;
+  return `estatehelm-mcp/1.0 (${os.hostname()}, ${process.platform})`;
 }
 function sanitizeToken(token) {
   if (token.length <= 8) return "***";
@@ -1628,18 +1664,15 @@ ${loginUrl}
     privateKeyBytes: base64Encode(privateKeyBytes)
   });
   console.log("\n\u2713 Login complete!");
-  console.log("\nTo use with Claude Code, add to your MCP settings:");
+  console.log("\nTo use with Claude Code, run:");
   console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
-  console.log(JSON.stringify({
-    mcpServers: {
-      estatehelm: {
-        command: "npx",
-        args: ["estatehelm", "mcp"]
-      }
-    }
-  }, null, 2));
+  if (process.platform === "win32") {
+    console.log("  claude mcp add --transport stdio estatehelm -- cmd /c npx estatehelm mcp");
+  } else {
+    console.log("  claude mcp add --transport stdio estatehelm -- npx estatehelm mcp");
+  }
   console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
-  console.log("\nOr run manually: estatehelm mcp");
+  console.log("\nOr run manually: npx estatehelm mcp");
 }
 async function checkLogin() {
   const credentials = await getCredentials();
@@ -2417,6 +2450,40 @@ async function getCacheStats() {
   const cache = getCache();
   return cache.getCacheStats();
 }
+async function downloadAndDecryptFile(client, householdId, fileId, entityId, entityType) {
+  const keyType = getKeyTypeForEntity(entityType);
+  const householdKeyBytes = householdKeysCache.get(`${householdId}:${keyType}`);
+  if (!householdKeyBytes) {
+    throw new Error(`No key available for ${householdId}:${keyType}`);
+  }
+  const fileInfo = await client.get(
+    `/households/${householdId}/files/${fileId}`
+  );
+  if (!fileInfo.downloadUrl) {
+    throw new Error("No download URL returned for file");
+  }
+  const response = await fetch(fileInfo.downloadUrl);
+  if (!response.ok) {
+    throw new Error(`Failed to download file: ${response.status}`);
+  }
+  const encryptedBytes = await response.arrayBuffer();
+  const cryptoVersion = fileInfo.cryptoVersion ?? 1;
+  const keyDerivationId = cryptoVersion === 2 ? fileId : fileInfo.entityId || entityId;
+  const mimeType = fileInfo.fileType || "application/octet-stream";
+  const decrypted = await decryptFileFromArrayBuffer(
+    householdKeyBytes,
+    keyDerivationId,
+    entityType,
+    encryptedBytes,
+    mimeType
+  );
+  return {
+    data: decrypted.data,
+    dataBase64: base64Encode(decrypted.data),
+    mimeType: decrypted.mimeType,
+    fileName: fileInfo.fileName
+  };
+}
 
 // src/server.ts
 async function startServer(mode) {
@@ -2594,6 +2661,32 @@ async function startServer(mode) {
             type: "object",
             properties: {}
           }
+        },
+        {
+          name: "get_file",
+          description: "Download and decrypt a file attachment. Returns base64-encoded file data that can be saved to disk.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              fileId: {
+                type: "string",
+                description: "The file ID to download"
+              },
+              householdId: {
+                type: "string",
+                description: "The household ID the file belongs to"
+              },
+              entityId: {
+                type: "string",
+                description: "The entity ID the file is attached to"
+              },
+              entityType: {
+                type: "string",
+                description: "The entity type (e.g., insurance, document)"
+              }
+            },
+            required: ["fileId", "householdId", "entityId", "entityType"]
+          }
         }
       ]
     };
@@ -2694,15 +2787,15 @@ async function startServer(mode) {
         for (const household of searchHouseholds) {
           const insurance = await getDecryptedEntities(household.id, "insurance", privateKey);
           for (const policy of insurance) {
-            if (policy.expirationDate) {
-              const expires = new Date(policy.expirationDate);
+            if (policy.expiration_date) {
+              const expires = new Date(policy.expiration_date);
               if (expires <= cutoff) {
                 expiring.push({
                   householdId: household.id,
                   householdName: household.name,
                   type: "insurance",
-                  name: policy.name || policy.policyNumber,
-                  expiresAt: policy.expirationDate,
+                  name: policy.name || policy.policy_number,
+                  expiresAt: policy.expiration_date,
                   daysUntil: Math.ceil((expires.getTime() - now.getTime()) / (24 * 60 * 60 * 1e3))
                 });
               }
@@ -2710,15 +2803,29 @@ async function startServer(mode) {
           }
           const vehicles = await getDecryptedEntities(household.id, "vehicle", privateKey);
           for (const vehicle of vehicles) {
-            if (vehicle.registrationExpiration) {
-              const expires = new Date(vehicle.registrationExpiration);
+            const vehicleName = `${vehicle.year || ""} ${vehicle.make || ""} ${vehicle.model || ""}`.trim();
+            if (vehicle.registration_expiration) {
+              const expires = new Date(vehicle.registration_expiration);
               if (expires <= cutoff) {
                 expiring.push({
                   householdId: household.id,
                   householdName: household.name,
                   type: "vehicle_registration",
-                  name: `${vehicle.year || ""} ${vehicle.make || ""} ${vehicle.model || ""}`.trim(),
-                  expiresAt: vehicle.registrationExpiration,
+                  name: vehicleName,
+                  expiresAt: vehicle.registration_expiration,
+                  daysUntil: Math.ceil((expires.getTime() - now.getTime()) / (24 * 60 * 60 * 1e3))
+                });
+              }
+            }
+            if (vehicle.tabs_expiration) {
+              const expires = new Date(vehicle.tabs_expiration);
+              if (expires <= cutoff) {
+                expiring.push({
+                  householdId: household.id,
+                  householdName: household.name,
+                  type: "vehicle_tabs",
+                  name: vehicleName,
+                  expiresAt: vehicle.tabs_expiration,
                   daysUntil: Math.ceil((expires.getTime() - now.getTime()) / (24 * 60 * 60 * 1e3))
                 });
               }
@@ -2726,16 +2833,16 @@ async function startServer(mode) {
           }
           const subscriptions = await getDecryptedEntities(household.id, "subscription", privateKey);
           for (const sub of subscriptions) {
-            if (sub.renewalDate) {
-              const renews = new Date(sub.renewalDate);
-              if (renews <= cutoff) {
+            if (sub.expiration_date) {
+              const expires = new Date(sub.expiration_date);
+              if (expires <= cutoff) {
                 expiring.push({
                   householdId: household.id,
                   householdName: household.name,
                   type: "subscription",
-                  name: sub.name || sub.serviceName,
-                  expiresAt: sub.renewalDate,
-                  daysUntil: Math.ceil((renews.getTime() - now.getTime()) / (24 * 60 * 60 * 1e3))
+                  name: sub.name || sub.service_name,
+                  expiresAt: sub.expiration_date,
+                  daysUntil: Math.ceil((expires.getTime() - now.getTime()) / (24 * 60 * 60 * 1e3))
                 });
               }
             }
@@ -2762,6 +2869,44 @@ async function startServer(mode) {
           ]
         };
       }
+      case "get_file": {
+        const { fileId, householdId, entityId, entityType } = args;
+        try {
+          const result = await downloadAndDecryptFile(
+            client,
+            householdId,
+            fileId,
+            entityId,
+            entityType
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  success: true,
+                  fileName: result.fileName,
+                  mimeType: result.mimeType,
+                  size: result.data.length,
+                  data: result.dataBase64
+                }, null, 2)
+              }
+            ]
+          };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  success: false,
+                  error: err.message
+                }, null, 2)
+              }
+            ]
+          };
+        }
+      }
       default:
         throw new Error(`Unknown tool: ${name}`);
     }
@@ -2855,18 +3000,6 @@ async function startServer(mode) {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error("[MCP] Server started");
-  console.error("");
-  console.error("To use with Claude Code, add to ~/.claude/claude_desktop_config.json:");
-  console.error("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
-  console.error(JSON.stringify({
-    mcpServers: {
-      estatehelm: {
-        command: "npx",
-        args: ["estatehelm", "mcp"]
-      }
-    }
-  }, null, 2));
-  console.error("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
 }
 function parseResourceUri(uri) {
   const match = uri.match(/^estatehelm:\/\/([^/]+)(?:\/([^/]+))?(?:\/([^/]+))?(?:\/([^/]+))?$/);