@stratta/mcp 0.10.0 → 0.12.0

package/dist/tools/read.js

@@ -1,40 +1,51 @@
 import { z } from 'zod';
 import { api } from '../client.js';
 import { requireApiKey } from '../auth.js';
+import { catalogEntry, param } from './catalog.gen.js';
 import { defineTool } from './define.js';
 /**
- * The eight read tools: how an agent navigates a norm.
+ * The read tools: how an agent navigates a norm.
  *
- * All of them are `readOnlyHint: true` — they never write, so a client is free
- * to retry them and an agent is free to explore.
+ * Names, descriptions and annotations come from the generated catalogue, which
+ * the remote transport reads too: the two transports cannot describe the same
+ * tool differently any more (ADR 22 § 2.4). What stays here is the argument
+ * schema and the call.
+ *
+ * ⚠️ The norm argument is `code` on both transports since 0.12.0. It used to
+ * be `norm` here and `code` remotely; an agent reads the schema on every
+ * session, so the rename costs it nothing, and one name is one less thing a
+ * skill can get wrong.
  */
-const norm = z
-    .string()
-    .min(1)
-    .describe('Norm code, e.g. "SIA 261", "SIA 263", "EN 1992-1-1".');
-const sectionPath = z
-    .string()
-    .min(1)
-    .describe('Section path as it appears in the document, e.g. "4.2.1" or "Annexe A".');
-const readOnly = { readOnlyHint: true, openWorldHint: false };
+const headOf = (name) => {
+    const entry = catalogEntry(name);
+    return {
+        name,
+        title: entry.title,
+        description: entry.description,
+        annotations: entry.annotations,
+    };
+};
+const code = (tool) => z.string().min(1).describe(param(tool, 'code'));
+const path = (tool) => z.string().min(1).describe(param(tool, 'path'));
+const edition = (tool) => z.string().optional().describe(param(tool, 'edition'));
 export const getMethodology = defineTool({
-    name: 'get_methodology',
-    title: 'Get methodology',
-    description: 'MANDATORY FIRST CALL when answering any technical question about Swiss civil engineering norms via Stratta. Returns the canonical persona, navigation workflow, meta-routing hints (which SIA norms cover which topics), tree-navigation rules (where to look for formulas vs coefficients vs definitions), citation format and answer rules. Adopt these rules verbatim for the rest of the consultation. If you skip this call you WILL produce lower-quality answers (wrong citation format, missing cross-norm dependencies, hallucinated values).',
-    inputSchema: {
-        norm: norm
-            .optional()
-            .describe('Optional: norm code the user is asking about, if already known. Used to scope methodology hints (currently informational only).'),
-    },
-    annotations: readOnly,
-    run: (client, args) => client.query(api._mcp.getMethodology, { norm: args.norm }),
+    ...headOf('get_methodology'),
+    inputSchema: {},
+    run: (client) => client.action(api._mcp.getMethodology, { apiKey: requireApiKey() }),
+    // One Markdown document, read at the start of every conversation.
+    toContent: (result) => ({
+        content: [{ type: 'text', text: result.text }],
+        structuredContent: result,
+    }),
+});
+export const whoami = defineTool({
+    ...headOf('whoami'),
+    inputSchema: {},
+    run: (client) => client.action(api._mcp.whoami, { apiKey: requireApiKey() }),
 });
 export const listNorms = defineTool({
-    name: 'list_norms',
-    title: 'List norms',
-    description: "List all engineering norms (SIA, Eurocodes, etc.) available in YOUR workspace. Returns code, year, title, and language for each. Workflow: call get_methodology FIRST (persona + rules), then list_norms to know what is queryable, then meta-route the user's question to the relevant norms before drilling in.",
+    ...headOf('list_norms'),
     inputSchema: {},
-    annotations: readOnly,
     run: async (client) => ({
         norms: await client.action(api._mcp.listPublishedNorms, {
             apiKey: requireApiKey(),
@@ -42,24 +53,23 @@ export const listNorms = defineTool({
     }),
 });
 export const getToc = defineTool({
-    name: 'get_toc',
-    title: 'Get table of contents',
-    description: "Get the high-level table of contents for a norm. By default returns only top-level chapters (depth=1) to stay light. Call get_subtree on a specific chapter's path to drill into sections + subsections. Increase maxDepth if you need a wider overview (cost: response size grows fast). Each node has path, title, summary, pageStart, pageEnd, depth, and children (empty at the maxDepth boundary).",
+    ...headOf('get_toc'),
     inputSchema: {
-        norm,
+        code: code('get_toc'),
+        edition: edition('get_toc'),
         maxDepth: z
             .number()
             .int()
             .min(1)
             .max(6)
             .optional()
-            .describe('Maximum nesting depth to include. Defaults to 1 (chapters only). depth=2 includes sections X.Y. depth=3 includes sub-subsections X.Y.Z (may exceed response size limit on large norms).'),
+            .describe(param('get_toc', 'maxDepth')),
     },
-    annotations: readOnly,
     run: async (client, args) => {
         const tree = await client.action(api._mcp.getDocumentToc, {
             apiKey: requireApiKey(),
-            code: args.norm,
+            code: args.code,
+            edition: args.edition,
             maxDepth: args.maxDepth,
         });
         // An unknown or unpublished norm comes back empty. Saying so beats
@@ -67,132 +77,195 @@ export const getToc = defineTool({
         // chapters" and then answer from memory.
         if (!tree || (Array.isArray(tree) && tree.length === 0)) {
             return {
-                error: `Norm "${args.norm}" not found in your workspace, or not published yet. Call list_norms to see what is available.`,
+                error: `Norm "${args.code}" not found in your workspace, or not published yet. Call list_norms to see what is available.`,
             };
         }
-        return { norm: args.norm, tree };
+        return { code: args.code, tree };
     },
 });
 export const getSubtree = defineTool({
-    name: 'get_subtree',
-    title: 'Get subtree',
-    description: 'Drill down into a specific chapter or section. Returns the subtree rooted at `path` with optional depth limit (relative to the root). Use this after get_toc to explore one chapter in detail without fetching the entire TOC. Each node has path, title, summary, depth, pageStart, pageEnd, and recursive children.',
+    ...headOf('get_subtree'),
     inputSchema: {
-        norm,
-        path: sectionPath.describe('Section path to root the subtree at, e.g. "14" or "14.2".'),
+        code: code('get_subtree'),
+        edition: edition('get_subtree'),
+        path: path('get_subtree'),
         maxDepth: z
             .number()
             .int()
             .min(1)
             .max(6)
             .optional()
-            .describe('Max nesting depth relative to the root. Default: unlimited. depth=1 returns the root + direct children only.'),
+            .describe(param('get_subtree', 'maxDepth')),
+        maxNodes: z
+            .number()
+            .int()
+            .min(20)
+            .max(2000)
+            .optional()
+            .describe(param('get_subtree', 'maxNodes')),
     },
-    annotations: readOnly,
     run: async (client, args) => {
         const tree = await client.action(api._mcp.getSubtree, {
             apiKey: requireApiKey(),
-            code: args.norm,
+            code: args.code,
+            edition: args.edition,
             path: args.path,
             maxDepth: args.maxDepth,
+            maxNodes: args.maxNodes,
         });
         if (tree === null) {
             return {
-                error: `Section "${args.path}" not found in norm "${args.norm}".`,
+                error: `Section "${args.path}" not found in norm "${args.code}", or the norm is not in your workspace. Call list_norms, then get_toc on the norm.`,
             };
         }
-        return { norm: args.norm, root: args.path, tree };
+        return { code: args.code, root: args.path, tree };
     },
 });
 export const getSection = defineTool({
-    name: 'get_section',
-    title: 'Get section',
-    description: "Fetch the full enriched content of a section: markdown text with formulas in LaTeX and tables inline, pageStart/pageEnd, figures (call get_figure for the image), attached tables/formulas, and cross-references to other norms. ALL technical claims in your answer MUST be backed by a [<norm> <path>, p. <pageStart>] citation pointing to a section you actually fetched via get_section — never cite from memory. When a section's crossRefs list non-empty targets, follow them with another get_section call if the answer depends on them.",
-    inputSchema: { norm, path: sectionPath },
-    annotations: readOnly,
+    ...headOf('get_section'),
+    inputSchema: {
+        code: code('get_section'),
+        edition: edition('get_section'),
+        path: path('get_section'),
+        maxChars: z
+            .number()
+            .int()
+            .min(500)
+            .max(40_000)
+            .optional()
+            .describe(param('get_section', 'maxChars')),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe(param('get_section', 'offset')),
+    },
     run: async (client, args) => {
-        const section = await client.action(api._mcp.getSection, {
+        const section = (await client.action(api._mcp.getSection, {
             apiKey: requireApiKey(),
-            code: args.norm,
+            code: args.code,
+            edition: args.edition,
             path: args.path,
-        });
+            maxChars: args.maxChars,
+            offset: args.offset,
+        }));
         if (section === null) {
             return {
-                error: `Section "${args.path}" not found in norm "${args.norm}".`,
+                error: `Section "${args.path}" not found in norm "${args.code}", or the norm is not in your workspace. Call list_norms, then get_toc on the norm to read its section paths.`,
             };
         }
-        return { norm: args.norm, section };
+        return { code: args.code, section };
+    },
+    // The section as one document. The JSON travels as `structuredContent` for
+    // a client that wants the fields; the model reads the Markdown.
+    toContent: (result) => {
+        const r = result;
+        if (r.error || !r.section) {
+            return {
+                content: [{ type: 'text', text: r.error ?? 'Section unavailable.' }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: 'text', text: r.section.markdown }],
+            structuredContent: r.section,
+        };
     },
 });
 export const searchInNorm = defineTool({
-    name: 'search_in_norm',
-    title: 'Search in norm',
-    description: 'Full-text search within a norm. Returns up to `limit` matches in relevance order, with path, title and a snippet. Matching is by term, not substring: "charges variables" finds sections containing those words, and a hit in a section TITLE ranks above one in its body. Use this when you do not yet know which section to read.',
+    ...headOf('search_in_norm'),
     inputSchema: {
-        norm,
+        code: code('search_in_norm'),
+        edition: edition('search_in_norm'),
         keyword: z
             .string()
             .min(1)
             .max(200)
-            .describe('Search terms. Searches both section titles and content.'),
+            .describe(param('search_in_norm', 'keyword')),
         limit: z
             .number()
             .int()
             .min(1)
             .max(50)
             .optional()
-            .describe('Max results to return (default 20).'),
+            .describe(param('search_in_norm', 'limit')),
     },
-    annotations: readOnly,
     run: async (client, args) => ({
-        norm: args.norm,
+        code: args.code,
+        edition: args.edition,
         keyword: args.keyword,
         hits: await client.action(api._mcp.searchInNorm, {
             apiKey: requireApiKey(),
-            code: args.norm,
+            code: args.code,
+            edition: args.edition,
+            keyword: args.keyword,
+            limit: args.limit,
+        }),
+    }),
+});
+export const searchCorpus = defineTool({
+    ...headOf('search_corpus'),
+    inputSchema: {
+        keyword: z
+            .string()
+            .min(1)
+            .max(200)
+            .describe(param('search_corpus', 'keyword')),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(40)
+            .optional()
+            .describe(param('search_corpus', 'limit')),
+    },
+    run: async (client, args) => ({
+        keyword: args.keyword,
+        norms: await client.action(api._mcp.searchCorpus, {
+            apiKey: requireApiKey(),
             keyword: args.keyword,
             limit: args.limit,
         }),
     }),
 });
 export const getCrossRefs = defineTool({
-    name: 'get_cross_refs',
-    title: 'Get cross-references',
-    description: 'List outgoing cross-references from a section to other norms (e.g. SIA 261 §4.2 → SIA 263). For compound questions you MUST follow these refs: fetch each target via get_section before concluding. Skipping cross-refs is the #1 cause of incomplete answers — SIA norms intentionally distribute the rule, the coefficient, and the action across separate norms (260 / 261 / domain).',
-    inputSchema: { norm, path: sectionPath },
-    annotations: readOnly,
+    ...headOf('get_cross_refs'),
+    inputSchema: {
+        code: code('get_cross_refs'),
+        edition: edition('get_cross_refs'),
+        path: path('get_cross_refs'),
+    },
     run: async (client, args) => ({
-        norm: args.norm,
+        code: args.code,
+        edition: args.edition,
         path: args.path,
         crossRefs: await client.action(api._mcp.getCrossRefs, {
             apiKey: requireApiKey(),
-            code: args.norm,
+            code: args.code,
+            edition: args.edition,
             path: args.path,
         }),
     }),
 });
 export const getFigure = defineTool({
-    name: 'get_figure',
-    title: 'Get figure',
-    description: 'Retrieve a figure (image) referenced in a section. Returns the image inline (base64) so you can see and reason about it. Use the `id` returned by get_section in its `figures` array.',
+    ...headOf('get_figure'),
     inputSchema: {
-        norm,
-        figureId: z
-            .string()
-            .min(1)
-            .describe('Figure ID from get_section response (figures[].id).'),
+        code: code('get_figure'),
+        edition: edition('get_figure'),
+        figureId: z.string().min(1).describe(param('get_figure', 'figureId')),
     },
-    annotations: readOnly,
     run: async (client, args) => {
         const apiKey = requireApiKey();
         const meta = (await client.action(api._mcp.getFigureMeta, {
             apiKey,
-            code: args.norm,
+            code: args.code,
+            edition: args.edition,
             figureId: args.figureId,
         }));
         if (!meta)
             return { error: 'Figure not found.' };
-        // The storage URL is used server-side, here, only to download the bytes —
+        // The storage URL is used server-side, here, only to download the bytes;
         // it is never returned to the agent. Convex `getUrl` hands back a bare,
         // unsigned, non-expiring public link, and the norm figures are licensed,
         // per-org content: surfacing that link would drop a permanent, tenant-
@@ -200,7 +273,8 @@ export const getFigure = defineTool({
         // logs). The agent gets the image inline instead.
         const url = (await client.action(api._mcp.getStorageUrl, {
             apiKey,
-            code: args.norm,
+            code: args.code,
+            edition: args.edition,
             figureId: args.figureId,
         }));
         if (!url)
@@ -230,18 +304,20 @@ export const getFigure = defineTool({
         return {
             content: [
                 { type: 'image', data: r.image.base64, mimeType: r.image.mimeType },
-                { type: 'text', text: `${r.figureNumber} — ${r.caption}` },
+                { type: 'text', text: `${r.figureNumber}: ${r.caption}` },
             ],
         };
     },
 });
 export const readTools = [
     getMethodology,
+    whoami,
     listNorms,
     getToc,
     getSubtree,
     getSection,
     searchInNorm,
+    searchCorpus,
     getCrossRefs,
     getFigure,
 ];

package/dist/usage.d.ts

@@ -0,0 +1,3 @@
+export declare const USAGE_DIGEST_MAX = 80;
+export declare const SESSION_ID: `${string}-${string}-${string}-${string}-${string}`;
+export declare function usageDigest(args: unknown): string | undefined;

package/dist/usage.js

@@ -0,0 +1,50 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Session and argument digest reported with every tool call.
+ *
+ * A stdio server lives exactly as long as the agent's process, so one id per
+ * process is the session: everything an agent did in one conversation lands
+ * under the same `sessionId`, and the dashboard can read the path it took.
+ *
+ * The digest is a short, fixed address of what was asked for (norm code,
+ * section path, search terms, identifiers), never the free-form fields. Both
+ * strings are telemetry for the key's own organisation and nothing else: the
+ * server bounds them and never lets them decide anything.
+ *
+ * ⚠️ Mirror of `convex/usageDigest.ts`. The package is published alone and
+ * cannot import from the workspace; keep the two in step.
+ */
+const DIGEST_KEYS = [
+    'code',
+    'norm',
+    'path',
+    'keyword',
+    'figureId',
+    'documentId',
+    'sectionId',
+    'dossierId',
+    'questionId',
+    'name',
+];
+export const USAGE_DIGEST_MAX = 80;
+export const SESSION_ID = randomUUID();
+export function usageDigest(args) {
+    if (typeof args !== 'object' || args === null)
+        return undefined;
+    const record = args;
+    const parts = [];
+    for (const key of DIGEST_KEYS) {
+        const value = record[key];
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            if (trimmed.length > 0)
+                parts.push(trimmed);
+        }
+        else if (typeof value === 'number') {
+            parts.push(String(value));
+        }
+    }
+    if (parts.length === 0)
+        return undefined;
+    return parts.join('|').slice(0, USAGE_DIGEST_MAX);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stratta/mcp",
   "mcpName": "ch.stratta/mcp",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "MCP server exposing the engineering norms your firm is licensed for (SIA / Eurocodes) to any MCP client, via Stratta TreeRAG.",
   "license": "UNLICENSED",
   "author": "SmartFlow <hello@stratta.ch>",