@stratta/mcp 0.9.8 → 0.10.0

package/README.md

@@ -167,15 +167,17 @@ settings come from environment variables — see [`.env.example`](./.env.example
 | `get_figure`      | Retrieve a figure inline (base64 ImageContent) + public URL.                           |
 | `get_cross_refs`  | Outgoing cross-refs from a section to other norms.                                     |
 
-**Dossier** (5 tools — keep what was decided on a project):
-
-| Tool               | Purpose                                                                                           |
-| ------------------ | ------------------------------------------------------------------------------------------------- |
-| `list_dossiers`    | Your organisation's dossiers, most recently touched first, with open counts.                      |
-| `open_dossier`     | Open a project's dossier, creating it if needed. Idempotent on the name.                          |
-| `save_finding`     | Record one decision: a cited article, a retained value and why, an observation, an open question. |
-| `load_dossier`     | Reload everything, unresolved questions first. Accepts the id or the name.                        |
-| `resolve_question` | Mark a question settled. The entry stays; it stops surfacing at the top.                          |
+**Dossier** (7 tools — keep what was decided on a project):
+
+| Tool               | Purpose                                                                                  |
+| ------------------ | ---------------------------------------------------------------------------------------- |
+| `list_dossiers`    | Your organisation's dossiers, most recently touched first, with open-question counts.    |
+| `open_dossier`     | Open a project's dossier, creating it if needed. Idempotent on the name.                 |
+| `open_question`    | Open one question to settle, with optional named options. Idempotent on the title.       |
+| `save_finding`     | Record one piece of evidence: a cited article, a retained value and why, an observation. |
+| `record_decision`  | Settle a question with a decision the engineer has confirmed, and the retained option.   |
+| `load_dossier`     | Reload everything: questions with their evidence and decisions, open ones first.         |
+| `resolve_question` | Close a question without a decision, or reopen one. The evidence stays.                  |
 
 A dossier is read, annotated, reviewed and exported from
 [stratta.ch/dossiers](https://stratta.ch/dossiers).

package/dist/tools/dossier.d.ts

@@ -4,14 +4,34 @@ export declare const openDossier: import("./define.js").ToolDef<{
     name: z.ZodString;
     reference: z.ZodOptional<z.ZodString>;
 }>;
+export declare const openQuestion: import("./define.js").ToolDef<{
+    dossierId: z.ZodString;
+    title: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}>;
 export declare const saveFinding: import("./define.js").ToolDef<{
+    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>;
+    normEdition: z.ZodOptional<z.ZodString>;
     dossierId: z.ZodString;
+    questionId: z.ZodOptional<z.ZodString>;
     kind: z.ZodEnum<{
         reference: "reference";
         hypothesis: "hypothesis";
         observation: "observation";
-        question: "question";
     }>;
+}>;
+export declare const recordDecision: import("./define.js").ToolDef<{
     title: z.ZodString;
     detail: z.ZodOptional<z.ZodString>;
     value: z.ZodOptional<z.ZodString>;
@@ -23,13 +43,16 @@ export declare const saveFinding: import("./define.js").ToolDef<{
     normCode: z.ZodOptional<z.ZodString>;
     sectionPath: z.ZodOptional<z.ZodString>;
     page: z.ZodOptional<z.ZodNumber>;
+    normEdition: z.ZodOptional<z.ZodString>;
+    questionId: z.ZodString;
+    retainedOption: z.ZodOptional<z.ZodString>;
 }>;
 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;
+    questionId: z.ZodString;
     resolved: z.ZodOptional<z.ZodBoolean>;
 }>;
 export declare const dossierTools: (import("./define.js").ToolDef<{}> | import("./define.js").ToolDef<{
@@ -37,12 +60,30 @@ export declare const dossierTools: (import("./define.js").ToolDef<{}> | import("
     reference: z.ZodOptional<z.ZodString>;
 }> | import("./define.js").ToolDef<{
     dossierId: z.ZodString;
+    title: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}> | import("./define.js").ToolDef<{
+    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>;
+    normEdition: z.ZodOptional<z.ZodString>;
+    dossierId: z.ZodString;
+    questionId: z.ZodOptional<z.ZodString>;
     kind: z.ZodEnum<{
         reference: "reference";
         hypothesis: "hypothesis";
         observation: "observation";
-        question: "question";
     }>;
+}> | import("./define.js").ToolDef<{
     title: z.ZodString;
     detail: z.ZodOptional<z.ZodString>;
     value: z.ZodOptional<z.ZodString>;
@@ -54,10 +95,13 @@ export declare const dossierTools: (import("./define.js").ToolDef<{}> | import("
     normCode: z.ZodOptional<z.ZodString>;
     sectionPath: z.ZodOptional<z.ZodString>;
     page: z.ZodOptional<z.ZodNumber>;
+    normEdition: z.ZodOptional<z.ZodString>;
+    questionId: z.ZodString;
+    retainedOption: z.ZodOptional<z.ZodString>;
 }> | import("./define.js").ToolDef<{
     dossierId: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
 }> | import("./define.js").ToolDef<{
-    entryId: z.ZodString;
+    questionId: z.ZodString;
     resolved: z.ZodOptional<z.ZodBoolean>;
 }>)[];

package/dist/tools/dossier.js

@@ -3,17 +3,24 @@ 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.
+ * The seven 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.
  *
+ * A dossier is a set of QUESTIONS. Each question holds the evidence gathered
+ * for it, the options on the table and, once the engineer has confirmed it, a
+ * decision. The question is the unit of work: it is what gets assigned,
+ * reviewed and closed. The first model was a flat journal, and the one real
+ * dossier it produced held a single "question" with eight sub-questions in its
+ * body — unassignable, unanswerable one at a time, unreadable.
+ *
  * 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.
+ * it what is worth putting in one, and in what shape.
  */
 const write = { readOnlyHint: false, openWorldHint: false };
 const readOnly = { readOnlyHint: true, openWorldHint: false };
@@ -21,10 +28,57 @@ const dossierId = z
     .string()
     .min(1)
     .describe('Dossier id returned by open_dossier or list_dossiers.');
+const questionId = z
+    .string()
+    .min(1)
+    .describe('Question id returned by open_question or load_dossier.');
+/** The fields a piece of evidence or a decision carries. */
+const entryFields = {
+    title: z
+        .string()
+        .min(1)
+        .max(200)
+        .describe('The fact in one line, as an engineer would write it in a report. One clause, one value or one observation; not a theme.'),
+    detail: z
+        .string()
+        .max(4000)
+        .optional()
+        .describe('The reasoning, in one or two sentences: why this value, what it rests on, what disagreed. Required in practice for a hypothesis.'),
+    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 267".'),
+    sectionPath: z
+        .string()
+        .max(60)
+        .optional()
+        .describe('Exact section path, e.g. "9.5.2.1".'),
+    page: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Page in the norm, so a human can verify it in their PDF.'),
+    normEdition: z
+        .string()
+        .max(40)
+        .optional()
+        .describe('The edition cited, e.g. "2013" or "2020 + rect. 2022", when list_norms gives it.'),
+};
 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.',
+    description: 'List the dossiers of YOUR organisation, most recently touched first. A dossier is a project record: the questions to settle, what was decided, what it rests on. 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 OPEN questions — a dossier with open questions is the one to resume.',
     inputSchema: {},
     annotations: readOnly,
     run: async (client) => ({
@@ -36,7 +90,7 @@ export const listDossiers = defineTool({
 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 }.",
+    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 question to settle, a retained value, an assumption, a site observation. Do not open one for a passing lookup. Returns { dossierId, created }.",
     inputSchema: {
         name: z
             .string()
@@ -56,63 +110,89 @@ export const openDossier = defineTool({
         reference: args.reference,
     }),
 });
+export const openQuestion = defineTool({
+    name: 'open_question',
+    title: 'Open a question',
+    description: `Open ONE question to settle in a dossier, BEFORE gathering evidence for it. A question is the unit of work: "Can pile P38 be kept?", "Which φ'k do we retain for the fill?", "Is kinematic interaction to be checked?". Evidence saved with save_finding and the eventual record_decision hang off it.
+
+ONE QUESTION PER THING TO SETTLE. Never put a list of sub-questions in the body: a question that bundles eight cannot be assigned, answered or closed one at a time. Open eight questions.
+
+IDEMPOTENT on the title: reopening the same wording returns the question already open, with its evidence. Name the options on the table in \`options\` when the user or the norm puts several forward ("abandon the pile", "recover it by re-concreting plus integrity tests", "redistribute onto P37/P39"). Returns { questionId, created }.`,
+    inputSchema: {
+        dossierId,
+        title: z
+            .string()
+            .min(1)
+            .max(200)
+            .describe('The question in one line, phrased as a question.'),
+        body: z
+            .string()
+            .max(4000)
+            .optional()
+            .describe('What is at stake and why it is not settled, in two or three sentences. Not a list of sub-questions.'),
+        options: z
+            .array(z.string().min(1).max(120))
+            .max(10)
+            .optional()
+            .describe('The ways this could be settled, one short name each.'),
+    },
+    annotations: { ...write, idempotentHint: true },
+    run: (client, args) => client.action(api.dossiersApi.openQuestion, {
+        apiKey: requireApiKey(),
+        dossierId: args.dossierId,
+        title: args.title,
+        body: args.body,
+        options: args.options,
+    }),
+});
 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.
+    title: 'Record evidence in a dossier',
+    description: `Record ONE piece of evidence 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.
+KEEP IT SHORT: one clause, one value or one fact per call, in one or two sentences. Three short entries beat one paragraph that mixes the citation, the reasoning and the consequence. A question is NOT recorded here: call open_question. A decision is NOT recorded here: call record_decision.
+
+FILE IT: pass \`questionId\` so the entry lands under the question it serves. If you do not yet know which question it serves, save it anyway without one — the engineer files it later.
 
 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,
+        questionId: questionId
+            .optional()
+            .describe('The question this evidence serves, from open_question or load_dossier. Omit only when you do not know yet.'),
         kind: z
-            .enum(['reference', 'hypothesis', 'observation', 'question'])
+            .enum(['reference', 'hypothesis', 'observation'])
             .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
+        ...entryFields,
+    },
+    annotations: write,
+    run: (client, args) => client.action(api.dossiersApi.saveFinding, {
+        apiKey: requireApiKey(),
+        ...args,
+    }),
+});
+export const recordDecision = defineTool({
+    name: 'record_decision',
+    title: 'Record a decision',
+    description: `Settle a question with a decision the engineer has CONFIRMED: what was decided, why, and the clause it rests on. The question leaves the open items and keeps its evidence; the decision becomes the entry a reviewer reads first.
+
+Only call this once the user has confirmed the decision, never on your own reasoning. Name the retained option in \`retainedOption\` when the question listed some (the name as it was given; an option not listed yet is created). Put the number in \`value\` when the decision is a value, and set \`confidence\`. Returns { entryId }.`,
+    inputSchema: {
+        questionId,
+        retainedOption: 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.'),
+            .describe('The option that was retained, by name.'),
+        ...entryFields,
     },
     annotations: write,
-    run: (client, args) => client.action(api.dossiersApi.saveFinding, {
+    run: (client, args) => client.action(api.dossiersApi.recordDecision, {
         apiKey: requireApiKey(),
         ...args,
     }),
@@ -120,7 +200,7 @@ Set \`confidence\` whenever the entry is a value: established (computed or read
 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.',
+    description: 'Reload everything a dossier holds: its questions with their evidence, options and decisions, then the evidence not yet filed under a question, then the comments a colleague left. OPEN 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()
@@ -143,23 +223,20 @@ export const loadDossier = defineTool({
 });
 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.',
+    title: 'Close a question',
+    description: 'Close a question that stopped mattering WITHOUT a decision: the variant was abandoned, the client withdrew the request, the point became moot. The question stays in the dossier, marked closed, with its evidence. To settle a question with an answer, call record_decision instead. Pass resolved: false to reopen a question. Only call this when the user says so, never on your own reasoning.',
     inputSchema: {
-        entryId: z
-            .string()
-            .min(1)
-            .describe('Entry id of the question, from load_dossier.'),
+        questionId,
         resolved: z
             .boolean()
             .optional()
-            .describe('Defaults to true. Pass false to reopen a question.'),
+            .describe('Defaults to true (close). Pass false to reopen.'),
     },
     annotations: { ...write, idempotentHint: true },
     run: async (client, args) => {
         await client.action(api.dossiersApi.resolveQuestion, {
             apiKey: requireApiKey(),
-            entryId: args.entryId,
+            questionId: args.questionId,
             resolved: args.resolved,
         });
         return { ok: true };
@@ -168,7 +245,9 @@ export const resolveQuestion = defineTool({
 export const dossierTools = [
     listDossiers,
     openDossier,
+    openQuestion,
     saveFinding,
+    recordDecision,
     loadDossier,
     resolveQuestion,
 ];

package/dist/tools/read.js

@@ -44,7 +44,7 @@ export const listNorms = defineTool({
 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).",
+    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 path, title, summary, pageStart, pageEnd, depth, and children (empty at the maxDepth boundary).",
     inputSchema: {
         norm,
         maxDepth: z
@@ -76,7 +76,7 @@ export const getToc = defineTool({
 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.',
+    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 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".'),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stratta/mcp",
   "mcpName": "ch.stratta/mcp",
-  "version": "0.9.8",
+  "version": "0.10.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>",