@stratta/mcp 0.5.0 → 0.7.1

package/dist/tools/read.js

@@ -0,0 +1,247 @@
+import { z } from 'zod';
+import { api } from '../client.js';
+import { requireApiKey } from '../auth.js';
+import { defineTool } from './define.js';
+/**
+ * The eight 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.
+ */
+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 };
+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 }),
+});
+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.",
+    inputSchema: {},
+    annotations: readOnly,
+    run: async (client) => ({
+        norms: await client.action(api._mcp.listPublishedNorms, {
+            apiKey: requireApiKey(),
+        }),
+    }),
+});
+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 nodeId, path, title, summary, pageStart, pageEnd, depth, and children (empty at the maxDepth boundary).",
+    inputSchema: {
+        norm,
+        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).'),
+    },
+    annotations: readOnly,
+    run: async (client, args) => {
+        const tree = await client.action(api._mcp.getDocumentToc, {
+            apiKey: requireApiKey(),
+            code: args.norm,
+            maxDepth: args.maxDepth,
+        });
+        // An unknown or unpublished norm comes back empty. Saying so beats
+        // handing the agent an empty array it will read as "this norm has no
+        // 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.`,
+            };
+        }
+        return { norm: args.norm, 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 nodeId, path, title, summary, depth, pageStart, pageEnd, and recursive children.',
+    inputSchema: {
+        norm,
+        path: sectionPath.describe('Section path to root the subtree at, e.g. "14" or "14.2".'),
+        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.'),
+    },
+    annotations: readOnly,
+    run: async (client, args) => {
+        const tree = await client.action(api._mcp.getSubtree, {
+            apiKey: requireApiKey(),
+            code: args.norm,
+            path: args.path,
+            maxDepth: args.maxDepth,
+        });
+        if (tree === null) {
+            return {
+                error: `Section "${args.path}" not found in norm "${args.norm}".`,
+            };
+        }
+        return { norm: args.norm, 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,
+    run: async (client, args) => {
+        const section = await client.action(api._mcp.getSection, {
+            apiKey: requireApiKey(),
+            code: args.norm,
+            path: args.path,
+        });
+        if (section === null) {
+            return {
+                error: `Section "${args.path}" not found in norm "${args.norm}".`,
+            };
+        }
+        return { norm: args.norm, 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.',
+    inputSchema: {
+        norm,
+        keyword: z
+            .string()
+            .min(1)
+            .max(200)
+            .describe('Search terms. Searches both section titles and content.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe('Max results to return (default 20).'),
+    },
+    annotations: readOnly,
+    run: async (client, args) => ({
+        norm: args.norm,
+        keyword: args.keyword,
+        hits: await client.action(api._mcp.searchInNorm, {
+            apiKey: requireApiKey(),
+            code: args.norm,
+            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,
+    run: async (client, args) => ({
+        norm: args.norm,
+        path: args.path,
+        crossRefs: await client.action(api._mcp.getCrossRefs, {
+            apiKey: requireApiKey(),
+            code: args.norm,
+            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.',
+    inputSchema: {
+        norm,
+        figureId: z
+            .string()
+            .min(1)
+            .describe('Figure ID from get_section response (figures[].id).'),
+    },
+    annotations: readOnly,
+    run: async (client, args) => {
+        const apiKey = requireApiKey();
+        const meta = (await client.action(api._mcp.getFigureMeta, {
+            apiKey,
+            code: args.norm,
+            figureId: args.figureId,
+        }));
+        if (!meta)
+            return { error: 'Figure not found.' };
+        // 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-
+        // bypassing capability into the model context (and thus the provider's
+        // logs). The agent gets the image inline instead.
+        const url = (await client.action(api._mcp.getStorageUrl, {
+            apiKey,
+            code: args.norm,
+            figureId: args.figureId,
+        }));
+        if (!url)
+            return { error: 'Figure storage is unavailable.' };
+        const response = await fetch(url);
+        if (!response.ok) {
+            return { error: `Failed to download figure: HTTP ${response.status}` };
+        }
+        const buffer = await response.arrayBuffer();
+        return {
+            caption: meta.caption,
+            figureNumber: meta.figureNumber,
+            image: {
+                base64: Buffer.from(buffer).toString('base64'),
+                mimeType: response.headers.get('content-type') ?? 'image/png',
+            },
+        };
+    },
+    toContent: (result) => {
+        const r = result;
+        if (r.error || !r.image) {
+            return {
+                content: [{ type: 'text', text: r.error ?? 'Figure unavailable.' }],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                { type: 'image', data: r.image.base64, mimeType: r.image.mimeType },
+                { type: 'text', text: `${r.figureNumber} — ${r.caption}` },
+            ],
+        };
+    },
+});
+export const readTools = [
+    getMethodology,
+    listNorms,
+    getToc,
+    getSubtree,
+    getSection,
+    searchInNorm,
+    getCrossRefs,
+    getFigure,
+];

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@stratta/mcp",
   "mcpName": "io.github.hugogebel-boop/stratta",
-  "version": "0.5.0",
-  "description": "MCP server exposing Swiss engineering norms (SIA / Eurocodes) to Claude clients via Stratta TreeRAG.",
+  "version": "0.7.1",
+  "description": "MCP server exposing the engineering norms your firm is licensed for (SIA / Eurocodes) to any MCP client, via Stratta TreeRAG.",
   "license": "UNLICENSED",
-  "author": "Hugo Gebel <hugo.gebel@epfl.ch>",
+  "author": "SmartFlow <hello@stratta.ch>",
   "homepage": "https://stratta.ch",
   "repository": {
     "type": "git",
@@ -33,7 +33,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
     "test": "vitest run",
@@ -41,14 +41,14 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "convex": "^1.39.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "convex": "^1.42.3",
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.5.4",
-    "typescript": "^5.7.2",
-    "vitest": "^3.2.4"
+    "@types/node": "^26.1.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   },
   "engines": {
     "node": ">=20"

package/skills/ingest-norm/SKILL.md

@@ -1,128 +1,140 @@
----
-name: ingest-norm
-description: Use when the user wants to add an engineering norm (SIA, Eurocode, etc.) they are licensed for into THEIR Stratta workspace. A Python pre-pass (PyMuPDF) extracts the hierarchical tree and rasterizes figures; an agentic pass enriches sections (LaTeX formulas, tables, cross-references, summaries) and writes everything via the MCP `ingest_*` tools — scoped to the user's own organization. Trigger phrases: "ingère cette norme", "/ingest-norm", "ingest SIA", "ajoute la norme X à Stratta".
----
-
-# Ingest a norm into your Stratta workspace
-
-This skill turns a norm PDF **you are licensed to use** into a queryable
-TreeRAG inside **your own** Stratta workspace. A Python pre-pass (PyMuPDF)
-does the deterministic heavy lifting — TOC tree, per-section raw text, figure
-captions and full-page renders. Then an agentic pass enriches sections with
-summaries, LaTeX formulas, structured tables, and cross-references. Final
-writes go through the Stratta MCP `ingest_*` tools, scoped to your org.
-
-> ⚠️ **Licence**: only ingest norms your organization holds a valid licence
-> for. You are responsible for your usage rights (see Stratta's Terms).
-
-## Prerequisites
-- The Stratta MCP server is installed and your `STRATTA_API_KEY` resolves
-  (via env, `~/.stratta/config.json`, or first-call elicitation).
-- **Python ≥ 3.10 with PyMuPDF**. Install once:
-  `python -m pip install --user pymupdf` (or `uv pip install pymupdf`).
-- The norm PDF is available locally.
-
-## Tools used (all scoped to your workspace)
-`ingest_status` · `ingest_create_document` · `ingest_create_sections` ·
-`ingest_attach_formula` · `ingest_attach_table` · `ingest_attach_cross_ref` ·
-`ingest_upload_figure` · `ingest_normalize_cross_refs` · `ingest_publish` ·
-`ingest_delete`.
-
-## Workflow
-
-### 1. Locate the pre-pass script
-It ships inside this package at `scripts/ingest-prepass.py`. Resolve its path:
-```bash
-node -e "console.log(require.resolve('@stratta/mcp/package.json'))"
-# → <root>/package.json  →  <root>/scripts/ingest-prepass.py
-```
-If the user is working in the Stratta monorepo, the script also lives at
-`packages/mcp/scripts/ingest-prepass.py`.
-
-### 2. Check for an existing copy
-`ingest_status { code }` (e.g. `"SIA 261"`). To re-ingest, call
-`ingest_delete { documentId }` first.
-
-### 3. Run the pre-pass
-```bash
-python <pkg-root>/scripts/ingest-prepass.py \
-  --pdf <path-to-pdf> \
-  --output .stratta-ingest/<code-slug>
-```
-Output under `.stratta-ingest/<code-slug>/`:
-- `prepass.json` — full manifest (see below).
-- `figures/page-NNN.png` — one PNG per page that contains a `Figure N` caption.
-
-`prepass.json` structure:
-- `doc` — `pageCount`, detected `language`, `tocSource`, raw `metadata`.
-- `stats` — `sectionCount`, `byDepth`, `figureCount`.
-- `sections[]` — full hierarchical tree (depth **0 = chapter**, 1+ = sub-sections),
-  each with `nodeId`, `parentNodeId`, `path` (`"4.2.1"` or `"Annexe B"`),
-  `title`, `depth`, `pageStart`, `pageEnd`, `orderIndex`, `rawText` (concat
-  of the pages the node spans).
-- `figures[]` — one entry per `Figure N` caption: `figureNumber`, `caption`,
-  `page`, `fileName`, `mimeType`.
-
-The pre-pass is **exhaustive** (e.g. ~550 nodes on SIA 261). You decide what
-to keep in the next step.
-
-### 4. Create the document
-Read `prepass.json`, then:
-`ingest_create_document { code, year, title, language: <doc.language>, totalPages: <doc.pageCount> }`
-→ returns `documentId`. Keep it for every subsequent call.
-
-### 5. Decide section granularity + generate summaries
-Iterate `sections[]` and decide what to keep. Two viable strategies:
-- **Keep all** — most faithful, ~500 sections on a typical SIA norm. Great
-  for fine-grained navigation but verbose.
-- **Aggregate trivial leaves** — fold paragraph-level nodes (`6.1.1`...`6.1.11`)
-  into their parent (`6.1`), concatenating their `rawText`. Typical result:
-  100-150 sections. Recommended unless the user asks for max granularity.
-
-For each kept section, prepare:
-- `summary` — 1-3 sentences derived from `rawText` (mention formulas/values).
-- `content` — enriched text with LaTeX inline where the source has math
-  (e.g. `$\sigma_d = f_{yd} \cdot \gamma$`). Open the PDF visually for pages
-  that contain formulas or multi-column tables — PyMuPDF mangles those.
-- `rawContent` — use the pre-pass `rawText` as-is.
-
-Keep the `nodeId` / `parentNodeId` / `path` / `pageStart` / `pageEnd` /
-`orderIndex` / `depth` from the pre-pass — those are deterministic.
-
-### 6. Insert sections (batched)
-`ingest_create_sections { documentId, sections: [...] }` in batches of 30-50.
-Parent links resolve via `parentNodeId` within the batch and across prior
-batches. The call returns a `nodeId → sectionId` map — **use those `sectionId`s**
-for every enrichment call below.
-
-### 7. Enrich
-- `ingest_attach_formula { sectionId, latex, description, formulaNumber }`
-- `ingest_attach_table { sectionId, data: { headers, rows }, caption, tableNumber }`
-- `ingest_attach_cross_ref { sourceSectionId, targetDocumentCode, targetSectionPath?, refText, refType }`
-
-### 8. Upload figures
-For each figure in `prepass.json#figures`:
-- Read `.stratta-ingest/<code>/<fileName>` and base64-encode the bytes.
-- Find the owning section: the kept section whose `pageStart..pageEnd`
-  range includes the figure's `page`.
-- `ingest_upload_figure { sectionId, base64, mimeType: "image/png", caption, figureNumber }`
-  (≤ 8 MB per image).
-
-### 9. Auto cross-references (optional but recommended)
-`ingest_normalize_cross_refs { documentId }` scans every section's text for
-references to other norms (SIA / SN EN / EN / ISO / DIN …) and rebuilds the
-cross-ref index. Idempotent.
-
-### 10. Publish
-`ingest_publish { documentId }`. The norm is now queryable in your workspace
-via `list_norms`, `get_toc`, `get_section`, `search_in_norm`, `get_figure`, etc.
-
-## Quality bar
-- Trust the pre-pass for `path` + `pageStart`/`pageEnd` — it's deterministic
-  and verified against the PDF bookmarks.
-- Summaries drive navigation — be specific (mention key formulas/values).
-- Keep `content` faithful to the source; don't invent values.
-- If PyMuPDF mangled a formula (Greek letters, fractions, exponents broken),
-  re-read the relevant PDF page visually and write proper LaTeX.
-- Never skip annexes — they hold key numeric values (zones, coefficients,
-  characteristic loads).
+---
+name: ingest-norm
+description: Use when the user wants to add an engineering norm (SIA, Eurocode, etc.) they are licensed for into THEIR Stratta workspace. A Python pre-pass (PyMuPDF) extracts the hierarchical tree and rasterizes figures; an agentic pass enriches sections (LaTeX formulas, tables, cross-references, summaries) and writes everything via the MCP `ingest_*` tools — scoped to the user's own organization. Trigger phrases: "ingère cette norme", "/ingest-norm", "ingest SIA", "ajoute la norme X à Stratta".
+---
+
+# Ingest a norm into your Stratta workspace
+
+This skill turns a norm PDF **you are licensed to use** into a queryable
+TreeRAG inside **your own** Stratta workspace. A Python pre-pass (PyMuPDF)
+does the deterministic heavy lifting — TOC tree, per-section raw text, figure
+captions and full-page renders. Then an agentic pass enriches sections with
+summaries, LaTeX formulas, structured tables, and cross-references. Final
+writes go through the Stratta MCP `ingest_*` tools, scoped to your org.
+
+> ⚠️ **Licence**: only ingest norms your organization holds a valid licence
+> for. You are responsible for your usage rights (see Stratta's Terms).
+
+## Prerequisites
+- The Stratta MCP server is installed and your `STRATTA_API_KEY` resolves
+  (via env, `~/.stratta/config.json`, or first-call elicitation).
+- **Python ≥ 3.10 with PyMuPDF**. Install once:
+  `python -m pip install --user pymupdf` (or `uv pip install pymupdf`).
+- The norm PDF is available locally.
+
+## Tools used (all scoped to your workspace)
+`ingest_status` · `ingest_create_document` · `ingest_create_sections` ·
+`ingest_attach_formula` · `ingest_attach_table` · `ingest_attach_cross_ref` ·
+`ingest_upload_figure` · `ingest_normalize_cross_refs` · `ingest_publish` ·
+`ingest_delete`.
+
+## Quotas — read before you start
+The workspace has server-enforced limits on norms, sections and figures. A
+`QUOTA_EXCEEDED` error names the dimension, the current count and the limit.
+
+**Do not retry it.** The limit will not move on its own. Stop the ingestion,
+report the numbers to the user, and offer the two ways out: delete a norm that is
+no longer needed (`ingest_delete`), or raise the plan.
+
+Check the budget up front on a large norm: the pre-pass output tells you how many
+sections and figures you are about to write. Failing at step 8 of 10 leaves a
+half-ingested document behind, which the user then has to delete by hand.
+
+## Workflow
+
+### 1. Locate the pre-pass script
+It ships inside this package at `scripts/ingest-prepass.py`. Resolve its path:
+```bash
+node -e "console.log(require.resolve('@stratta/mcp/package.json'))"
+# → <root>/package.json  →  <root>/scripts/ingest-prepass.py
+```
+If the user is working in the Stratta monorepo, the script also lives at
+`packages/mcp/scripts/ingest-prepass.py`.
+
+### 2. Check for an existing copy
+`ingest_status { code }` (e.g. `"SIA 261"`). To re-ingest, call
+`ingest_delete { documentId }` first.
+
+### 3. Run the pre-pass
+```bash
+python <pkg-root>/scripts/ingest-prepass.py \
+  --pdf <path-to-pdf> \
+  --output .stratta-ingest/<code-slug>
+```
+Output under `.stratta-ingest/<code-slug>/`:
+- `prepass.json` — full manifest (see below).
+- `figures/page-NNN.png` — one PNG per page that contains a `Figure N` caption.
+
+`prepass.json` structure:
+- `doc` — `pageCount`, detected `language`, `tocSource`, raw `metadata`.
+- `stats` — `sectionCount`, `byDepth`, `figureCount`.
+- `sections[]` — full hierarchical tree (depth **0 = chapter**, 1+ = sub-sections),
+  each with `nodeId`, `parentNodeId`, `path` (`"4.2.1"` or `"Annexe B"`),
+  `title`, `depth`, `pageStart`, `pageEnd`, `orderIndex`, `rawText` (concat
+  of the pages the node spans).
+- `figures[]` — one entry per `Figure N` caption: `figureNumber`, `caption`,
+  `page`, `fileName`, `mimeType`.
+
+The pre-pass is **exhaustive** (e.g. ~550 nodes on SIA 261). You decide what
+to keep in the next step.
+
+### 4. Create the document
+Read `prepass.json`, then:
+`ingest_create_document { code, year, title, language: <doc.language>, totalPages: <doc.pageCount> }`
+→ returns `documentId`. Keep it for every subsequent call.
+
+### 5. Decide section granularity + generate summaries
+Iterate `sections[]` and decide what to keep. Two viable strategies:
+- **Keep all** — most faithful, ~500 sections on a typical SIA norm. Great
+  for fine-grained navigation but verbose.
+- **Aggregate trivial leaves** — fold paragraph-level nodes (`6.1.1`...`6.1.11`)
+  into their parent (`6.1`), concatenating their `rawText`. Typical result:
+  100-150 sections. Recommended unless the user asks for max granularity.
+
+For each kept section, prepare:
+- `summary` — 1-3 sentences derived from `rawText` (mention formulas/values).
+- `content` — enriched text with LaTeX inline where the source has math
+  (e.g. `$\sigma_d = f_{yd} \cdot \gamma$`). Open the PDF visually for pages
+  that contain formulas or multi-column tables — PyMuPDF mangles those.
+- `rawContent` — use the pre-pass `rawText` as-is.
+
+Keep the `nodeId` / `parentNodeId` / `path` / `pageStart` / `pageEnd` /
+`orderIndex` / `depth` from the pre-pass — those are deterministic.
+
+### 6. Insert sections (batched)
+`ingest_create_sections { documentId, sections: [...] }` in batches of 30-50.
+Parent links resolve via `parentNodeId` within the batch and across prior
+batches. The call returns a `nodeId → sectionId` map — **use those `sectionId`s**
+for every enrichment call below.
+
+### 7. Enrich
+- `ingest_attach_formula { sectionId, latex, description, formulaNumber }`
+- `ingest_attach_table { sectionId, data: { headers, rows }, caption, tableNumber }`
+- `ingest_attach_cross_ref { sourceSectionId, targetDocumentCode, targetSectionPath?, refText, refType }`
+
+### 8. Upload figures
+For each figure in `prepass.json#figures`:
+- Read `.stratta-ingest/<code>/<fileName>` and base64-encode the bytes.
+- Find the owning section: the kept section whose `pageStart..pageEnd`
+  range includes the figure's `page`.
+- `ingest_upload_figure { sectionId, base64, mimeType: "image/png", caption, figureNumber }`
+  (≤ 8 MB per image).
+
+### 9. Auto cross-references (optional but recommended)
+`ingest_normalize_cross_refs { documentId }` scans every section's text for
+references to other norms (SIA / SN EN / EN / ISO / DIN …) and rebuilds the
+cross-ref index. Idempotent.
+
+### 10. Publish
+`ingest_publish { documentId }`. The norm is now queryable in your workspace
+via `list_norms`, `get_toc`, `get_section`, `search_in_norm`, `get_figure`, etc.
+
+## Quality bar
+- Trust the pre-pass for `path` + `pageStart`/`pageEnd` — it's deterministic
+  and verified against the PDF bookmarks.
+- Summaries drive navigation — be specific (mention key formulas/values).
+- Keep `content` faithful to the source; don't invent values.
+- If PyMuPDF mangled a formula (Greek letters, fractions, exponents broken),
+  re-read the relevant PDF page visually and write proper LaTeX.
+- Never skip annexes — they hold key numeric values (zones, coefficients,
+  characteristic loads).

package/dist/tools/get-cross-refs.d.ts

@@ -1,24 +0,0 @@
-import type { ConvexHttpClient } from 'convex/browser';
-export declare const getCrossRefsTool: {
-    readonly name: "get_cross_refs";
-    readonly 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).";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly norm: {
-                readonly type: "string";
-                readonly description: "Norm code, e.g. \"SIA 261\".";
-            };
-            readonly path: {
-                readonly type: "string";
-                readonly description: "Section path, e.g. \"4.2.1\".";
-            };
-        };
-        readonly required: readonly ["norm", "path"];
-        readonly additionalProperties: false;
-    };
-};
-export declare function handleGetCrossRefs(client: ConvexHttpClient, args: {
-    norm: string;
-    path: string;
-}): Promise<unknown>;

package/dist/tools/get-cross-refs.js

@@ -1,23 +0,0 @@
-import { api } from '../client.js';
-import { requireApiKey } from '../auth.js';
-export const getCrossRefsTool = {
-    name: 'get_cross_refs',
-    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: {
-        type: 'object',
-        properties: {
-            norm: { type: 'string', description: 'Norm code, e.g. "SIA 261".' },
-            path: { type: 'string', description: 'Section path, e.g. "4.2.1".' },
-        },
-        required: ['norm', 'path'],
-        additionalProperties: false,
-    },
-};
-export async function handleGetCrossRefs(client, args) {
-    const result = await client.action(api._mcp.getCrossRefs, {
-        apiKey: requireApiKey(),
-        code: args.norm,
-        path: args.path,
-    });
-    return { norm: args.norm, path: args.path, crossRefs: result };
-}

package/dist/tools/get-figure.d.ts

@@ -1,24 +0,0 @@
-import type { ConvexHttpClient } from 'convex/browser';
-export declare const getFigureTool: {
-    readonly name: "get_figure";
-    readonly description: "Retrieve a figure (image) referenced in a section. Returns the image inline (base64) so you can see and reason about it, plus a public `url` for full-size viewing. Use the `id` returned by get_section in its `figures` array.";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly norm: {
-                readonly type: "string";
-                readonly description: "Norm code, e.g. \"SIA 261\".";
-            };
-            readonly figureId: {
-                readonly type: "string";
-                readonly description: "Figure ID from get_section response (figures[].id).";
-            };
-        };
-        readonly required: readonly ["norm", "figureId"];
-        readonly additionalProperties: false;
-    };
-};
-export declare function handleGetFigure(client: ConvexHttpClient, args: {
-    norm: string;
-    figureId: string;
-}): Promise<unknown>;