@stratta/mcp 0.9.8 → 0.12.0

package/dist/tools/ingest.js

@@ -1,28 +1,32 @@
 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';
 /**
- * Ingestion tools — let an engineering office add ITS OWN licensed norms to
- * its Stratta workspace, agentically, from the user's own Claude. Every call
- * is authenticated by the user's API key and scoped server-side to their
- * organization (see convex/ingestionApi.ts). Driven by the `ingest-norm` skill.
+ * Ingestion tools: let an engineering office add its own licensed norms to
+ * its Stratta workspace, from the user's own agent. Every call is
+ * authenticated by the user's API key and scoped server-side to their
+ * organisation (see convex/ingestionApi.ts). Driven by the `ingest-norm`
+ * skill. Absent from the remote transport on purpose: the pipeline starts
+ * with a PDF on the caller's disk.
  *
- * These used to be JSON Schema literals paired with a 90-line switch of
- * `args.year as number` casts. A cast is not a check: a client sending
- * `"2020"` passed straight through and failed deep inside Convex with an error
- * the agent could do nothing with. The Zod shapes below are enforced by the
- * SDK before the handler is entered, so a bad call fails at the boundary with
- * a message naming the field.
+ * Names, descriptions and annotations come from the generated catalogue. The
+ * Zod shapes below are enforced by the SDK before a handler runs, so a bad
+ * call fails at the boundary with a message naming the field, not deep inside
+ * Convex.
  */
-const documentId = z
-    .string()
-    .min(1)
-    .describe('Document id from ingest_create_document.');
-const sectionId = z
-    .string()
-    .min(1)
-    .describe('Section id from ingest_create_sections.');
+const headOf = (name) => {
+    const entry = catalogEntry(name);
+    return {
+        name,
+        title: entry.title,
+        description: entry.description,
+        annotations: entry.annotations,
+    };
+};
+const documentId = (tool) => z.string().min(1).describe(param(tool, 'documentId'));
+const sectionId = (tool) => z.string().min(1).describe(param(tool, 'sectionId'));
 const sectionInput = z.object({
     nodeId: z
         .string()
@@ -46,33 +50,46 @@ const sectionInput = z.object({
     pageEnd: z.number().int().min(0),
     orderIndex: z.number().int().min(0),
 });
-/** Writes: not read-only, and re-running one is not automatically safe. */
-const write = { readOnlyHint: false, openWorldHint: false };
 export const ingestStatus = defineTool({
-    name: 'ingest_status',
-    title: 'Check ingestion status',
-    description: 'Check whether a norm (by code) already exists in YOUR workspace and how many sections it has. Call before creating to avoid duplicates.',
+    ...headOf('ingest_status'),
     inputSchema: {
-        code: z.string().min(1).describe('Norm code, e.g. "SIA 261".'),
+        code: z.string().min(1).describe(param('ingest_status', 'code')),
     },
-    annotations: { readOnlyHint: true, openWorldHint: false },
     run: (client, args) => client.action(api.ingestionApi.ingestStatus, {
         apiKey: requireApiKey(),
         code: args.code,
     }),
 });
 export const ingestCreateDocument = defineTool({
-    name: 'ingest_create_document',
-    title: 'Create norm document',
-    description: 'Create a draft norm document in YOUR workspace. Returns the documentId used by subsequent ingest_* calls. You must hold a valid licence for the norm you ingest.',
+    ...headOf('ingest_create_document'),
     inputSchema: {
-        code: z.string().min(1),
-        year: z.number().int().min(1900).max(2100),
-        title: z.string().min(1),
-        language: z.enum(['fr', 'de', 'it', 'en']),
-        totalPages: z.number().int().min(1),
+        code: z.string().min(1).describe(param('ingest_create_document', 'code')),
+        year: z
+            .number()
+            .int()
+            .min(1900)
+            .max(2100)
+            .describe(param('ingest_create_document', 'year')),
+        title: z.string().min(1).describe(param('ingest_create_document', 'title')),
+        language: z
+            .enum(['fr', 'de', 'it', 'en'])
+            .describe(param('ingest_create_document', 'language')),
+        totalPages: z
+            .number()
+            .int()
+            .min(1)
+            .describe(param('ingest_create_document', 'totalPages')),
+        scope: z
+            .string()
+            .max(300)
+            .optional()
+            .describe(param('ingest_create_document', 'scope')),
+        edition: z
+            .string()
+            .max(20)
+            .optional()
+            .describe(param('ingest_create_document', 'edition')),
     },
-    annotations: write,
     run: async (client, args) => ({
         documentId: await client.action(api.ingestionApi.createDocument, {
             apiKey: requireApiKey(),
@@ -81,14 +98,15 @@ export const ingestCreateDocument = defineTool({
     }),
 });
 export const ingestCreateSections = defineTool({
-    name: 'ingest_create_sections',
-    title: 'Create sections',
-    description: 'Bulk-insert sections into a draft document. Parent links resolve via parentNodeId within the batch + already-inserted sections. Returns a map of nodeId → sectionId (use those ids to attach formulas/tables/figures/cross-refs).',
+    ...headOf('ingest_create_sections'),
     inputSchema: {
-        documentId,
-        sections: z.array(sectionInput).min(1).max(200),
+        documentId: documentId('ingest_create_sections'),
+        sections: z
+            .array(sectionInput)
+            .min(1)
+            .max(200)
+            .describe(param('ingest_create_sections', 'sections')),
     },
-    annotations: write,
     run: async (client, args) => ({
         sections: await client.action(api.ingestionApi.createSections, {
             apiKey: requireApiKey(),
@@ -98,16 +116,17 @@ export const ingestCreateSections = defineTool({
     }),
 });
 export const ingestAttachFormula = defineTool({
-    name: 'ingest_attach_formula',
-    title: 'Attach formula',
-    description: 'Attach a LaTeX formula to a section.',
+    ...headOf('ingest_attach_formula'),
     inputSchema: {
-        sectionId,
-        latex: z.string().min(1),
-        description: z.string(),
-        formulaNumber: z.string(),
+        sectionId: sectionId('ingest_attach_formula'),
+        latex: z.string().min(1).describe(param('ingest_attach_formula', 'latex')),
+        description: z
+            .string()
+            .describe(param('ingest_attach_formula', 'description')),
+        formulaNumber: z
+            .string()
+            .describe(param('ingest_attach_formula', 'formulaNumber')),
     },
-    annotations: write,
     run: async (client, args) => ({
         formulaId: await client.action(api.ingestionApi.attachFormula, {
             apiKey: requireApiKey(),
@@ -116,25 +135,24 @@ export const ingestAttachFormula = defineTool({
     }),
 });
 export const ingestAttachTable = defineTool({
-    name: 'ingest_attach_table',
-    title: 'Attach table',
-    description: 'Attach a structured table to a section. `data` is { headers: string[], rows: string[][] }.',
+    ...headOf('ingest_attach_table'),
     inputSchema: {
-        sectionId,
+        sectionId: sectionId('ingest_attach_table'),
         // Cells are coerced rather than required to be strings. Every table
         // currently stored has string cells, but a norm table is full of figures
-        // and an agent will sooner or later send `2400` instead of `"2400"` —
+        // and an agent will sooner or later send `2400` instead of `"2400"`;
         // failing mid-ingestion over that would cost far more than normalising it.
-        // The shape itself stays strict: headers and rows are what the renderer
-        // reads.
-        data: z.object({
+        data: z
+            .object({
             headers: z.array(z.coerce.string()),
             rows: z.array(z.array(z.coerce.string())),
-        }),
-        caption: z.string(),
-        tableNumber: z.string(),
+        })
+            .describe(param('ingest_attach_table', 'data')),
+        caption: z.string().describe(param('ingest_attach_table', 'caption')),
+        tableNumber: z
+            .string()
+            .describe(param('ingest_attach_table', 'tableNumber')),
     },
-    annotations: write,
     run: async (client, args) => ({
         tableId: await client.action(api.ingestionApi.attachTable, {
             apiKey: requireApiKey(),
@@ -143,17 +161,25 @@ export const ingestAttachTable = defineTool({
     }),
 });
 export const ingestAttachCrossRef = defineTool({
-    name: 'ingest_attach_cross_ref',
-    title: 'Attach cross-reference',
-    description: 'Attach a cross-reference from a section to another norm/section.',
+    ...headOf('ingest_attach_cross_ref'),
     inputSchema: {
-        sourceSectionId: sectionId,
-        targetDocumentCode: z.string().min(1),
-        targetSectionPath: z.string().optional(),
-        refText: z.string(),
-        refType: z.enum(['explicit', 'implicit']),
+        sourceSectionId: z
+            .string()
+            .min(1)
+            .describe(param('ingest_attach_cross_ref', 'sourceSectionId')),
+        targetDocumentCode: z
+            .string()
+            .min(1)
+            .describe(param('ingest_attach_cross_ref', 'targetDocumentCode')),
+        targetSectionPath: z
+            .string()
+            .optional()
+            .describe(param('ingest_attach_cross_ref', 'targetSectionPath')),
+        refText: z.string().describe(param('ingest_attach_cross_ref', 'refText')),
+        refType: z
+            .enum(['explicit', 'implicit'])
+            .describe(param('ingest_attach_cross_ref', 'refType')),
     },
-    annotations: write,
     run: async (client, args) => ({
         crossRefId: await client.action(api.ingestionApi.attachCrossRef, {
             apiKey: requireApiKey(),
@@ -162,20 +188,18 @@ export const ingestAttachCrossRef = defineTool({
     }),
 });
 export const ingestUploadFigure = defineTool({
-    name: 'ingest_upload_figure',
-    title: 'Upload figure',
-    description: 'Upload a figure image (base64) and attach it to a section. mimeType must be image/png, image/jpeg or image/webp; max 8 MB.',
+    ...headOf('ingest_upload_figure'),
     inputSchema: {
-        sectionId,
-        base64: z
+        sectionId: sectionId('ingest_upload_figure'),
+        base64: z.string().min(1).describe(param('ingest_upload_figure', 'base64')),
+        mimeType: z
+            .enum(['image/png', 'image/jpeg', 'image/webp'])
+            .describe(param('ingest_upload_figure', 'mimeType')),
+        caption: z.string().describe(param('ingest_upload_figure', 'caption')),
+        figureNumber: z
             .string()
-            .min(1)
-            .describe('Base64-encoded image bytes (data: prefix tolerated).'),
-        mimeType: z.enum(['image/png', 'image/jpeg', 'image/webp']),
-        caption: z.string(),
-        figureNumber: z.string(),
+            .describe(param('ingest_upload_figure', 'figureNumber')),
     },
-    annotations: write,
     run: async (client, args) => ({
         figureId: await client.action(api.ingestionApi.uploadFigure, {
             apiKey: requireApiKey(),
@@ -184,37 +208,31 @@ export const ingestUploadFigure = defineTool({
     }),
 });
 export const ingestNormalizeCrossRefs = defineTool({
-    name: 'ingest_normalize_cross_refs',
-    title: 'Normalize cross-references',
-    description: 'Scan all sections of a document and (re)build cross-references to other norms detected in the text. Idempotent.',
-    inputSchema: { documentId },
-    annotations: { ...write, idempotentHint: true },
+    ...headOf('ingest_normalize_cross_refs'),
+    inputSchema: { documentId: documentId('ingest_normalize_cross_refs') },
     run: (client, args) => client.action(api.ingestionApi.normalizeCrossRefs, {
         apiKey: requireApiKey(),
         documentId: args.documentId,
     }),
 });
 export const ingestPublish = defineTool({
-    name: 'ingest_publish',
-    title: 'Publish document',
-    description: 'Publish a draft document so it becomes queryable via the read tools in YOUR workspace.',
-    inputSchema: { documentId },
-    annotations: { ...write, idempotentHint: true },
+    ...headOf('ingest_publish'),
+    inputSchema: {
+        documentId: documentId('ingest_publish'),
+        force: z.boolean().optional().describe(param('ingest_publish', 'force')),
+    },
     run: async (client, args) => {
-        await client.action(api.ingestionApi.publishDocument, {
+        const quality = await client.action(api.ingestionApi.publishDocument, {
             apiKey: requireApiKey(),
             documentId: args.documentId,
+            force: args.force,
         });
-        return { published: true };
+        return { published: true, quality };
     },
 });
 export const ingestDelete = defineTool({
-    name: 'ingest_delete',
-    title: 'Delete document',
-    description: 'Delete a document and all its sections/figures/tables/formulas/cross-refs. Use before re-ingesting.',
-    inputSchema: { documentId },
-    // The one genuinely destructive tool. Clients use this hint to confirm.
-    annotations: { ...write, destructiveHint: true },
+    ...headOf('ingest_delete'),
+    inputSchema: { documentId: documentId('ingest_delete') },
     run: async (client, args) => {
         await client.action(api.ingestionApi.deleteDocument, {
             apiKey: requireApiKey(),

package/dist/tools/read.d.ts

@@ -1,51 +1,76 @@
 import { z } from 'zod';
-export declare const getMethodology: import("./define.js").ToolDef<{
-    norm: z.ZodOptional<z.ZodString>;
-}>;
+export declare const getMethodology: import("./define.js").ToolDef<{}>;
+export declare const whoami: import("./define.js").ToolDef<{}>;
 export declare const listNorms: import("./define.js").ToolDef<{}>;
 export declare const getToc: import("./define.js").ToolDef<{
-    norm: z.ZodString;
+    code: z.ZodString;
+    edition: z.ZodOptional<z.ZodString>;
     maxDepth: z.ZodOptional<z.ZodNumber>;
 }>;
 export declare const getSubtree: import("./define.js").ToolDef<{
-    norm: z.ZodString;
+    code: z.ZodString;
+    edition: z.ZodOptional<z.ZodString>;
     path: z.ZodString;
     maxDepth: z.ZodOptional<z.ZodNumber>;
+    maxNodes: z.ZodOptional<z.ZodNumber>;
 }>;
 export declare const getSection: import("./define.js").ToolDef<{
-    norm: z.ZodString;
+    code: z.ZodString;
+    edition: z.ZodOptional<z.ZodString>;
     path: z.ZodString;
+    maxChars: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
 }>;
 export declare const searchInNorm: import("./define.js").ToolDef<{
-    norm: z.ZodString;
+    code: z.ZodString;
+    edition: z.ZodOptional<z.ZodString>;
+    keyword: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+}>;
+export declare const searchCorpus: import("./define.js").ToolDef<{
     keyword: z.ZodString;
     limit: z.ZodOptional<z.ZodNumber>;
 }>;
 export declare const getCrossRefs: import("./define.js").ToolDef<{
-    norm: z.ZodString;
+    code: z.ZodString;
+    edition: z.ZodOptional<z.ZodString>;
     path: z.ZodString;
 }>;
 export declare const getFigure: import("./define.js").ToolDef<{
-    norm: z.ZodString;
+    code: z.ZodString;
+    edition: z.ZodOptional<z.ZodString>;
     figureId: z.ZodString;
 }>;
-export declare const readTools: (import("./define.js").ToolDef<{
-    norm: z.ZodOptional<z.ZodString>;
-}> | import("./define.js").ToolDef<{}> | import("./define.js").ToolDef<{
-    norm: z.ZodString;
+export declare const readTools: (import("./define.js").ToolDef<{}> | import("./define.js").ToolDef<{
+    code: z.ZodString;
+    edition: z.ZodOptional<z.ZodString>;
     maxDepth: z.ZodOptional<z.ZodNumber>;
 }> | import("./define.js").ToolDef<{
-    norm: z.ZodString;
+    code: z.ZodString;
+    edition: z.ZodOptional<z.ZodString>;
     path: z.ZodString;
     maxDepth: z.ZodOptional<z.ZodNumber>;
+    maxNodes: z.ZodOptional<z.ZodNumber>;
 }> | import("./define.js").ToolDef<{
-    norm: z.ZodString;
+    code: z.ZodString;
+    edition: z.ZodOptional<z.ZodString>;
     path: z.ZodString;
+    maxChars: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
 }> | import("./define.js").ToolDef<{
-    norm: z.ZodString;
+    code: z.ZodString;
+    edition: z.ZodOptional<z.ZodString>;
     keyword: z.ZodString;
     limit: z.ZodOptional<z.ZodNumber>;
 }> | import("./define.js").ToolDef<{
-    norm: z.ZodString;
+    keyword: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+}> | import("./define.js").ToolDef<{
+    code: z.ZodString;
+    edition: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+}> | import("./define.js").ToolDef<{
+    code: z.ZodString;
+    edition: z.ZodOptional<z.ZodString>;
     figureId: z.ZodString;
 }>)[];