@stratta/mcp 0.5.0 → 0.7.1

package/README.md

@@ -87,23 +87,52 @@ settings come from environment variables — see [`.env.example`](./.env.example
 
 ## Tools exposed
 
+**Read** (8 tools — query norms in your workspace):
+
 | Tool | Purpose |
 |---|---|
-| `list_norms` | List all available norms (code, year, title, language). |
-| `get_toc` | Get the hierarchical table of contents for a norm. |
-| `get_section` | Fetch the full enriched content of a section (with formulas, tables, cross-refs). |
-| `search_in_norm` | Search sections within a norm by keyword. |
-| `get_figure` | Retrieve a figure (image) inline (base64) to reason about diagrams. |
-| `get_cross_refs` | List outgoing cross-references from a section to other norms. |
+| `get_methodology` | Behavioural contract: persona, workflow, meta-routing hints, answer rules. Call first. |
+| `list_norms` | List all norms published in your workspace (code, year, title, language). |
+| `get_toc` | Hierarchical TOC for a norm (default `maxDepth=1` = chapters). |
+| `get_subtree` | Drill into a chapter/section subtree (`path` + `maxDepth`). |
+| `get_section` | Full enriched content of a section (formulas, tables, figures, cross-refs). |
+| `search_in_norm` | Keyword search inside a norm. |
+| `get_figure` | Retrieve a figure inline (base64 ImageContent) + public URL. |
+| `get_cross_refs` | Outgoing cross-refs from a section to other norms. |
+
+**Ingest** (10 tools — add YOUR licensed norms; driven by the bundled `ingest-norm` skill):
+
+| Tool | Purpose |
+|---|---|
+| `ingest_status` | Check if a norm already exists in your workspace. |
+| `ingest_create_document` | Create a draft norm document. |
+| `ingest_create_sections` | Bulk-insert sections (returns `nodeId → sectionId` map). |
+| `ingest_attach_formula` | Attach a LaTeX formula to a section. |
+| `ingest_attach_table` | Attach a structured table `{headers, rows}` to a section. |
+| `ingest_attach_cross_ref` | Attach an explicit cross-ref to another norm. |
+| `ingest_upload_figure` | Upload a figure (base64 PNG/JPEG/WebP, ≤ 8 MB) to a section. |
+| `ingest_normalize_cross_refs` | Auto-detect and rebuild cross-refs from section content. |
+| `ingest_publish` | Flip a draft to published — visible via the read tools. |
+| `ingest_delete` | Delete a document and all its children. |
 
 ## How agents should use it
 
-1. Call `list_norms` to see what's available.
-2. Call `get_toc(norm)` to navigate the structure.
-3. Call `get_section(norm, path)` to read specific content.
-4. Use `search_in_norm` when the section path is unknown.
-5. Follow `crossRefs` for compound questions (e.g. SIA 261 → SIA 263 → EC).
-6. Call `get_figure` when the section references a figure relevant to the answer.
+For querying:
+
+1. Call `get_methodology` first — load the behavioural contract.
+2. Call `list_norms` to see what's available in your workspace.
+3. Call `get_toc(norm)` to navigate the structure; `get_subtree` to drill in.
+4. Call `get_section(norm, path)` to read specific content.
+5. Use `search_in_norm` when the section path is unknown.
+6. Follow `crossRefs` for compound questions (e.g. SIA 261 → SIA 263 → EC).
+7. Call `get_figure` when the section references a figure relevant to the answer.
+
+For ingesting your own licensed norms, see the bundled **`ingest-norm` skill** —
+a 2-phase hybrid pipeline (since 0.4.0): a Python pre-pass
+(`scripts/ingest-prepass.py`, PyMuPDF) extracts the hierarchical tree and
+rasterizes figures deterministically, then the agent enriches sections with
+summaries, LaTeX formulas, tables and cross-refs via targeted visual reading.
+Requires Python ≥ 3.10 with PyMuPDF (`python -m pip install --user pymupdf`).
 
 ## Troubleshooting
 
@@ -128,8 +157,29 @@ settings come from environment variables — see [`.env.example`](./.env.example
 
 - Each user can create up to 50 active keys and 20 new keys per 24h. Revoke unused keys in the dashboard.
 
+### `QUOTA_EXCEEDED`
+
+Your organization reached one of its limits. The error names the dimension, your
+current count and the plan limit. Retrying will fail identically.
+
+| Limit | Free | Pro | Max |
+|---|---|---|---|
+| Norms | 1 | 15 | 60 |
+| Sections | 500 | 5,000 | 21,000 |
+| Figures | 60 | 750 | 3,000 |
+| Queries / month | 500 | 15,000 | 100,000 |
+| Members | 1 | 1 | 5 |
+
+Beyond Max, an Enterprise plan scales to 100 members, 300 norms and a million
+monthly queries; the calculator is at https://stratta.ch/tarifs
+
+Stock limits free up when you delete a norm (`ingest_delete`). The monthly query
+counter resets on its own. Gauges live on the Workspace page of your dashboard,
+and an org admin can also set caps below the plan. Full details:
+https://stratta.ch/docs/en/account/plans
+
 ## License
 
-Proprietary — © SmartFlow (Hugo Gebel). All rights reserved. This package is the
+Proprietary — © Stratta, Lausanne. All rights reserved. This package is the
 official Stratta MCP client; redistribution, modification, or reuse of the source
 is not permitted without prior written consent.

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Turns a server error into something an agent can act on. A quota rejection
+ * is not a bug: the agent should stop retrying and tell the user which limit
+ * was hit, so it gets the numbers instead of a stack trace.
+ */
+export declare function formatToolError(err: unknown): string;

package/dist/errors.js

@@ -0,0 +1,55 @@
+import { ConvexError } from 'convex/values';
+function isQuotaPayload(data) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        data.code === 'QUOTA_EXCEEDED');
+}
+function humanDuration(ms) {
+    const days = Math.floor(ms / 86_400_000);
+    if (days >= 1)
+        return `${days} jour${days > 1 ? 's' : ''}`;
+    const hours = Math.ceil(ms / 3_600_000);
+    return `${hours} heure${hours > 1 ? 's' : ''}`;
+}
+/**
+ * Turns a server error into something an agent can act on. A quota rejection
+ * is not a bug: the agent should stop retrying and tell the user which limit
+ * was hit, so it gets the numbers instead of a stack trace.
+ */
+export function formatToolError(err) {
+    if (err instanceof ConvexError) {
+        const data = err.data;
+        if (isQuotaPayload(data)) {
+            const lines = [
+                data.message,
+                `Dimension : ${data.label} (${data.current}/${data.limit}, demandé : ${data.requested}).`,
+                `Plan : ${data.plan}.`,
+            ];
+            if (data.retryAfter) {
+                lines.push(`Réinitialisation dans ${humanDuration(data.retryAfter)}.`);
+            }
+            lines.push('Ne relancez pas la même opération : elle échouera à l’identique tant que la limite est atteinte.');
+            return lines.join('\n');
+        }
+        if (typeof data === 'string') {
+            switch (data) {
+                case 'UNAUTHORIZED':
+                    return 'Clé API invalide ou révoquée. Relancez `npx @stratta/mcp login` pour en enregistrer une autre.';
+                case 'NO_ORGANIZATION':
+                    return "Cette clé n'est rattachée à aucune organisation. Ouvrez stratta.ch et recréez une clé depuis votre espace.";
+                case 'DOCUMENT_NOT_FOUND':
+                    return "Cette norme n'existe pas dans votre organisation, ou elle appartient à une autre.";
+                case 'SECTION_NOT_FOUND':
+                    return "Cette section n'existe pas dans votre organisation.";
+                case 'INSUFFICIENT_ROLE':
+                    return "Cette action modifie le corpus de normes et demande un rôle propriétaire ou administrateur de l'organisation. Demandez à un administrateur de votre espace de l'exécuter (ou de vous accorder ce rôle).";
+                case 'RATE_LIMITED':
+                    return 'Trop de tentatives en peu de temps. Patientez une minute avant de réessayer.';
+                default:
+                    return data;
+            }
+        }
+        return JSON.stringify(data);
+    }
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/index.js

@@ -1,155 +1,105 @@
 #!/usr/bin/env node
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { createConvexClient, api } from './client.js';
+import { formatToolError } from './errors.js';
 import { ensureAuthenticated, resolveApiKey } from './auth.js';
 import { elicitApiKey } from './elicit.js';
-import { getMethodologyTool, handleGetMethodology } from './tools/get-methodology.js';
-import { listNormsTool, handleListNorms } from './tools/list-norms.js';
-import { getTocTool, handleGetToc } from './tools/get-toc.js';
-import { getSubtreeTool, handleGetSubtree } from './tools/get-subtree.js';
-import { getSectionTool, handleGetSection } from './tools/get-section.js';
-import { searchInNormTool, handleSearchInNorm } from './tools/search-in-norm.js';
-import { getFigureTool, handleGetFigure } from './tools/get-figure.js';
-import { getCrossRefsTool, handleGetCrossRefs } from './tools/get-cross-refs.js';
-import { ingestTools, isIngestTool, handleIngestTool } from './tools/ingest.js';
-const tools = [
-    getMethodologyTool,
-    listNormsTool,
-    getTocTool,
-    getSubtreeTool,
-    getSectionTool,
-    searchInNormTool,
-    getFigureTool,
-    getCrossRefsTool,
-    ...ingestTools,
-];
-const server = new Server({ name: 'stratta-mcp', version: '0.3.0' }, { capabilities: { tools: {} } });
+import { readTools } from './tools/read.js';
+import { ingestTools } from './tools/ingest.js';
+/**
+ * Read from package.json rather than repeated in a literal. The previous
+ * version announced `0.3.0` while the published package was `0.6.0`, so every
+ * client's logs and every bug report carried the wrong number.
+ */
+function packageVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const candidate of ['../package.json', '../../package.json']) {
+        try {
+            const raw = readFileSync(join(here, candidate), 'utf8');
+            const version = JSON.parse(raw).version;
+            if (version)
+                return version;
+        }
+        catch {
+            // Try the next candidate: the file sits one level up from `dist/`, but
+            // two when running from source.
+        }
+    }
+    return '0.0.0';
+}
+const server = new McpServer({ name: 'stratta-mcp', version: packageVersion() }, { capabilities: { tools: {} } });
 const client = createConvexClient();
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools,
-}));
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
+/**
+ * Everything every tool call needs, in one place: resolve the key (env, then
+ * stored config, then prompt the user), validate it, run the tool, report
+ * usage, and turn a thrown error into a message the agent can act on.
+ *
+ * Usage is reported with the plaintext key as proof of possession — the server
+ * derives the identity from it, so a call cannot be attributed to somebody
+ * else's key.
+ */
+async function call(def, args) {
     const startedAt = Date.now();
-    let apiKeyId = null;
     let resolvedKey = null;
+    let authenticated = false;
     let status = 'success';
-    const recordUsage = () => {
-        // Only record once authenticated. Send the plaintext key (proof of
-        // possession) — the server derives the identity, so usage can't be forged
-        // for another user's key.
-        if (!apiKeyId || !resolvedKey)
+    const reportUsage = () => {
+        if (!authenticated || !resolvedKey)
             return;
         void client
             .action(api.apiKeys.recordToolUsage, {
             apiKey: resolvedKey,
-            toolName: name,
+            toolName: def.name,
             status,
             durationMs: Date.now() - startedAt,
         })
-            .catch((e) => console.error('[stratta-mcp] track failed:', e));
+            .catch((e) => console.error('[stratta-mcp] usage report failed:', e));
     };
     try {
-        resolvedKey = resolveApiKey();
-        if (!resolvedKey) {
-            resolvedKey = await elicitApiKey(server, client);
-        }
-        const auth = await ensureAuthenticated(client, resolvedKey);
-        apiKeyId = auth.apiKeyId;
-        let result;
-        if (isIngestTool(name)) {
-            result = await handleIngestTool(client, name, (args ?? {}));
-            recordUsage();
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-            };
-        }
-        switch (name) {
-            case 'get_methodology':
-                result = await handleGetMethodology(client, args);
-                break;
-            case 'list_norms':
-                result = await handleListNorms(client);
-                break;
-            case 'get_toc':
-                result = await handleGetToc(client, args);
-                break;
-            case 'get_subtree':
-                result = await handleGetSubtree(client, args);
-                break;
-            case 'get_section':
-                result = await handleGetSection(client, args);
-                break;
-            case 'search_in_norm':
-                result = await handleSearchInNorm(client, args);
-                break;
-            case 'get_figure':
-                result = await handleGetFigure(client, args);
-                break;
-            case 'get_cross_refs':
-                result = await handleGetCrossRefs(client, args);
-                break;
-            default:
-                return {
-                    content: [{ type: 'text', text: `Unknown tool: ${name}` }],
-                    isError: true,
-                };
-        }
-        // Special handling for get_figure: return ImageContent inline
-        if (name === 'get_figure' &&
-            typeof result === 'object' &&
-            result !== null &&
-            'image' in result) {
-            const r = result;
-            recordUsage();
-            const lines = [`${r.figureNumber} — ${r.caption}`];
-            if (r.url) {
-                lines.push(`Image URL: ${r.url}`);
-                lines.push(`To show this figure to the user, embed it inline in your reply as Markdown: ![${r.figureNumber}](${r.url})`);
-            }
-            return {
-                content: [
-                    {
-                        type: 'image',
-                        data: r.image.base64,
-                        mimeType: r.image.mimeType,
-                    },
-                    {
-                        type: 'text',
-                        text: lines.join('\n'),
-                    },
-                ],
-            };
-        }
-        recordUsage();
+        resolvedKey = resolveApiKey() ?? (await elicitApiKey(server.server, client));
+        await ensureAuthenticated(client, resolvedKey);
+        authenticated = true;
+        const result = await def.run(client, args);
+        reportUsage();
+        if (def.toContent)
+            return def.toContent(result);
         return {
-            content: [
-                { type: 'text', text: JSON.stringify(result, null, 2) },
-            ],
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         };
     }
     catch (err) {
         status = 'error';
-        recordUsage();
-        const message = err instanceof Error ? err.message : String(err);
+        reportUsage();
         return {
-            content: [{ type: 'text', text: `Error: ${message}` }],
+            content: [{ type: 'text', text: `Error: ${formatToolError(err)}` }],
             isError: true,
         };
     }
-});
+}
+for (const def of [...readTools, ...ingestTools]) {
+    server.registerTool(def.name, {
+        title: def.title,
+        description: def.description,
+        inputSchema: def.inputSchema,
+        annotations: def.annotations,
+    }, 
+    // The SDK validates `args` against `inputSchema` before this runs, so the
+    // handler receives values that already match the declared shape.
+    (args) => call(def, args));
+}
 async function main() {
     if (process.argv[2] === 'login') {
         const { runLogin } = await import('./login.js');
         await runLogin();
         return;
     }
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    // Stderr-only logging; stdout is reserved for MCP protocol.
-    console.error('[stratta-mcp] started, listening on stdio');
+    await server.connect(new StdioServerTransport());
+    // Stderr only; stdout carries the MCP protocol.
+    console.error(`[stratta-mcp] v${packageVersion()} listening on stdio`);
 }
 main().catch((err) => {
     console.error('[stratta-mcp] fatal:', err);

package/dist/tools/define.d.ts

@@ -0,0 +1,45 @@
+import type { ConvexHttpClient } from 'convex/browser';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { z, ZodRawShape } from 'zod';
+/**
+ * A tool, described once.
+ *
+ * The previous shape kept three things apart that always change together: a
+ * hand-written JSON Schema literal, a `handleX` function that re-declared the
+ * same argument types with `as` casts, and a `case 'x':` in a switch that
+ * wired them up. Nothing checked that the three agreed — and they did not:
+ * `args.year as number` happily accepted the string `"2020"` and failed later,
+ * inside Convex, with an error the agent could not act on.
+ *
+ * Here the Zod shape IS the schema (the SDK converts it to JSON Schema for the
+ * client), IS the runtime validation (the SDK rejects bad arguments before the
+ * handler runs), and IS the argument type (`z.infer`). One source, three uses.
+ */
+export type ToolDef<S extends ZodRawShape = ZodRawShape> = {
+    name: string;
+    /** Human-facing label shown by clients that display one. */
+    title: string;
+    description: string;
+    inputSchema: S;
+    /**
+     * Behaviour hints for the client. `readOnlyHint` lets an agent know a call
+     * is safe to retry or run speculatively; `destructiveHint` is what makes a
+     * client ask before running `ingest_delete`. Absent before — every tool
+     * looked equally dangerous, which means none did.
+     */
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+    run: (client: ConvexHttpClient, args: z.infer<z.ZodObject<S>>) => Promise<unknown>;
+    /**
+     * Optional override for turning the result into MCP content. Only
+     * `get_figure` needs it, to return the image as an `ImageContent` block
+     * rather than as JSON.
+     */
+    toContent?: (result: unknown) => CallToolResult;
+};
+/** Identity helper that keeps the generic bound to the literal shape. */
+export declare function defineTool<S extends ZodRawShape>(def: ToolDef<S>): ToolDef<S>;

package/dist/tools/define.js

@@ -0,0 +1,4 @@
+/** Identity helper that keeps the generic bound to the literal shape. */
+export function defineTool(def) {
+    return def;
+}