@thinger-io/cli-core 0.4.2 → 0.5.0

package/lib/mcp/core-types.js

@@ -0,0 +1,36 @@
+// @ts-check
+import { bucketData } from './types/bucket-data.js';
+import { dashboardActions } from './types/dashboard-apps.js';
+import { deviceResource, overview } from './types/device-resource.js';
+import { doc } from './types/doc.js';
+import { pluginCall } from './types/plugin-call.js';
+import { apiCall } from './types/product-api.js';
+import { profile } from './types/profile.js';
+import { storageFile } from './types/storage-file.js';
+
+/**
+ * What every CLI on the core serves next to the catalog, through the same
+ * `resource_*` tools: data and files as types (a bucket's time series, a
+ * storage's files, a connected device's resources), the guides and the
+ * profiles, and the actions on catalog types that are more than one
+ * request (or run on this machine). They take the shape of the types and
+ * actions a CLI adds (tools-resource.js), with the server operations each
+ * runs (`ops`, `op`), or `local` when it runs here.
+ */
+
+/** @type {Record<string, import('./tools-resource.js').LocalType>} */
+export const CORE_TYPES = {
+    bucket_data: bucketData,
+    storage_file: storageFile,
+    device_resource: deviceResource,
+    doc,
+    profile,
+};
+
+/** @type {Record<string, Record<string, import('./tools-resource.js').LocalAction>>} */
+export const CORE_ACTIONS = {
+    device: { overview },
+    product_profile_api: { call: apiCall },
+    plugin: { call: pluginCall },
+    dashboard: dashboardActions,
+};

package/lib/mcp/helpers.js

@@ -1,7 +1,28 @@
 // @ts-check
 import { getProfile, withActiveProfile } from '../config.js';
 import { inputError } from '../errors.js';
-import { toolName } from './naming.js';
+import { opRef } from './naming.js';
+
+/**
+ * Key of the structured answer a tool result carries next to its text, for
+ * the CLI commands that run the same handlers (`--json`). A symbol: it
+ * never reaches the MCP client.
+ */
+export const DATA = Symbol('data');
+
+/**
+ * Set on the arguments of a call a CLI command makes (runTool): the
+ * answer is read by a person, so records go without the `ids` an agent
+ * passes back.
+ */
+export const CLI = Symbol('cli');
+
+/** A text tool result, with `data` for the CLI's --json when given. */
+export const textResult = (t, data) => ({
+    content: [{ type: 'text', text: t }],
+    isError: false,
+    ...(data === undefined ? {} : { [DATA]: data }),
+});
 
 /** Run `fn` against `profile` (when supplied) so callers can target any
  *  configured environment per tool call without persisting the change.
@@ -11,7 +32,7 @@ export async function withProfile(profile, fn) {
     if (!profile) return fn();
     if (!getProfile(profile)) {
         throw inputError(
-            `Unknown profile: ${profile}. Use ${toolName('profile_list')} to list available ones.`,
+            `Unknown profile: ${profile}. ${opRef('profile', 'list')} lists the available ones.`,
         );
     }
     return withActiveProfile(profile, fn);

package/lib/mcp/naming.js

@@ -9,6 +9,10 @@ import { identity } from '../identity.js';
  * `{family:token}` (→ `thinger_token_*`); the registry expands both once
  * the identity is known. Handlers building messages at call time use
  * `toolName()` directly.
+ *
+ * The tools are the eight `resource_*` ones: an operation is a type and a
+ * verb or action, written `{op:<type>.<verb|action>}` in the texts (the
+ * resource tools expand it, checking it exists) and `opRef()` in code.
  */
 
 const TOOL_REF = /\{(tool|family):([a-z0-9_]+)\}/g;
@@ -42,3 +46,19 @@ export function expandToolRefs(text, known, where) {
         return toolName(base);
     });
 }
+
+/** Verbs with a tool of their own; anything else is an action of resource_call. */
+const VERB_TOOLS = new Set(['describe', 'list', 'get', 'create', 'update', 'delete', 'clone']);
+
+/**
+ * How an operation is called: `<prefix>_resource_list type "bucket_data"`,
+ * `<prefix>_resource_call type "device" action "send"`.
+ *
+ * @param {string} type
+ * @param {string} op  A verb or an action.
+ */
+export function opRef(type, op) {
+    return VERB_TOOLS.has(op)
+        ? `${toolName(`resource_${op}`)} type "${type}"`
+        : `${toolName('resource_call')} type "${type}" action "${op}"`;
+}

package/lib/mcp/registry.js

@@ -1,15 +1,8 @@
 // @ts-check
-import { tools as bucketTools } from './tools-buckets.js';
-import { tools as dashboardTools } from './tools-dashboards.js';
-import { tools as deviceTools } from './tools-devices.js';
-import { tools as miscTools } from './tools-misc.js';
-import { tools as pluginTools } from './tools-plugins.js';
-import { tools as productTools } from './tools-products.js';
 import { resourceTools } from './tools-resource.js';
-import { tools as storageTools } from './tools-storage.js';
 import { docMimeType, listDocs, readDoc } from '../docs.js';
 import { identity } from '../identity.js';
-import { expandToolRefs, toolName } from './naming.js';
+import { expandToolRefs, opRef, toolName } from './naming.js';
 
 /**
  * @typedef {object} ToolOptions
@@ -19,77 +12,35 @@ import { expandToolRefs, toolName } from './naming.js';
  *   Resource types the CLI adds, served by the same `resource_*` tools.
  * @property {Record<string, Record<string, import('./tools-resource.js').LocalAction>>} [actions]
  *   Actions the CLI adds to resource types (the server's or its own).
+ * @property {boolean} [readOnly]  Serve only what reads (`mcp --read-only`).
  */
 
 /**
- * Tools available to every CLI, declared with their bare names: the
- * generic `resource_*` ones over the catalog, and the few operations that
- * are not CRUD.
- *
- * @param {ToolOptions} [opts]
- */
-export function genericTools(opts = {}) {
-    return [
-        ...resourceTools(opts),
-        ...deviceTools,
-        ...productTools,
-        ...bucketTools,
-        ...storageTools,
-        ...dashboardTools,
-        ...pluginTools,
-        ...miscTools,
-    ];
-}
-
-// `profile_list` is the lookup of the profiles themselves, so it takes none.
-const PROFILE_EXEMPT = new Set(['profile_list']);
-
-/**
- * Build the tool list a CLI serves: its own tools on top of the generic
- * ones, every name prefixed with the identity's tool prefix, `{tool:x}`
- * references in descriptions expanded, and the optional `profile`
- * parameter injected so callers can target any configured environment
- * per call without changing the saved default.
+ * Build the tool list a CLI serves: the eight `resource_*` tools over the
+ * catalog, the core's types and the CLI's, every name prefixed with the
+ * identity's tool prefix, `{tool:x}` references in descriptions expanded,
+ * and the optional `profile` parameter injected so callers can target any
+ * configured environment per call without changing the saved default.
  *
  * Returns fresh objects: the declarations stay untouched, so building
- * twice (tests, a CLI adding tools) never double-prefixes anything.
+ * twice (tests) never double-prefixes anything.
  *
- * @param {Array<object>} [extraTools] CLI-specific tools, same shape as the
- *   generic ones; `replaces: true` swaps out the generic tool of that name.
  * @param {ToolOptions} [opts]
+ * @returns {Array<Record<string, any>>}
  */
-export function buildTools(extraTools = [], opts = {}) {
-    const generic = genericTools(opts);
-    // A CLI may replace a generic tool with its own (same name, flagged
-    // `replaces: true`): its platform knows more about that operation.
-    // Without the flag a clash is a mistake and fails loudly.
-    const replaced = new Set();
-    const extraNames = new Set();
-    for (const t of extraTools) {
-        if (extraNames.has(t.name)) throw new Error(`Duplicate MCP tool name: ${t.name}`);
-        extraNames.add(t.name);
-        const isGeneric = generic.some((g) => g.name === t.name);
-        if (t.replaces && !isGeneric) {
-            throw new Error(`MCP tool "${t.name}" replaces no generic tool`);
-        }
-        if (isGeneric && !t.replaces) throw new Error(`Duplicate MCP tool name: ${t.name}`);
-        if (isGeneric) replaced.add(t.name);
-    }
-    const declared = [...generic.filter((t) => !replaced.has(t.name)), ...extraTools];
+export function buildTools(opts = {}) {
+    const declared = resourceTools(opts);
     const known = new Set(declared.map((t) => t.name));
 
     return declared.map((t) => {
         const inputSchema = expandSchema(structuredClone(t.inputSchema), known, t.name);
-        if (!PROFILE_EXEMPT.has(t.name)) {
-            inputSchema.properties = inputSchema.properties || {};
-            inputSchema.properties.profile = {
-                type: 'string',
-                description: `CLI profile (server) for this call, see ${toolName('profile_list')}. Omit for the default.`,
-            };
-        }
-        const { replaces: _replaces, ...rest } = t;
+        inputSchema.properties = inputSchema.properties || {};
+        inputSchema.properties.profile = {
+            type: 'string',
+            description: `CLI profile (server) for this call; ${opRef('profile', 'list')} lists them. Omit for the default.`,
+        };
         return {
-            ...rest,
+            ...t,
             name: toolName(t.name),
             description: expandToolRefs(t.description, known, t.name),
             inputSchema,
@@ -121,7 +72,7 @@ export async function listResources() {
         uri: `${prefix}://${d.id}`,
         name: d.id,
         title: d.title,
-        description: `${d.description || d.title} Also through ${toolName('doc_read')}.`,
+        description: `${d.description || d.title} Also through ${opRef('doc', 'get')}.`,
         mimeType: docMimeType(d.format),
     }));
 }

package/lib/mcp/resource-hooks.js

@@ -1,7 +1,7 @@
 // @ts-check
 import { CREDENTIAL_DEVICE_TYPES, generateDeviceCredentials } from '../devices.js';
 import { identity } from '../identity.js';
-import { resolveExpiry, validatePermissionTree } from '../tokens.js';
+import { resolveExpiry, resolveExpiryMs, validatePermissionTree } from '../tokens.js';
 import { toolName } from './naming.js';
 
 /**
@@ -15,10 +15,13 @@ import { toolName } from './naming.js';
  *
  * @typedef {object} HookContext
  * @property {string} type
- * @property {string} [parent]
- * @property {string} [id]
+ * @property {Record<string, string>} ids  Every id of the call, by name.
+ * @property {string} [parent]  The parents' ids, outermost first, joined with "/".
+ * @property {string} [id]      The record's own id.
  * @property {string | null} [user]
  * @property {boolean} [full]  resource_get asked for the whole record.
+ * @property {boolean} [merge]  resource_update patches (beforeUpdate gets the patch).
+
  * @property {Record<string, any>} state  Scratch space shared by the hooks of one call.
  *
  * @typedef {object} ResourceHooks
@@ -29,14 +32,16 @@ import { toolName } from './naming.js';
  * @property {(record: any, ctx: HookContext) => any} [afterGet]  Returns the record to show.
  * @property {(ctx: HookContext) => string | void | Promise<string | void>} [afterDelete]
  *   Returns a note added to the tool's answer.
+ * @property {() => any} [describe]  What resource_describe adds about the type, under
+ *   `cli`: the rules the CLI's other hooks enforce, say.
  */
 
-/** Token bodies: expiry as a duration, permission trees checked before sending. */
+/** Token bodies: expiry as a duration (or unix ms), permission trees checked before sending. */
 function tokenBody(body) {
     validatePermissionTree(body.allow, 'allow');
     validatePermissionTree(body.deny, 'deny');
     if (body.expire === undefined) return body;
-    const expire = resolveExpiry(body.expire);
+    const expire = resolveExpiryMs(body.expire);
     const { expire: _expire, ...rest } = body;
     return expire === null ? rest : { ...rest, expire };
 }
@@ -131,6 +136,15 @@ export function mergeHooks(extra = {}) {
             const first = base[stage];
             if (!first) {
                 out[stage] = fn;
+            } else if (stage === 'describe') {
+                // Both are shown, the CLI's last.
+                const [one, two] = /** @type {Array<() => any>} */ ([first, fn]);
+                out[stage] = async () => {
+                    const [a, b] = [await one(), await two()];
+                    return a && b && typeof a === 'object' && typeof b === 'object'
+                        ? { ...a, ...b }
+                        : (b ?? a);
+                };
             } else if (stage === 'afterCreate' || stage === 'afterDelete') {
                 // Both notes are kept.
                 out[stage] = async (a, b) =>

package/lib/mcp/server.js

@@ -13,45 +13,50 @@ import { buildTools, listResources, readResource } from './registry.js';
 import { withProfile } from './helpers.js';
 import { defineCliDocs } from '../docs.js';
 
+/** What a tool declares that the protocol lists. */
+const LISTED = ['name', 'title', 'description', 'inputSchema', 'annotations'];
+
 /**
- * Start the MCP server over stdio. Serves the generic tools plus the ones
- * the CLI adds; every tool takes an optional `profile` (and `user`, for
- * admin impersonation, where it applies).
+ * Start the MCP server over stdio. Serves the eight `resource_*` tools over
+ * the catalog, the core's types and the CLI's; every tool takes an
+ * optional `profile` (and `user`, for admin impersonation, where it
+ * applies).
  *
  * stdout is the protocol channel from here on: diagnostics go to stderr.
  *
  * @param {{
  *   version?: string,
- *   tools?: Array<object>,
  *   instructions?: string,
  *   resourceHooks?: Record<string, import('./resource-hooks.js').ResourceHooks>,
  *   resourceTypes?: Record<string, import('./tools-resource.js').LocalType>,
  *   resourceActions?: Record<string, Record<string, import('./tools-resource.js').LocalAction>>,
  *   docs?: Parameters<typeof import('../docs.js').defineCliDocs>[0],
+ *   readOnly?: boolean,
  * }} [opts]
  *   `version` is echoed in the `initialize` response's `serverInfo.version`;
  *   callers pass their `package.json#version` so the two never drift.
- *   `tools` are CLI-specific tools added to the generic set.
  *   `instructions` is the server-level guidance sent to the client.
  *   `resourceHooks` are the CLI's hooks on catalog types; `resourceTypes`
  *   and `resourceActions` the types and actions it adds to the catalog.
- *   `docs` are the guides the CLI ships (see docs.js).
+ *   `docs` are the guides the CLI ships (see docs.js). `readOnly` serves
+ *   only what reads: describe, list, get, and the read-only actions.
  */
 export async function startMCPServer({
     version = 'unknown',
-    tools: extra = [],
     instructions,
     resourceHooks,
     resourceTypes,
     resourceActions,
     docs,
+    readOnly = false,
 } = {}) {
     const { mcp } = identity();
     defineCliDocs(docs);
-    const tools = buildTools(extra, {
+    const tools = buildTools({
         hooks: resourceHooks,
         types: resourceTypes,
         actions: resourceActions,
+        readOnly,
     });
 
     const server = new Server(
@@ -66,9 +71,33 @@ export async function startMCPServer({
     );
 
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: tools.map(({ handler: _handler, ...t }) => t),
+        tools: tools.map((t) =>
+            Object.fromEntries(LISTED.filter((k) => t[k] !== undefined).map((k) => [k, t[k]])),
+        ),
     }));
 
+    /**
+     * Ask the user to confirm an action with a high impact, when the client
+     * can show a form (elicitation): the agent cannot answer for them.
+     */
+    const elicit = async (message) => {
+        const result = await server.elicitInput({
+            message,
+            requestedSchema: {
+                type: 'object',
+                properties: {
+                    confirm: {
+                        type: 'boolean',
+                        title: 'Do it',
+                        description: 'Run it as described above.',
+                    },
+                },
+                required: ['confirm'],
+            },
+        });
+        return result.action === 'accept' && result.content?.confirm === true;
+    };
+
     server.setRequestHandler(ListResourcesRequestSchema, async () => ({
         resources: await listResources(),
     }));
@@ -96,15 +125,18 @@ export async function startMCPServer({
         const known = tool.inputSchema?.properties;
         const unknown = known ? Object.keys(args).filter((k) => !(k in known)) : [];
         if (unknown.length) {
-            const message = `Unknown argument${unknown.length > 1 ? 's' : ''} ${unknown.join(', ')}. ${name} takes: ${Object.keys(known).join(', ')}.`;
+            // A filter or body key written at the top: say where it goes.
+            const hint = tool.explain?.(args, unknown);
+            const message = `Unknown argument${unknown.length > 1 ? 's' : ''} ${unknown.join(', ')}. ${name} takes: ${Object.keys(known).join(', ')}.${hint ? ` ${hint}.` : ''}`;
             return {
                 content: [{ type: 'text', text: `Error [input_error]: ${message}` }],
                 isError: true,
                 _meta: { code: 'input_error', message },
             };
         }
+        const extra = server.getClientCapabilities()?.elicitation ? { elicit } : {};
         try {
-            return await withProfile(args.profile, () => tool.handler(args));
+            return await withProfile(args.profile, () => tool.handler(args, extra));
         } catch (error) {
             // Surface the same {message, code} pair the CLI emits in JSON
             // mode so MCP clients can pattern-match on `[code]` instead of