json-object-editor 0.10.624 → 0.10.632

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-object-editor",
-  "version": "0.10.624",
+  "version": "0.10.632",
   "description": "JOE the Json Object Editor | Platform Edition",
   "main": "app.js",
   "scripts": {

package/readme.md

@@ -44,12 +44,12 @@ JOE is software that allows you to manage data models via JSON objects. There ar
 
 - Tools
   - `listSchemas(name?)`, `getSchema(name)`
-  - `getObject(_id, schema?)` (supports optional `flatten` and `depth`)
+  - `getObject(_id, itemtype?)` (supports optional `flatten` and `depth`)
   - `search` (exact): unified tool for cache and storage
-    - Params: `{ schema?, query?, ids?, source?: 'cache'|'storage', limit?, flatten?, depth? }`
-    - Defaults to cache across all collections; add `schema` to filter; set `source:"storage"` to query a specific schema in the DB. Use `fuzzySearch` for typo-tolerant free text.
+    - Params: `{ itemtype?, query?, ids?, source?: 'cache'|'storage', limit?, flatten?, depth? }`
+    - Defaults to cache across all collections; add `itemtype` to filter; set `source:"storage"` to query a specific collection in the DB. Runtime accepts legacy alias `schema` (maps to `itemtype`). Use `fuzzySearch` for typo-tolerant free text.
   - `fuzzySearch` (typo-tolerant free text across weighted fields)
-    - Params: `{ schema?, q, filters?, fields?, threshold?, limit?, offset?, highlight?, minQueryLength? }`
+    - Params: `{ itemtype?, q, filters?, fields?, threshold?, limit?, offset?, highlight?, minQueryLength? }`
     - Defaults: `fields` resolved from schema `searchables` (plural) if present; otherwise weights `name:0.6, info:0.3, description:0.1`. `threshold:0.5`, `limit:50`, `minQueryLength:2`.
     - Returns: `{ items, count }`. Each item may include `_score` (0..1) and `_matches` when `highlight` is true.
   - `saveObject({ object })`
@@ -86,17 +86,17 @@ JOE is software that allows you to manage data models via JSON objects. There ar
     ```
   - fuzzySearch (cache):
     ```powershell
-    $body = @{ jsonrpc="2.0"; id="6"; method="fuzzySearch"; params=@{ schema="<schemaName>"; q="st paal"; threshold=0.35; limit=10 } } | ConvertTo-Json -Depth 10
+    $body = @{ jsonrpc="2.0"; id="6"; method="fuzzySearch"; params=@{ itemtype="<schemaName>"; q="st paal"; threshold=0.35; limit=10 } } | ConvertTo-Json -Depth 10
     Invoke-RestMethod -Method Post -Uri "$base/mcp" -Headers $h -Body $body
     ```
   - search (storage):
     ```powershell
-    $body = @{ jsonrpc="2.0"; id="4"; method="search"; params=@{ schema="<schemaName>"; source="storage"; query=@{ }; limit=10 } } | ConvertTo-Json -Depth 10
+    $body = @{ jsonrpc="2.0"; id="4"; method="search"; params=@{ itemtype="<schemaName>"; source="storage"; query=@{ }; limit=10 } } | ConvertTo-Json -Depth 10
     Invoke-RestMethod -Method Post -Uri "$base/mcp" -Headers $h -Body $body
     ```
   - search (ids + flatten):
     ```powershell
-    $body = @{ jsonrpc="2.0"; id="5"; method="search"; params=@{ schema="<schemaName>"; ids=@("<id1>","<id2>"); flatten=$true; depth=2 } } | ConvertTo-Json -Depth 10
+    $body = @{ jsonrpc="2.0"; id="5"; method="search"; params=@{ itemtype="<schemaName>"; ids=@("<id1>","<id2>"); flatten=$true; depth=2 } } | ConvertTo-Json -Depth 10
     Invoke-RestMethod -Method Post -Uri "$base/mcp" -Headers $h -Body $body
     ```
   - saveObject:
@@ -131,13 +131,13 @@ JOE is software that allows you to manage data models via JSON objects. There ar
     ```bash
     curl -s -X POST http://localhost:<PORT>/mcp \
       -H 'Content-Type: application/json' \
-      -d '{"jsonrpc":"2.0","id":"6","method":"fuzzySearch","params":{"schema":"<schemaName>","q":"st paal","threshold":0.35,"limit":10}}' | jq
+      -d '{"jsonrpc":"2.0","id":"6","method":"fuzzySearch","params":{"itemtype":"<schemaName>","q":"st paal","threshold":0.35,"limit":10}}' | jq
     ```
   - search (storage):
     ```bash
     curl -s -X POST http://localhost:<PORT>/mcp \
       -H 'Content-Type: application/json' \
-      -d '{"jsonrpc":"2.0","id":"4","method":"search","params":{"schema":"<schemaName>","source":"storage","query":{},"limit":10}}' | jq
+      -d '{"jsonrpc":"2.0","id":"4","method":"search","params":{"itemtype":"<schemaName>","source":"storage","query":{},"limit":10}}' | jq
     ```
     ```bash
     curl -s -X POST http://localhost:<PORT>/mcp \
@@ -660,4 +660,11 @@ To help you develop and debug the widget + plugin in your instance, JOE exposes
     <a href="/ai-widget-test.html" target="ai_widget_test_win" rel="noopener">AI Widget</a>
     ```
 
-  - This appears on MCP test/export/prompt pages and on the AI widget test page itself.
+  - This appears on MCP test/export/prompt pages and on the AI widget test page itself.
+
+### AI / Widget Changelog (current work – `0.10.632`)
+
+- Added a Responses‑based tool runner for `<joe-ai-widget>` that wires `ai_assistant.tools` into MCP functions via `chatgpt.runWithTools`.
+- Enhanced widget UX: assistant/user bubble theming (using `assistant_color` and user `color`), inline “tools used this turn” meta messages, and markdown rendering for assistant replies.
+- Expanded the AI widget test page with an assistant picker, live tool JSON viewer, a clickable conversation history list (resume existing `ai_widget_conversation` threads), and safer user handling (widget conversations now store user id/name/color explicitly and OAuth token‑exchange errors from Google are surfaced clearly during login).
+- Added field-level AI autofill support: schemas can declare `ai` config on a field (e.g. `{ name:'ai_summary', type:'rendering', ai:{ prompt:'Summarize the project in a few sentences.' } }`), which renders an inline “AI” button that calls `_joe.Ai.populateField('ai_summary')` and posts to `/API/plugin/chatgpt/autofill` to compute a JSON `patch` and update the UI (with confirmation before overwriting non-empty values).

package/server/apps/aihub.js

@@ -0,0 +1,97 @@
+var App = function () {
+
+    this.title = 'AIHub';
+    this.description = 'Central hub for managing AI assistants, prompts, tools, conversations, and widget chats in JOE.';
+
+    // Core AI-related schemas in JOE
+    this.collections = [
+        'ai_assistant',
+        'ai_prompt',
+        'ai_tool',
+        'ai_response',
+        'ai_conversation',
+        'ai_widget_conversation'
+    ].concat(JOE.webconfig.default_schemas);
+
+    this.dashboard = [
+        // Standard app home: shows AIHub schemas plus default schemas
+        JOE.Apps.Cards.appHome({ cssclass: 'w2 h3' }),
+
+        // Small MCP test portal card
+        {
+            type: 'Card',
+            config: {
+                title: 'MCP Test Portal',
+                left: 0,
+                top: 3,
+                cssclass: 'w2 h1',
+                content: function () {
+                    return '' +
+                        '<div class="spaced">' +
+                          '<div><b>MCP Tools & Tests</b></div>' +
+                          '<ul style="margin:6px 0 0 16px; padding:0; list-style:disc;">' +
+                            '<li><a href="/mcp-test.html" target="mcp_test_win" rel="noopener">MCP Test</a></li>' +
+                            '<li><a href="/mcp-export.html" target="mcp_export_win" rel="noopener">MCP Export</a></li>' +
+                            '<li><a href="/mcp-schemas.html" target="mcp_schemas_win" rel="noopener">Schemas</a></li>' +
+                            '<li><a href="/mcp-prompt.html" target="mcp_prompt_win" rel="noopener">MCP Prompt</a></li>' +
+                            '<li><a href="/ai-widget-test.html" target="ai_widget_test_win">AI Widget</a></li>'+
+                          '</ul>' +
+                        '</div>';
+                }
+            }
+        },
+
+        // Cap card with an embedded joe-ai-widget that fills the panel
+        {
+            type: 'Card',
+            config: {
+                title: 'AIHub Chat',
+                left: 2,
+                top: 0,
+                cssclass: 'w4 h4',
+                content: function () {
+                    return '' +
+                        '<div style="width:100%;height:100%;display:flex;flex-direction:column;">' +
+                          '<joe-ai-assistant-picker for_widget="aihub_widget"></joe-ai-assistant-picker>' +
+                          '<joe-ai-widget ' +
+                            'id="aihub_widget" ' +
+                            'title="AIHub Assistant" ' +
+                            'source="aihub_card" ' +
+                            'user_id="' + ((_joe && _joe.User && _joe.User._id) || '') + '" ' +
+                            'style="flex:1 1 auto;width:100%;height:100%;">' +
+                          '</joe-ai-widget>' +
+                        '</div>';
+                }
+            }
+        },
+
+        // Widget conversations list (replaces Recently Updated AI Items card for now)
+        {
+            type: 'Card',
+            config: {
+                title: 'Widget Conversations',
+                left: 6,
+                top: 1,
+                cssclass: 'w2 h3',
+                content: function () {
+                    return '' +
+                        '<div style="width:100%;height:100%;display:flex;flex-direction:column;">' +
+                          '<joe-ai-conversation-list ' +
+                            'for_widget="aihub_widget" ' +
+                            'source="aihub_card">' +
+                          '</joe-ai-conversation-list>' +
+                        '</div>';
+                }
+            }
+        },
+
+        // Platform/system stats in the context of AIHub
+        JOE.Apps.Cards.systemStats({ top: 0, left: 6 })
+    ];
+
+    return this;
+};
+
+module.exports = new App();
+
+

package/server/fields/core.js

@@ -546,7 +546,10 @@ var fields = {
             return `_joe.Ai.spawnChatHelper('${object._id}');`;
         },
         
-    }
+    },
+    listConversations:{display:'Ai Conversations', type:"content",reloadable:true,run:function(obj){
+        return _joe.schemas.ai_conversation.methods.listConversations(obj,true);
+    }},
 
 };
 

package/server/modules/MCP.js

@@ -7,12 +7,21 @@
  */
 
 const MCP = {};
-const { Storage, Schemas } = global.JOE; // Adjust as needed based on how your modules are wired
 
 // Internal helpers
+function getStorage() {
+  return (global.JOE && global.JOE.Storage) || null;
+}
+
+function getSchemas() {
+  return (global.JOE && global.JOE.Schemas) || null;
+}
+
 function loadFromStorage(collection, query) {
   return new Promise((resolve, reject) => {
     try {
+      const Storage = getStorage();
+      if (!Storage) return reject(new Error('Storage module not initialized'));
       Storage.load(collection, query || {}, function(err, results){
         if (err) return reject(err);
         resolve(results || []);
@@ -38,6 +47,60 @@ function sanitizeItems(items) {
   }
 }
 
+// Resolve simple dotted paths against an object, including arrays.
+// Example: getPathValues(recipe, "ingredients.id") → ["ing1","ing2",...]
+function getPathValues(root, path) {
+  if (!root || !path) return [];
+  const parts = String(path).split('.');
+  let current = [root];
+  for (let i = 0; i < parts.length; i++) {
+    const key = parts[i];
+    const next = [];
+    for (let j = 0; j < current.length; j++) {
+      const val = current[j];
+      if (val == null) continue;
+      if (Array.isArray(val)) {
+        val.forEach(function (item) {
+          if (item && Object.prototype.hasOwnProperty.call(item, key)) {
+            next.push(item[key]);
+          }
+        });
+      } else if (Object.prototype.hasOwnProperty.call(val, key)) {
+        next.push(val[key]);
+      }
+    }
+    current = next;
+    if (!current.length) break;
+  }
+  // Flatten one level in case the last hop produced arrays
+  const out = [];
+  current.forEach(function (v) {
+    if (Array.isArray(v)) {
+      v.forEach(function (x) { if (x != null) out.push(x); });
+    } else if (v != null) {
+      out.push(v);
+    }
+  });
+  return out;
+}
+
+// Best-effort helper to get a normalized schema summary for a given name.
+// Prefers the precomputed `Schemas.summary[name]` map, but falls back to
+// `Schemas.schema[name].summary` when the summary map has not been generated
+// or that particular schema has not yet been merged in.
+function getSchemaSummary(name) {
+  if (!name) return null;
+  const Schemas = getSchemas();
+  if (!Schemas) return null;
+  if (Schemas.summary && Schemas.summary[name]) {
+    return Schemas.summary[name];
+  }
+  if (Schemas.schema && Schemas.schema[name] && Schemas.schema[name].summary) {
+    return Schemas.schema[name].summary;
+  }
+  return null;
+}
+
 function getComparable(val){
   if (val == null) return null;
   // Date-like
@@ -84,6 +147,7 @@ MCP.tools = {
 
   // List all schema names in the system
   listSchemas: async (_params, _ctx) => {
+    var Schemas = getSchemas();
     const list = (Schemas && (
       (Schemas.schemaList && Schemas.schemaList.length && Schemas.schemaList) ||
       (Schemas.schema && Object.keys(Schemas.schema))
@@ -125,25 +189,177 @@ MCP.tools = {
     }
   },
 
-  // Convenience: fetch a single object by _id (schema optional). Prefer cache; fallback to storage.
-  getObject: async ({ _id, schema, flatten = false, depth = 1 }, _ctx) => {
+  // Convenience: fetch a single object by _id (itemtype optional). Prefer cache; fallback to storage.
+  // Accepts legacy alias 'schema' for itemtype.
+  getObject: async ({ _id, itemtype, schema, flatten = false, depth = 1 }, _ctx) => {
     if (!_id) throw new Error("Missing required param '_id'");
+    itemtype = itemtype || schema; // legacy alias
     // Fast path via global lookup
     let obj = (JOE && JOE.Cache && JOE.Cache.findByID) ? (JOE.Cache.findByID(_id) || null) : null;
-    if (!obj && schema) {
-      const results = await loadFromStorage(schema, { _id });
+    if (!obj && itemtype) {
+      const results = await loadFromStorage(itemtype, { _id });
       obj = (results && results[0]) || null;
     }
-    if (!obj && schema && JOE && JOE.Cache && JOE.Cache.findByID) {
-      obj = JOE.Cache.findByID(schema, _id) || null;
+    if (!obj && itemtype && JOE && JOE.Cache && JOE.Cache.findByID) {
+      obj = JOE.Cache.findByID(itemtype, _id) || null;
     }
-    if (!obj) throw new Error(`Object not found${schema?(' in '+schema):''} with _id: ${_id}`);
+    if (!obj) throw new Error(`Object not found${itemtype?(' in '+itemtype):''} with _id: ${_id}`);
     if (flatten && JOE && JOE.Utils && JOE.Utils.flattenObject) {
       try { return sanitizeItems(JOE.Utils.flattenObject(_id, { recursive: true, depth }))[0]; } catch(e) {}
     }
     return sanitizeItems(obj)[0];
   },
 
+  /**
+   * understandObject
+   *
+   * High-level helper for agents: given an _id (and optional itemtype),
+   * returns a rich payload combining:
+   *   - object:     the raw object (ids intact)
+   *   - flattened:  the same object flattened to a limited depth
+   *   - schemas:    a map of schema summaries for the main itemtype and any
+   *                 referenced itemtypes (keyed by schema name)
+   *   - related:    an array of referenced objects discovered via outbound
+   *                 relationships in the schema summary.
+   *
+   * When `slim` is false (default), each related entry includes both `object`
+   * and `flattened`. When `slim` is true, only the main object is flattened
+   * and related entries are reduced to slim references:
+   *   { field, _id, itemtype, object: { _id, itemtype, name, info } }
+   *
+   * Agents should prefer this tool when they need to understand or work with
+   * an object by id, instead of issuing many individual getObject / getSchema
+   * calls. The original object always keeps its reference ids; expanded views
+   * live under `flattened` and `related[*]`.
+   */
+  understandObject: async ({ _id, itemtype, schema, depth = 2, slim = false } = {}, _ctx) => {
+    if (!_id) throw new Error("Missing required param '_id'");
+    itemtype = itemtype || schema;
+
+    // Base object (sanitized) without flattening
+    const base = await MCP.tools.getObject({ _id, itemtype, flatten: false }, _ctx);
+    const mainType = base.itemtype || itemtype || null;
+
+    const result = {
+      _id: base._id,
+      itemtype: mainType,
+      object: base,
+      flattened: null,
+      schemas: {},
+      related: [],
+      // Deduped lookups for global reference types
+      tags: {},
+      statuses: {},
+      slim: !!slim
+    };
+
+    // Main schema summary
+    const mainSummary = getSchemaSummary(mainType);
+    if (mainType && mainSummary) {
+      result.schemas[mainType] = mainSummary;
+    }
+
+    // Flattened view of the main object (depth-limited)
+    if (JOE && JOE.Utils && JOE.Utils.flattenObject) {
+      try {
+        const flat = JOE.Utils.flattenObject(base._id, { recursive: true, depth });
+        result.flattened = sanitizeItems(flat)[0];
+      } catch (_e) {
+        result.flattened = null;
+      }
+    }
+
+    const seenSchemas = new Set(Object.keys(result.schemas || {}));
+    function addSchemaIfPresent(name) {
+      if (!name || seenSchemas.has(name)) return;
+      const sum = getSchemaSummary(name);
+      if (sum) {
+        result.schemas[name] = sum;
+        seenSchemas.add(name);
+      }
+    }
+
+    // Discover outbound relationships from schema summary
+    const schemaSummary = mainType && getSchemaSummary(mainType);
+    const outbound = (schemaSummary &&
+      schemaSummary.relationships &&
+      Array.isArray(schemaSummary.relationships.outbound))
+      ? schemaSummary.relationships.outbound
+      : [];
+
+    for (let i = 0; i < outbound.length; i++) {
+      const rel = outbound[i] || {};
+      const field = rel.field;
+      const targetSchema = rel.targetSchema;
+      if (!field || !targetSchema) continue;
+
+      // Support nested paths like "ingredients.id" coming from objectList fields.
+      const vals = getPathValues(base, field);
+      if (!vals || !vals.length) continue;
+
+      const ids = Array.isArray(vals) ? vals : [vals];
+      for (let j = 0; j < ids.length; j++) {
+        const rid = ids[j];
+        if (!rid) continue;
+        let robj = null;
+        try {
+          robj = await MCP.tools.getObject({ _id: rid, itemtype: targetSchema, flatten: false }, _ctx);
+        } catch (_e) {
+          continue;
+        }
+        if (!robj) continue;
+
+        const rType = robj.itemtype || targetSchema;
+        // Global reference types (tag/status) go into top-level lookup maps
+        if (rType === 'tag' || rType === 'status') {
+          const mapName = (rType === 'tag') ? 'tags' : 'statuses';
+          if (!result[mapName][robj._id]) {
+            result[mapName][robj._id] = {
+              _id: robj._id,
+              itemtype: rType,
+              name: robj.name || robj.label || robj.info || ''
+            };
+          }
+        } else {
+          if (slim) {
+            const slimObj = toSlim(robj);
+            result.related.push({
+              field,
+              _id: slimObj._id,
+              itemtype: slimObj.itemtype || rType,
+              object: {
+                _id: slimObj._id,
+                itemtype: slimObj.itemtype || rType,
+                name: slimObj.name,
+                info: slimObj.info
+              }
+            });
+          } else {
+            let rflat = null;
+            if (JOE && JOE.Utils && JOE.Utils.flattenObject) {
+              try {
+                const f = JOE.Utils.flattenObject(robj._id, { recursive: true, depth: Math.max(1, depth - 1) });
+                rflat = sanitizeItems(f)[0];
+              } catch (_e) {
+                rflat = null;
+              }
+            }
+            result.related.push({
+              field,
+              _id: robj._id,
+              itemtype: rType,
+              object: robj,
+              flattened: rflat
+            });
+          }
+        }
+        addSchemaIfPresent(rType || targetSchema);
+      }
+    }
+
+    return result;
+  },
+
   /* Deprecated: use unified 'search' instead
   getObjectsByIds: async () => { throw new Error('Use search with ids instead'); },
   queryObjects: async () => { throw new Error('Use search instead'); },
@@ -153,23 +369,25 @@ MCP.tools = {
   searchCache: async () => { throw new Error('Use search instead'); },
   */
 
-  // Unified search: defaults to cache; set source="storage" to query DB for a schema
-  search: async ({ schema, query = {}, ids, source = 'cache', limit = 50, offset = 0, flatten = false, depth = 1, countOnly = false, withCount = false, sortBy, sortDir = 'desc', slim = false }, _ctx) => {
+  // Unified search: defaults to cache; set source="storage" to query DB for a given itemtype
+  // Accepts legacy alias 'schema' for itemtype.
+  search: async ({ itemtype, schema, query = {}, ids, source = 'cache', limit = 50, offset = 0, flatten = false, depth = 1, countOnly = false, withCount = false, sortBy, sortDir = 'desc', slim = false }, _ctx) => {
+    itemtype = itemtype || schema; // legacy alias
     const useCache = !source || source === 'cache';
     const useStorage = source === 'storage';
 
     if (ids && !Array.isArray(ids)) throw new Error("'ids' must be an array if provided");
 
-    // When ids are provided and a schema is known, prefer cache for safety/speed
-    if (Array.isArray(ids) && schema) {
+    // When ids are provided and an itemtype is known, prefer cache for safety/speed
+    if (Array.isArray(ids) && itemtype) {
       let items = [];
       if (JOE && JOE.Cache && JOE.Cache.findByID) {
-        const found = JOE.Cache.findByID(schema, ids.join(',')) || [];
+        const found = JOE.Cache.findByID(itemtype, ids.join(',')) || [];
         items = Array.isArray(found) ? found : (found ? [found] : []);
       }
       if (useStorage && (!items || items.length === 0)) {
         try {
-          const fromStorage = await loadFromStorage(schema, { _id: { $in: ids } });
+          const fromStorage = await loadFromStorage(itemtype, { _id: { $in: ids } });
           items = fromStorage || [];
         } catch (e) { /* ignore storage errors here */ }
       }
@@ -192,7 +410,7 @@ MCP.tools = {
     if (useCache) {
       if (!JOE || !JOE.Cache || !JOE.Cache.search) throw new Error('Cache not initialized');
       let results = JOE.Cache.search(query || {});
-      if (schema) results = (results || []).filter(i => i && i.itemtype === schema);
+      if (itemtype) results = (results || []).filter(i => i && i.itemtype === itemtype);
       results = sortItems(results, sortBy, sortDir);
       if (countOnly) {
         return { count: (results || []).length };
@@ -206,8 +424,8 @@ MCP.tools = {
     }
 
     if (useStorage) {
-      if (!schema) throw new Error("'schema' is required when source=storage");
-      const results = await loadFromStorage(schema, query || {});
+      if (!itemtype) throw new Error("'itemtype' is required when source=storage");
+      const results = await loadFromStorage(itemtype, query || {});
       let sorted = sortItems(results, sortBy, sortDir);
       if (countOnly) {
         return { count: (sorted || []).length };
@@ -227,7 +445,9 @@ MCP.tools = {
   },
 
   // Fuzzy, typo-tolerant search over cache with weighted fields
-  fuzzySearch: async ({ schema, q, filters = {}, fields, threshold = 0.35, limit = 50, offset = 0, highlight = false, minQueryLength = 2 }, _ctx) => {
+  // Accepts legacy alias 'schema' for itemtype.
+  fuzzySearch: async ({ itemtype, schema, q, filters = {}, fields, threshold = 0.35, limit = 50, offset = 0, highlight = false, minQueryLength = 2 }, _ctx) => {
+    itemtype = itemtype || schema; // legacy alias
     if (!q || (q+'').length < (minQueryLength||2)) {
       return { items: [] };
     }
@@ -235,7 +455,7 @@ MCP.tools = {
     var query = Object.assign({}, filters || {});
     query.$fuzzy = { q, fields, threshold, limit, offset, highlight, minQueryLength };
     var results = JOE.Cache.search(query) || [];
-    if (schema) { results = results.filter(function(i){ return i && i.itemtype === schema; }); }
+    if (itemtype) { results = results.filter(function(i){ return i && i.itemtype === itemtype; }); }
     var total = (typeof results.count === 'number') ? results.count : results.length;
     if (typeof limit === 'number' && limit > 0) { results = results.slice(0, limit); }
     return { items: sanitizeItems(results), count: total };
@@ -243,6 +463,8 @@ MCP.tools = {
 
   // Save an object via Storage (respects events/history)
   saveObject: async ({ object }, ctx = {}) => {
+    const Storage = getStorage();
+    if (!Storage) throw new Error('Storage module not initialized');
     if (!object || !object.itemtype) throw new Error("'object' with 'itemtype' is required");
     const user = (ctx.req && ctx.req.User) ? ctx.req.User : { name: 'anonymous' };
     // Ensure server-side update timestamp parity with /API/save
@@ -264,6 +486,8 @@ MCP.tools = {
 
   // Batch save with bounded concurrency; preserves per-item history/events
   saveObjects: async ({ objects, stopOnError = false, concurrency = 5 } = {}, ctx = {}) => {
+    const Storage = getStorage();
+    if (!Storage) throw new Error('Storage module not initialized');
     if (!Array.isArray(objects) || objects.length === 0) {
       throw new Error("'objects' (non-empty array) is required");
     }
@@ -319,6 +543,7 @@ MCP.tools = {
 
   // Hydration: surface core fields (from file), all schemas, statuses, and tags (no params)
   hydrate: async (_params, _ctx) => {
+    var Schemas = getSchemas();
     let coreDef = (JOE && JOE.Fields && JOE.Fields['core']) || null;
     if (!coreDef) {
       try { coreDef = require(__dirname + '/../fields/core.js'); } catch (_e) { coreDef = {}; }
@@ -372,16 +597,17 @@ MCP.descriptions = {
   listSchemas: "List all available JOE schema names.",
   getSchema: "Retrieve schema by name. Set summaryOnly=true for normalized summary instead of full schema.",
   getSchemas: "Retrieve multiple schemas. With summaryOnly=true, returns summaries; if names omitted, returns all.",
-  getObject: "Fetch a single object by _id (schema optional). Supports optional flatten.",
+  getObject: "Fetch a single object by _id (itemtype optional). Supports optional flatten. Accepts legacy alias 'schema' for itemtype.",
   // getObjectsByIds: "Deprecated - use 'search' with ids.",
   // queryObjects: "Deprecated - use 'search'.",
   // searchCache: "Deprecated - use 'search'.",
-  search: "Exact search. Defaults to cache; set source=storage to query DB. Supports sortBy/sortDir, offset/limit paging, withCount, and slim response for {_id,itemtype,name,info,joeUpdated,created}. Use fuzzySearch for typo-tolerant free text.",
-  fuzzySearch: "Fuzzy free‑text search. Candidates are prefiltered by 'filters' (e.g., { itemtype: 'user' }) and then scored. If 'fields' are omitted, the schema's searchables (strings) are used with best-field scoring; provide 'fields' (strings or {path,weight}) to use weighted sums. Examples: { q: 'corey hadden', filters: { itemtype: 'user' } } or { q: 'backyard', filters: { itemtype: 'house' } }.",
+  search: "Exact search. Defaults to cache; set source=storage to query DB. Supports sortBy/sortDir, offset/limit paging, withCount, and slim response for {_id,itemtype,name,info,joeUpdated,created}. Accepts legacy alias 'schema' for itemtype. Use fuzzySearch for typo-tolerant free text.",
+  fuzzySearch: "Fuzzy free‑text search. Candidates are prefiltered by 'filters' (e.g., { itemtype: 'user' }) and then scored. Accepts legacy alias 'schema' for itemtype. If 'fields' are omitted, the schema's searchables (strings) are used with best-field scoring; provide 'fields' (strings or {path,weight}) to use weighted sums. Examples: { q: 'corey hadden', filters: { itemtype: 'user' } } or { q: 'backyard', filters: { itemtype: 'house' } }.",
   saveObject: "Create/update an object; triggers events/history.",
   saveObjects: "Batch save objects with bounded concurrency; per-item history/events preserved.",
   hydrate: "Loads and merges the full JOE context, including core and organization-specific schemas, relationships, universal fields (tags and statuses), and datasets. Returns a single unified object describing the active environment for use by agents, UIs, and plugins.",
-  listApps: "List app definitions (title, description, collections, plugins)."
+  listApps: "List app definitions (title, description, collections, plugins).",
+  understandObject: "High-level helper: given an _id (and optional itemtype), returns { object, flattened, schemas, related[] } combining the main object, its schema summary, and referenced objects plus their schemas. Prefer this when you need to understand or reason about an object by id instead of issuing many separate getObject/getSchema calls."
 };
 
 MCP.params = {
@@ -406,7 +632,7 @@ MCP.params = {
     type: "object",
     properties: {
       _id: { type: "string" },
-      schema: { type: "string" },
+      itemtype: { type: "string" },
       flatten: { type: "boolean" },
       depth: { type: "integer" }
     },
@@ -418,7 +644,7 @@ MCP.params = {
   search: {
     type: "object",
     properties: {
-      schema: { type: "string" },
+      itemtype: { type: "string" },
       query: { type: "object" },
       ids: { type: "array", items: { type: "string" } },
       source: { type: "string", enum: ["cache","storage"] },
@@ -434,10 +660,21 @@ MCP.params = {
     },
     required: []
   },
-  fuzzySearch: {
+  understandObject: {
     type: "object",
     properties: {
+      _id: { type: "string" },
+      itemtype: { type: "string" },
       schema: { type: "string" },
+      depth: { type: "integer" },
+      slim: { type: "boolean" }
+    },
+    required: ["_id"]
+  },
+  fuzzySearch: {
+    type: "object",
+    properties: {
+      itemtype: { type: "string" },
       q: { type: "string" },
       filters: { type: "object" },
       fields: {