@stratta/mcp 0.5.0 → 0.7.1

package/dist/tools/ingest.js

@@ -1,250 +1,237 @@
+import { z } from 'zod';
 import { api } from '../client.js';
 import { requireApiKey } from '../auth.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 STRATTA_API_KEY and scoped server-side to their
-// organization (see convex/ingestionApi.ts). Driven by the `ingest-norm` skill.
-const sectionObject = {
-    type: 'object',
-    properties: {
-        nodeId: { type: 'string', description: 'Stable unique id within the doc (e.g. "s-4-2-1").' },
-        parentNodeId: { type: 'string', description: 'nodeId of the parent section, omit for roots.' },
-        path: { type: 'string', description: 'Human path, e.g. "4.2.1" or "Annexe B.1".' },
-        title: { type: 'string' },
-        summary: { type: 'string', description: '1-3 sentence summary used for tree navigation.' },
-        depth: { type: 'number', description: '0 = chapter, 1 = section, etc.' },
-        content: { type: 'string', description: 'Full enriched text (LaTeX formulas inline ok).' },
-        rawContent: { type: 'string', description: 'Raw extracted text.' },
-        pageStart: { type: 'number' },
-        pageEnd: { type: 'number' },
-        orderIndex: { type: 'number' },
+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.
+ *
+ * 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.
+ */
+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 sectionInput = z.object({
+    nodeId: z
+        .string()
+        .min(1)
+        .describe('Stable unique id within the doc (e.g. "s-4-2-1").'),
+    parentNodeId: z
+        .string()
+        .optional()
+        .describe('nodeId of the parent section, omit for roots.'),
+    path: z.string().min(1).describe('Human path, e.g. "4.2.1" or "Annexe B.1".'),
+    title: z.string().min(1),
+    summary: z
+        .string()
+        .describe('1-3 sentence summary used for tree navigation.'),
+    depth: z.number().int().min(0).describe('0 = chapter, 1 = section, etc.'),
+    content: z
+        .string()
+        .describe('Full enriched text (LaTeX formulas inline ok).'),
+    rawContent: z.string().describe('Raw extracted text.'),
+    pageStart: z.number().int().min(0),
+    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.',
+    inputSchema: {
+        code: z.string().min(1).describe('Norm code, e.g. "SIA 261".'),
     },
-    required: ['nodeId', 'path', 'title', 'summary', 'depth', 'content', 'rawContent', 'pageStart', 'pageEnd', 'orderIndex'],
-    additionalProperties: false,
-};
-export const ingestTools = [
-    {
-        name: 'ingest_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.',
-        inputSchema: {
-            type: 'object',
-            properties: { code: { type: 'string', description: 'Norm code, e.g. "SIA 261".' } },
-            required: ['code'],
-            additionalProperties: false,
-        },
-    },
-    {
-        name: 'ingest_create_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.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                code: { type: 'string' },
-                year: { type: 'number' },
-                title: { type: 'string' },
-                language: { type: 'string', enum: ['fr', 'de', 'it', 'en'] },
-                totalPages: { type: 'number' },
-            },
-            required: ['code', 'year', 'title', 'language', 'totalPages'],
-            additionalProperties: false,
-        },
+    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.',
+    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),
     },
-    {
-        name: 'ingest_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).',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                documentId: { type: 'string' },
-                sections: { type: 'array', items: sectionObject },
-            },
-            required: ['documentId', 'sections'],
-            additionalProperties: false,
-        },
+    annotations: write,
+    run: async (client, args) => ({
+        documentId: await client.action(api.ingestionApi.createDocument, {
+            apiKey: requireApiKey(),
+            ...args,
+        }),
+    }),
+});
+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).',
+    inputSchema: {
+        documentId,
+        sections: z.array(sectionInput).min(1).max(200),
     },
-    {
-        name: 'ingest_attach_formula',
-        description: 'Attach a LaTeX formula to a section.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                sectionId: { type: 'string' },
-                latex: { type: 'string' },
-                description: { type: 'string' },
-                formulaNumber: { type: 'string' },
-            },
-            required: ['sectionId', 'latex', 'description', 'formulaNumber'],
-            additionalProperties: false,
-        },
+    annotations: write,
+    run: async (client, args) => ({
+        sections: await client.action(api.ingestionApi.createSections, {
+            apiKey: requireApiKey(),
+            documentId: args.documentId,
+            sections: args.sections,
+        }),
+    }),
+});
+export const ingestAttachFormula = defineTool({
+    name: 'ingest_attach_formula',
+    title: 'Attach formula',
+    description: 'Attach a LaTeX formula to a section.',
+    inputSchema: {
+        sectionId,
+        latex: z.string().min(1),
+        description: z.string(),
+        formulaNumber: z.string(),
     },
-    {
-        name: 'ingest_attach_table',
-        description: 'Attach a structured table to a section. `data` should be { headers: string[], rows: string[][] }.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                sectionId: { type: 'string' },
-                data: { type: 'object' },
-                caption: { type: 'string' },
-                tableNumber: { type: 'string' },
-            },
-            required: ['sectionId', 'data', 'caption', 'tableNumber'],
-            additionalProperties: false,
-        },
+    annotations: write,
+    run: async (client, args) => ({
+        formulaId: await client.action(api.ingestionApi.attachFormula, {
+            apiKey: requireApiKey(),
+            ...args,
+        }),
+    }),
+});
+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[][] }.',
+    inputSchema: {
+        sectionId,
+        // 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"` —
+        // 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({
+            headers: z.array(z.coerce.string()),
+            rows: z.array(z.array(z.coerce.string())),
+        }),
+        caption: z.string(),
+        tableNumber: z.string(),
     },
-    {
-        name: 'ingest_attach_cross_ref',
-        description: 'Attach a cross-reference from a section to another norm/section.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                sourceSectionId: { type: 'string' },
-                targetDocumentCode: { type: 'string' },
-                targetSectionPath: { type: 'string' },
-                refText: { type: 'string' },
-                refType: { type: 'string', enum: ['explicit', 'implicit'] },
-            },
-            required: ['sourceSectionId', 'targetDocumentCode', 'refText', 'refType'],
-            additionalProperties: false,
-        },
+    annotations: write,
+    run: async (client, args) => ({
+        tableId: await client.action(api.ingestionApi.attachTable, {
+            apiKey: requireApiKey(),
+            ...args,
+        }),
+    }),
+});
+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.',
+    inputSchema: {
+        sourceSectionId: sectionId,
+        targetDocumentCode: z.string().min(1),
+        targetSectionPath: z.string().optional(),
+        refText: z.string(),
+        refType: z.enum(['explicit', 'implicit']),
     },
-    {
-        name: 'ingest_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.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                sectionId: { type: 'string' },
-                base64: { type: 'string', description: 'Base64-encoded image bytes (data: prefix tolerated).' },
-                mimeType: { type: 'string', enum: ['image/png', 'image/jpeg', 'image/webp'] },
-                caption: { type: 'string' },
-                figureNumber: { type: 'string' },
-            },
-            required: ['sectionId', 'base64', 'mimeType', 'caption', 'figureNumber'],
-            additionalProperties: false,
-        },
+    annotations: write,
+    run: async (client, args) => ({
+        crossRefId: await client.action(api.ingestionApi.attachCrossRef, {
+            apiKey: requireApiKey(),
+            ...args,
+        }),
+    }),
+});
+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.',
+    inputSchema: {
+        sectionId,
+        base64: 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(),
     },
-    {
-        name: 'ingest_normalize_cross_refs',
-        description: 'Scan all sections of a document and (re)build cross-references to other norms detected in the text. Idempotent.',
-        inputSchema: {
-            type: 'object',
-            properties: { documentId: { type: 'string' } },
-            required: ['documentId'],
-            additionalProperties: false,
-        },
+    annotations: write,
+    run: async (client, args) => ({
+        figureId: await client.action(api.ingestionApi.uploadFigure, {
+            apiKey: requireApiKey(),
+            ...args,
+        }),
+    }),
+});
+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 },
+    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 },
+    run: async (client, args) => {
+        await client.action(api.ingestionApi.publishDocument, {
+            apiKey: requireApiKey(),
+            documentId: args.documentId,
+        });
+        return { published: true };
     },
-    {
-        name: 'ingest_publish',
-        description: 'Publish a draft document so it becomes queryable via the read tools in YOUR workspace.',
-        inputSchema: {
-            type: 'object',
-            properties: { documentId: { type: 'string' } },
-            required: ['documentId'],
-            additionalProperties: false,
-        },
-    },
-    {
-        name: 'ingest_delete',
-        description: 'Delete a document and all its sections/figures/tables/formulas/cross-refs. Use before re-ingesting.',
-        inputSchema: {
-            type: 'object',
-            properties: { documentId: { type: 'string' } },
-            required: ['documentId'],
-            additionalProperties: false,
-        },
+});
+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 },
+    run: async (client, args) => {
+        await client.action(api.ingestionApi.deleteDocument, {
+            apiKey: requireApiKey(),
+            documentId: args.documentId,
+        });
+        return { deleted: true };
     },
+});
+export const ingestTools = [
+    ingestStatus,
+    ingestCreateDocument,
+    ingestCreateSections,
+    ingestAttachFormula,
+    ingestAttachTable,
+    ingestAttachCrossRef,
+    ingestUploadFigure,
+    ingestNormalizeCrossRefs,
+    ingestPublish,
+    ingestDelete,
 ];
-export function isIngestTool(name) {
-    return ingestTools.some((t) => t.name === name);
-}
-export async function handleIngestTool(client, name, args) {
-    const apiKey = requireApiKey();
-    switch (name) {
-        case 'ingest_status':
-            return await client.action(api.ingestionApi.ingestStatus, {
-                apiKey,
-                code: args.code,
-            });
-        case 'ingest_create_document':
-            return {
-                documentId: await client.action(api.ingestionApi.createDocument, {
-                    apiKey,
-                    code: args.code,
-                    year: args.year,
-                    title: args.title,
-                    language: args.language,
-                    totalPages: args.totalPages,
-                }),
-            };
-        case 'ingest_create_sections':
-            return {
-                sections: await client.action(api.ingestionApi.createSections, {
-                    apiKey,
-                    documentId: args.documentId,
-                    sections: args.sections,
-                }),
-            };
-        case 'ingest_attach_formula':
-            return {
-                formulaId: await client.action(api.ingestionApi.attachFormula, {
-                    apiKey,
-                    sectionId: args.sectionId,
-                    latex: args.latex,
-                    description: args.description,
-                    formulaNumber: args.formulaNumber,
-                }),
-            };
-        case 'ingest_attach_table':
-            return {
-                tableId: await client.action(api.ingestionApi.attachTable, {
-                    apiKey,
-                    sectionId: args.sectionId,
-                    data: args.data,
-                    caption: args.caption,
-                    tableNumber: args.tableNumber,
-                }),
-            };
-        case 'ingest_attach_cross_ref':
-            return {
-                crossRefId: await client.action(api.ingestionApi.attachCrossRef, {
-                    apiKey,
-                    sourceSectionId: args.sourceSectionId,
-                    targetDocumentCode: args.targetDocumentCode,
-                    targetSectionPath: args.targetSectionPath,
-                    refText: args.refText,
-                    refType: args.refType,
-                }),
-            };
-        case 'ingest_upload_figure':
-            return {
-                figureId: await client.action(api.ingestionApi.uploadFigure, {
-                    apiKey,
-                    sectionId: args.sectionId,
-                    base64: args.base64,
-                    mimeType: args.mimeType,
-                    caption: args.caption,
-                    figureNumber: args.figureNumber,
-                }),
-            };
-        case 'ingest_normalize_cross_refs':
-            return await client.action(api.ingestionApi.normalizeCrossRefs, {
-                apiKey,
-                documentId: args.documentId,
-            });
-        case 'ingest_publish':
-            await client.action(api.ingestionApi.publishDocument, {
-                apiKey,
-                documentId: args.documentId,
-            });
-            return { published: true };
-        case 'ingest_delete':
-            await client.action(api.ingestionApi.deleteDocument, {
-                apiKey,
-                documentId: args.documentId,
-            });
-            return { deleted: true };
-        default:
-            return { error: `Unknown ingest tool: ${name}` };
-    }
-}

package/dist/tools/read.d.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+export declare const getMethodology: import("./define.js").ToolDef<{
+    norm: z.ZodOptional<z.ZodString>;
+}>;
+export declare const listNorms: import("./define.js").ToolDef<{}>;
+export declare const getToc: import("./define.js").ToolDef<{
+    norm: z.ZodString;
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+}>;
+export declare const getSubtree: import("./define.js").ToolDef<{
+    norm: z.ZodString;
+    path: z.ZodString;
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+}>;
+export declare const getSection: import("./define.js").ToolDef<{
+    norm: z.ZodString;
+    path: z.ZodString;
+}>;
+export declare const searchInNorm: import("./define.js").ToolDef<{
+    norm: z.ZodString;
+    keyword: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+}>;
+export declare const getCrossRefs: import("./define.js").ToolDef<{
+    norm: z.ZodString;
+    path: z.ZodString;
+}>;
+export declare const getFigure: import("./define.js").ToolDef<{
+    norm: 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;
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+}> | import("./define.js").ToolDef<{
+    norm: z.ZodString;
+    path: z.ZodString;
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+}> | import("./define.js").ToolDef<{
+    norm: z.ZodString;
+    path: z.ZodString;
+}> | import("./define.js").ToolDef<{
+    norm: z.ZodString;
+    keyword: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+}> | import("./define.js").ToolDef<{
+    norm: z.ZodString;
+    figureId: z.ZodString;
+}>)[];