@stratta/mcp 0.7.1 → 0.9.0

package/README.md

@@ -1,3 +1,12 @@
+<!--
+Ownership marker for the official MCP registry. It must match `mcpName` in
+package.json exactly, and it must be present in the *published* tarball —
+the registry reads the README from npm, not from this repository. Without it
+`mcp-publisher publish` rejects the server as unverified.
+
+mcp-name: io.github.hugogebel-boop/stratta
+-->
+
 # @stratta/mcp
 
 MCP server exposing Swiss engineering norms (SIA / Eurocodes) to Claude clients via Stratta TreeRAG.
@@ -21,17 +30,22 @@ Add the server — no key needed up front:
 claude mcp add stratta -- npx -y @stratta/mcp
 ```
 
-On the first call, Claude Code prompts you to paste your Stratta API key. It's
-validated and saved to `~/.stratta/config.json` (owner-only, `0600`), so you
-only do this once.
-
-Prefer to set it up ahead of time? Log in via the CLI:
+Then sign in. This opens stratta.ch in your browser, where you confirm which
+machine and organisation to authorise; the key comes back to the terminal on
+its own and is saved to `~/.stratta/config.json` (owner-only, `0600`). You
+never see it, and you only do this once:
 
 ```bash
 npx -y @stratta/mcp login
 ```
 
-…or pass the key explicitly as an environment variable (it then takes
+No browser on this machine — remote server, SSH, CI? `login --paste` asks for a
+key from https://stratta.ch/api-keys instead, without echoing it.
+
+If you skip the step entirely, Claude Code prompts you for a key on the first
+tool call.
+
+You can also pass the key explicitly as an environment variable (it then takes
 precedence over the saved key):
 
 ```bash
@@ -40,7 +54,7 @@ claude mcp add stratta --scope user --env STRATTA_API_KEY=sk_strt_xxx -- npx -y
 
 ### Claude Desktop
 
-Save your key once via the CLI:
+Sign in once from a terminal — the desktop app cannot prompt you interactively:
 
 ```bash
 npx -y @stratta/mcp login
@@ -80,40 +94,40 @@ The API key is resolved in this order: the `STRATTA_API_KEY` env var, then
 `~/.stratta/config.json` (written by `login` or the first-run prompt). Other
 settings come from environment variables — see [`.env.example`](./.env.example).
 
-| Variable | Required | Default | Purpose |
-|---|---|---|---|
-| `STRATTA_API_KEY` | no¹ | – | API key from https://stratta.ch. ¹If unset, the server falls back to `~/.stratta/config.json`, or prompts you on first use (clients that support elicitation). |
-| `STRATTA_CONVEX_URL` | no | Stratta prod backend | Override only if you self-host. |
+| Variable             | Required | Default              | Purpose                                                                                                                                                        |
+| -------------------- | -------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STRATTA_API_KEY`    | no¹      | –                    | API key from https://stratta.ch. ¹If unset, the server falls back to `~/.stratta/config.json`, or prompts you on first use (clients that support elicitation). |
+| `STRATTA_CONVEX_URL` | no       | Stratta prod backend | Override only if you self-host.                                                                                                                                |
 
 ## Tools exposed
 
 **Read** (8 tools — query norms in your workspace):
 
-| Tool | Purpose |
-|---|---|
+| Tool              | Purpose                                                                                |
+| ----------------- | -------------------------------------------------------------------------------------- |
 | `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. |
+| `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. |
+| 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
 
@@ -162,13 +176,13 @@ Requires Python ≥ 3.10 with PyMuPDF (`python -m pip install --user pymupdf`).
 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 |
+| 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

package/dist/errors.js

@@ -11,6 +11,34 @@ function humanDuration(ms) {
     const hours = Math.ceil(ms / 3_600_000);
     return `${hours} heure${hours > 1 ? 's' : ''}`;
 }
+const DOCS = 'https://stratta.ch/docs/fr';
+/**
+ * Where an agent should read next, per failure.
+ *
+ * A message that only states what went wrong leaves the agent guessing at the
+ * fix; one that carries an address lets it read the page and recover on its
+ * own. Anchors are kept ASCII so the URL survives being copied into a terminal
+ * or a chat client that mangles percent-encoding.
+ */
+const HELP = {
+    QUOTA_EXCEEDED: `${DOCS}/account/plans#quand-une-limite-est-atteinte`,
+    UNAUTHORIZED: `${DOCS}/guides/get-api-key`,
+    NO_ORGANIZATION: `${DOCS}/guides/manage-organization`,
+    DOCUMENT_NOT_FOUND: `${DOCS}/guides/ingest-a-norm`,
+    SECTION_NOT_FOUND: `${DOCS}/mcp/read-tools`,
+    INSUFFICIENT_ROLE: `${DOCS}/guides/manage-organization`,
+    RATE_LIMITED: `${DOCS}/resources/troubleshooting`,
+    DOSSIER_NOT_FOUND: `${DOCS}/mcp/dossier-tools`,
+    DOSSIER_CLOSED: `${DOCS}/guides/suivre-un-projet`,
+    ENTRY_NOT_FOUND: `${DOCS}/mcp/dossier-tools`,
+    TOO_MANY_DOSSIERS: `${DOCS}/mcp/dossier-tools`,
+    TOO_MANY_ENTRIES: `${DOCS}/mcp/dossier-tools`,
+    TOO_MANY_COMMENTS: `${DOCS}/mcp/dossier-tools`,
+};
+function withHelp(code, lines) {
+    const url = HELP[code];
+    return (url ? [...lines, `Détails : ${url}`] : lines).join('\n');
+}
 /**
  * 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
@@ -29,22 +57,69 @@ export function formatToolError(err) {
                 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');
+            return withHelp('QUOTA_EXCEEDED', lines);
         }
         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.';
+                    return withHelp(data, [
+                        '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.";
+                    return withHelp(data, [
+                        "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.";
+                    return withHelp(data, [
+                        "Cette norme n'existe pas dans votre organisation, ou elle appartient à une autre.",
+                        'Appelez `list_norms` pour voir ce qui est disponible avant de réessayer.',
+                    ]);
                 case 'SECTION_NOT_FOUND':
-                    return "Cette section n'existe pas dans votre organisation.";
+                    return withHelp(data, [
+                        "Cette section n'existe pas dans votre organisation.",
+                        'Appelez `get_toc` sur la norme pour lire les chemins de section réels.',
+                    ]);
                 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).";
+                    return withHelp(data, [
+                        "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.';
+                    return withHelp(data, [
+                        'Trop de tentatives en peu de temps. Patientez une minute avant de réessayer.',
+                    ]);
+                case 'DOSSIER_NOT_FOUND':
+                    return withHelp(data, [
+                        "Ce dossier n'existe pas dans votre organisation.",
+                        'Appelez `list_dossiers` pour voir les dossiers disponibles, ou `open_dossier` pour en créer un.',
+                    ]);
+                case 'DOSSIER_CLOSED':
+                    return withHelp(data, [
+                        'Ce dossier est visé : ses entrées ne peuvent plus être modifiées.',
+                        "Ne réessayez pas. Dites à l'utilisateur de le repasser « en cours » sur stratta.ch/dossiers s'il veut le reprendre. Les commentaires, eux, restent possibles.",
+                    ]);
+                case 'ENTRY_NOT_FOUND':
+                    return withHelp(data, [
+                        "Cette entrée n'existe pas, ou elle appartient à un autre dossier.",
+                        'Rechargez le dossier avec `load_dossier` pour obtenir des identifiants à jour.',
+                    ]);
+                case 'TOO_MANY_DOSSIERS':
+                    return withHelp(data, [
+                        'Cette organisation a atteint son plafond de dossiers.',
+                        "Ne réessayez pas. Écrivez plutôt dans un dossier existant, ou dites à l'utilisateur d'en supprimer un.",
+                    ]);
+                case 'TOO_MANY_ENTRIES':
+                    return withHelp(data, [
+                        'Ce dossier a atteint son plafond d’entrées.',
+                        "Ne réessayez pas. Un dossier aussi rempli est le signe qu'on y consigne trop : ouvrez-en un second pour la phase en cours.",
+                    ]);
+                case 'TOO_MANY_COMMENTS':
+                    return withHelp(data, [
+                        'Ce dossier a atteint son plafond de commentaires. Ne réessayez pas.',
+                    ]);
+                case 'ACCOUNT_SUSPENDED':
+                    return withHelp(data, [
+                        'Ce compte est suspendu. Ne réessayez pas ; contactez hello@stratta.ch.',
+                    ]);
                 default:
                     return data;
             }

package/dist/index.js

@@ -10,6 +10,7 @@ import { ensureAuthenticated, resolveApiKey } from './auth.js';
 import { elicitApiKey } from './elicit.js';
 import { readTools } from './tools/read.js';
 import { ingestTools } from './tools/ingest.js';
+import { dossierTools } from './tools/dossier.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
@@ -80,7 +81,7 @@ async function call(def, args) {
         };
     }
 }
-for (const def of [...readTools, ...ingestTools]) {
+for (const def of [...readTools, ...dossierTools, ...ingestTools]) {
     server.registerTool(def.name, {
         title: def.title,
         description: def.description,
@@ -94,7 +95,7 @@ for (const def of [...readTools, ...ingestTools]) {
 async function main() {
     if (process.argv[2] === 'login') {
         const { runLogin } = await import('./login.js');
-        await runLogin();
+        await runLogin(process.argv.slice(3));
         return;
     }
     await server.connect(new StdioServerTransport());

package/dist/login.d.ts

@@ -1 +1 @@
-export declare function runLogin(): Promise<void>;
+export declare function runLogin(argv?: Array<string>): Promise<void>;

package/dist/login.js

@@ -1,6 +1,13 @@
 import { createInterface } from 'node:readline';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { hostname } from 'node:os';
+import { randomBytes } from 'node:crypto';
 import { createConvexClient, api } from './client.js';
 import { writeStoredApiKey, CONFIG_PATH } from './config.js';
+const SITE_URL = process.env.STRATTA_SITE_URL ?? 'https://stratta.ch';
+/** How long the loopback server waits before giving up on the browser. */
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 // Prompt for a secret on the TTY without echoing it back.
 function promptSecret(query) {
     return new Promise((resolve) => {
@@ -19,22 +26,159 @@ function promptSecret(query) {
         muted = true;
     });
 }
-export async function runLogin() {
-    const apiKey = await promptSecret('Paste your Stratta API key (from https://stratta.ch): ');
-    if (!apiKey) {
-        console.error('No key entered. Aborting.');
-        process.exitCode = 1;
-        return;
+/**
+ * Open a URL in the user's default browser, best effort.
+ *
+ * Deliberately not a dependency: the three platform commands are three lines,
+ * and a login flow should not pull an install-time package into a server that
+ * otherwise has none. Failure is expected and survivable — headless boxes and
+ * SSH sessions have no browser, so the caller always prints the URL too.
+ */
+function openBrowser(url) {
+    const [cmd, args] = process.platform === 'win32'
+        ? // `start` is a cmd builtin, not an executable, and it treats the first
+            // quoted argument as a window title — hence the empty one.
+            ['cmd', ['/c', 'start', '', url]]
+        : process.platform === 'darwin'
+            ? ['open', [url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => { });
+        child.unref();
     }
+    catch {
+        // Printed URL is the fallback.
+    }
+}
+function page(title, body) {
+    return `<!doctype html><html lang="fr"><meta charset="utf-8">
+<title>${title}</title>
+<style>
+  body{font:16px/1.6 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;
+       background:#12110f;color:#f5f1e8;display:grid;place-items:center;
+       min-height:100vh;margin:0;padding:2rem;text-align:center}
+  .c{max-width:26rem} h1{font-size:1.25rem;margin:0 0 .5rem}
+  p{margin:0;color:#a8a196}
+</style>
+<div class="c"><h1>${title}</h1><p>${body}</p></div>`;
+}
+/**
+ * Receive the key on 127.0.0.1 after the user approves in the browser.
+ *
+ * The loopback redirect is the same shape `firebase login` and `vercel login`
+ * use, and it is chosen over a device code for one reason: no server-side
+ * state. Nothing to store, expire, or poll — the page hands the key to a port
+ * that only this process is listening on.
+ *
+ * Two things keep that port honest. It binds to `127.0.0.1` explicitly, never
+ * `0.0.0.0`, so nothing off-machine can reach it. And it rejects any callback
+ * whose `state` does not match the one just generated, so another local
+ * process that guesses the port cannot feed us a key of its choosing.
+ */
+function awaitCallback(state, onPort) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            server.close();
+            resolve(result);
+        };
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            if (url.pathname !== '/callback') {
+                res.writeHead(404).end();
+                return;
+            }
+            const reply = (status, title, body) => {
+                res.writeHead(status, { 'content-type': 'text/html; charset=utf-8' });
+                res.end(page(title, body));
+            };
+            if (url.searchParams.get('state') !== state) {
+                reply(400, 'Requête refusée', 'Le jeton de session ne correspond pas. Relancez la commande de connexion.');
+                // Not fatal: keep listening. A mismatched callback is either a stale
+                // tab from a previous attempt or something we should ignore, and
+                // neither should cancel the login the user is in the middle of.
+                return;
+            }
+            // The page reports a refusal rather than closing the tab and leaving the
+            // terminal to sit through the five-minute timeout. A user who clicks
+            // "Refuser" gets their prompt back immediately, which is the whole point
+            // of offering the button.
+            const denied = url.searchParams.get('error');
+            if (denied) {
+                reply(200, 'Autorisation refusée', 'Aucune clé n’a été créée. Vous pouvez fermer cet onglet.');
+                finish({ error: 'refusée depuis le navigateur' });
+                return;
+            }
+            const key = url.searchParams.get('key');
+            if (!key) {
+                reply(400, 'Clé manquante', 'La page n’a transmis aucune clé.');
+                finish({ error: 'callback sans clé' });
+                return;
+            }
+            reply(200, 'Stratta est connecté', 'Vous pouvez fermer cet onglet et retourner à votre terminal.');
+            finish({ key });
+        });
+        const timer = setTimeout(() => finish({ error: 'délai dépassé' }), LOGIN_TIMEOUT_MS);
+        // `unref` so a forgotten timer never keeps the process alive on its own.
+        timer.unref?.();
+        server.on('error', (err) => finish({ error: err.message ?? 'port indisponible' }));
+        // Port 0 asks the OS for any free port, which avoids both a collision with
+        // a real service and a fixed port an attacker could camp on in advance.
+        server.listen(0, '127.0.0.1', () => {
+            onPort(server.address().port);
+        });
+    });
+}
+async function saveValidated(apiKey) {
     const client = createConvexClient();
     const res = (await client.action(api.apiKeys.validateApiKey, {
         plaintext: apiKey,
     }));
     if (!res?.valid) {
-        console.error('That API key is invalid. Generate a new one at https://stratta.ch and try again.');
-        process.exitCode = 1;
-        return;
+        console.error('That API key is invalid. Generate a new one at https://stratta.ch/api-keys and try again.');
+        return false;
     }
     writeStoredApiKey(apiKey);
     console.log(`Saved. Stratta MCP will use this key (stored at ${CONFIG_PATH}).`);
+    return true;
+}
+/** The old flow, kept behind `--paste` for CI and headless machines. */
+async function loginByPaste() {
+    const apiKey = await promptSecret('Paste your Stratta API key (from https://stratta.ch/api-keys): ');
+    if (!apiKey) {
+        console.error('No key entered. Aborting.');
+        process.exitCode = 1;
+        return;
+    }
+    if (!(await saveValidated(apiKey)))
+        process.exitCode = 1;
+}
+async function loginByBrowser() {
+    const state = randomBytes(24).toString('base64url');
+    // Named after the machine so the key is recognisable in the dashboard a year
+    // from now, when the question is which laptop to revoke.
+    const label = `CLI ${hostname()}`.slice(0, 60);
+    const result = await awaitCallback(state, (port) => {
+        const url = `${SITE_URL}/cli-auth?port=${port}&state=${state}&label=${encodeURIComponent(label)}`;
+        console.log('Opening your browser to authorise this machine…');
+        console.log(`If it does not open, visit:\n\n  ${url}\n`);
+        openBrowser(url);
+    });
+    if ('error' in result) {
+        console.error(`Browser login did not complete (${result.error}).\nRun \`npx @stratta/mcp login --paste\` to enter a key by hand instead.`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!(await saveValidated(result.key)))
+        process.exitCode = 1;
+}
+export async function runLogin(argv = []) {
+    if (argv.includes('--paste'))
+        return loginByPaste();
+    return loginByBrowser();
 }

package/dist/tools/dossier.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+export declare const listDossiers: import("./define.js").ToolDef<{}>;
+export declare const openDossier: import("./define.js").ToolDef<{
+    name: z.ZodString;
+    reference: z.ZodOptional<z.ZodString>;
+}>;
+export declare const saveFinding: import("./define.js").ToolDef<{
+    dossierId: z.ZodString;
+    kind: z.ZodEnum<{
+        reference: "reference";
+        hypothesis: "hypothesis";
+        observation: "observation";
+        question: "question";
+    }>;
+    title: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodOptional<z.ZodEnum<{
+        established: "established";
+        judgement: "judgement";
+        to_confirm: "to_confirm";
+    }>>;
+    normCode: z.ZodOptional<z.ZodString>;
+    sectionPath: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+}>;
+export declare const loadDossier: import("./define.js").ToolDef<{
+    dossierId: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}>;
+export declare const resolveQuestion: import("./define.js").ToolDef<{
+    entryId: z.ZodString;
+    resolved: z.ZodOptional<z.ZodBoolean>;
+}>;
+export declare const dossierTools: (import("./define.js").ToolDef<{}> | import("./define.js").ToolDef<{
+    name: z.ZodString;
+    reference: z.ZodOptional<z.ZodString>;
+}> | import("./define.js").ToolDef<{
+    dossierId: z.ZodString;
+    kind: z.ZodEnum<{
+        reference: "reference";
+        hypothesis: "hypothesis";
+        observation: "observation";
+        question: "question";
+    }>;
+    title: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodOptional<z.ZodEnum<{
+        established: "established";
+        judgement: "judgement";
+        to_confirm: "to_confirm";
+    }>>;
+    normCode: z.ZodOptional<z.ZodString>;
+    sectionPath: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+}> | import("./define.js").ToolDef<{
+    dossierId: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}> | import("./define.js").ToolDef<{
+    entryId: z.ZodString;
+    resolved: z.ZodOptional<z.ZodBoolean>;
+}>)[];

package/dist/tools/dossier.js

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+import { api } from '../client.js';
+import { requireApiKey } from '../auth.js';
+import { defineTool } from './define.js';
+/**
+ * The five dossier tools: how the work survives the conversation.
+ *
+ * Everything else here reads a norm. These write down what was decided with
+ * it, so the next conversation starts where the last one stopped and a human
+ * can review it in the app.
+ *
+ * The descriptions carry more instruction than the read tools do, on purpose.
+ * An agent left to guess will either record nothing — and the feature is dead
+ * — or record every sentence it produces, which buries the three decisions
+ * that mattered. `get_methodology` tells it when to open a dossier; these tell
+ * it what is worth putting in one.
+ */
+const write = { readOnlyHint: false, openWorldHint: false };
+const readOnly = { readOnlyHint: true, openWorldHint: false };
+const dossierId = z
+    .string()
+    .min(1)
+    .describe('Dossier id returned by open_dossier or list_dossiers.');
+export const listDossiers = defineTool({
+    name: 'list_dossiers',
+    title: 'List dossiers',
+    description: 'List the dossiers of YOUR organisation, most recently touched first. A dossier is a project record: what was decided, what it rests on, and what is still open. Call this when the user mentions a project by name, or asks what they were working on. Each row carries the count of entries and of UNRESOLVED questions — a dossier with open questions is the one to resume.',
+    inputSchema: {},
+    annotations: readOnly,
+    run: async (client) => ({
+        dossiers: await client.action(api.dossiersApi.listDossiers, {
+            apiKey: requireApiKey(),
+        }),
+    }),
+});
+export const openDossier = defineTool({
+    name: 'open_dossier',
+    title: 'Open a dossier',
+    description: "Open the dossier for a project, creating it if it does not exist yet. IDEMPOTENT on the name: calling it twice with the same name returns the same dossier rather than splitting a project's history in two. Call this when the user starts working on a named project and there is something worth keeping — a retained value, an assumption, a site observation, an unanswered question. Do not open one for a passing lookup. Returns { dossierId, created }.",
+    inputSchema: {
+        name: z
+            .string()
+            .min(1)
+            .max(120)
+            .describe('How the user refers to the project, e.g. "Villa Morges — toiture". Reuse their words: this is the name they will search for.'),
+        reference: z
+            .string()
+            .max(60)
+            .optional()
+            .describe("The bureau's own project number, if the user gave one."),
+    },
+    annotations: { ...write, idempotentHint: true },
+    run: (client, args) => client.action(api.dossiersApi.openDossier, {
+        apiKey: requireApiKey(),
+        name: args.name,
+        reference: args.reference,
+    }),
+});
+export const saveFinding = defineTool({
+    name: 'save_finding',
+    title: 'Save a finding to a dossier',
+    description: `Record ONE decision in a dossier. Call it as you work, not in a batch at the end — a finding saved when it is made carries the reasoning that produced it.
+
+WHAT TO RECORD, by kind:
+- reference: what a norm says, that the project relies on. ALWAYS fill normCode + sectionPath (+ page). If you cannot cite it, it is not a reference.
+- hypothesis: a value the engineer RETAINS, and why. This is the one that matters most in geotechnics, where a retained value is a judgement between disagreeing measurements rather than the output of a formula. Put the number in \`value\` and the reasoning in \`detail\`.
+- observation: what the site, a borehole, or a survey showed. Include the date in \`detail\` when known.
+- question: something not settled. These surface FIRST when the dossier is reloaded, so record them even when you cannot answer — especially then.
+
+WHAT NOT TO RECORD: your own prose, intermediate steps, anything the user did not treat as a decision. A dossier of forty entries where three mattered is worse than a dossier of three.
+
+Set \`confidence\` whenever the entry is a value: established (computed or read directly), judgement (the engineer chose it), to_confirm (provisional, needs a test or a check). Confusing those three is the professional fault this field exists to prevent.`,
+    inputSchema: {
+        dossierId,
+        kind: z
+            .enum(['reference', 'hypothesis', 'observation', 'question'])
+            .describe('See the tool description: pick by what the entry IS.'),
+        title: z
+            .string()
+            .min(1)
+            .max(200)
+            .describe('The decision in one line, as an engineer would write it in a report.'),
+        detail: z
+            .string()
+            .max(4000)
+            .optional()
+            .describe('The reasoning: why this value, what it rests on, what disagreed. Required in practice for a hypothesis — without it the entry cannot be reviewed.'),
+        value: z
+            .string()
+            .max(120)
+            .optional()
+            .describe('The retained value WITH its unit, e.g. "30°", "1,25 kN/m²".'),
+        confidence: z
+            .enum(['established', 'judgement', 'to_confirm'])
+            .optional()
+            .describe('How firm the value is. See the tool description.'),
+        normCode: z
+            .string()
+            .max(40)
+            .optional()
+            .describe('Norm this comes from, e.g. "SIA 261".'),
+        sectionPath: z
+            .string()
+            .max(60)
+            .optional()
+            .describe('Exact section path, e.g. "14.2".'),
+        page: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('Page in the norm, so a human can verify it in their PDF.'),
+    },
+    annotations: write,
+    run: (client, args) => client.action(api.dossiersApi.saveFinding, {
+        apiKey: requireApiKey(),
+        ...args,
+    }),
+});
+export const loadDossier = defineTool({
+    name: 'load_dossier',
+    title: 'Load a dossier',
+    description: 'Reload everything a dossier holds: retained values, what they rest on, site observations, open questions and the comments a colleague left. UNRESOLVED QUESTIONS COME FIRST — read them before anything else and tell the user what is still open. Call this whenever the user returns to a project ("reprends le dossier X", "on en était où sur Y") BEFORE answering anything about it, so you build on what was decided instead of deciding it again. Accepts either the id or the name the user uses.',
+    inputSchema: {
+        dossierId: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('Preferred when you have it.'),
+        name: z
+            .string()
+            .min(1)
+            .max(120)
+            .optional()
+            .describe('The project name, when the user names it rather than giving an id. Matched exactly; call list_dossiers first if unsure.'),
+    },
+    annotations: readOnly,
+    run: (client, args) => client.action(api.dossiersApi.loadDossier, {
+        apiKey: requireApiKey(),
+        dossierId: args.dossierId,
+        name: args.name,
+    }),
+});
+export const resolveQuestion = defineTool({
+    name: 'resolve_question',
+    title: 'Close an open question',
+    description: 'Mark a question entry as settled, once it actually is. The entry stays in the dossier — the trail of what was once uncertain is part of the record — but it stops surfacing at the top on reload. Only call this when the user has confirmed the answer, never on your own reasoning.',
+    inputSchema: {
+        entryId: z
+            .string()
+            .min(1)
+            .describe('Entry id of the question, from load_dossier.'),
+        resolved: z
+            .boolean()
+            .optional()
+            .describe('Defaults to true. Pass false to reopen a question.'),
+    },
+    annotations: { ...write, idempotentHint: true },
+    run: async (client, args) => {
+        await client.action(api.dossiersApi.resolveQuestion, {
+            apiKey: requireApiKey(),
+            entryId: args.entryId,
+            resolved: args.resolved,
+        });
+        return { ok: true };
+    },
+});
+export const dossierTools = [
+    listDossiers,
+    openDossier,
+    saveFinding,
+    loadDossier,
+    resolveQuestion,
+];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stratta/mcp",
   "mcpName": "io.github.hugogebel-boop/stratta",
-  "version": "0.7.1",
+  "version": "0.9.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>",