@stratta/mcp 0.10.0 → 0.12.1

package/README.md

@@ -9,34 +9,41 @@ mcp-name: ch.stratta/mcp
 
 # @stratta/mcp
 
-MCP server exposing Swiss engineering norms (SIA / Eurocodes) to Claude clients via Stratta TreeRAG.
+The local MCP server for [Stratta](https://stratta.ch): the engineering norms
+your bureau licensed (SIA, Eurocodes), cited to the section and page, inside
+any agent that speaks MCP.
 
-> Requires a free Stratta account. Sign up at https://stratta.ch and generate an API key at https://stratta.ch/api-keys.
+> Requires a free Stratta account: https://stratta.ch/sign-up.
 
 > [!IMPORTANT]
 > Your `STRATTA_API_KEY` is a **secret** — it grants read/write access to your
 > Stratta workspace. Never commit it to a repository, paste it into a shared/
 > project-scoped MCP config, or share it in logs. Prefer a user-scoped config or
-> a shell environment variable. If a key leaks, revoke it immediately at
-> https://stratta.ch/api-keys.
+> a shell environment variable. If a key leaks, revoke it immediately under
+> Settings › API keys (https://stratta.ch/settings?tab=keys).
 
 ## Do you need this package?
 
-Often not. Stratta also runs as a **remote connector** — one address, a browser
-sign-in, no key and no Node:
+Usually not. Stratta also runs as a **remote connector** — one address, a
+browser sign-in, no key, no Node:
 
 ```
 https://stratta.ch/mcp
 ```
 
-That is the shorter path, and the only one that works in an agent running in the
-cloud (claude.ai). See https://stratta.ch/docs/en/guides/connect-remote.
+That is the shorter path, the one the dashboard walks you through for Claude,
+ChatGPT, Claude Code, Codex, Cursor, VS Code, Gemini CLI and Windsurf, and the
+only one that works in an agent running in the cloud (claude.ai, ChatGPT). It
+serves 32 of the 33 tools below, **ingestion included**: the pre-pass script is
+downloaded from https://stratta.ch/ingest-prepass.py when it is not on disk.
+See https://stratta.ch/docs/en/guides/connect-remote.
 
 This package is what you want when:
 
-- you are **ingesting a norm** — it reads a PDF from your disk and runs a Python
-  pre-pass, neither of which a remote connector can reach;
-- your agent **cannot open a browser** — CI, a scheduled task, a server;
+- your agent **cannot open a browser** — CI, a scheduled task, a server — and
+  authenticates with an API key instead;
+- you want `add_attachment`, the one tool the connector does not serve: it
+  uploads a file from your disk to a project dossier;
 - you would simply rather run the server yourself.
 
 ## Install
@@ -63,7 +70,7 @@ npx -y @stratta/mcp login
 ```
 
 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.
+key from https://stratta.ch/settings?tab=keys instead, without echoing it.
 
 If you skip the step entirely, Claude Code prompts you for a key on the first
 tool call.
@@ -152,50 +159,76 @@ settings come from environment variables — see [`.env.example`](./.env.example
 | `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.                                                                                                                                |
 
+## Tests
+
+`npm test` runs the unit tests. The two integration suites
+(`tests/handlers.test.ts`, `tests/dossier-flow.e2e.test.ts`) run this checkout's
+built server against the deployment you name, and are skipped when either
+variable is missing:
+
+```bash
+npm run build
+STRATTA_E2E_URL=https://<dev-deployment>.convex.cloud STRATTA_E2E_API_KEY=sk_strt_... npm test
+```
+
+Point them at a development deployment: the dossier flow creates a dossier
+named `E2E dossier <timestamp>` and does not delete it.
+
 ## Tools exposed
 
-**Read** (8 tools — query norms in your workspace):
-
-| 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.                                     |
-
-**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.                  |
+33 tools, generated from one catalogue shared with the remote connector (which
+serves the same 33 minus `add_attachment`).
+
+**Read** (10 tools — query the norms of your workspace):
+
+| Tool              | Purpose                                                                                 |
+| ----------------- | --------------------------------------------------------------------------------------- |
+| `get_methodology` | Behavioural contract: persona, workflow, meta-routing hints, answer rules. Call first.  |
+| `whoami`          | Which organisation, role and plan this connection reads as, and how many norms it sees. |
+| `list_norms`      | List all norms published in your workspace (code, year, title, language, coverage).     |
+| `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.                                                           |
+| `search_corpus`   | Keyword search across every norm of the workspace, grouped by norm.                     |
+| `get_figure`      | Retrieve a figure inline (base64 ImageContent).                                         |
+| `get_cross_refs`  | Outgoing cross-refs from a section to other norms.                                      |
+
+**Dossier** (13 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.                                |
+| `list_attachments`  | The project attachments of a dossier: site reports, borehole logs, minutes, data sheets.               |
+| `read_attachment`   | Read an attachment's text as Markdown, page by page.                                                   |
+| `search_in_dossier` | Full-text search over a dossier's attachments, with the page of each hit.                              |
+| `add_attachment`    | Upload a file from the user's machine to a dossier (PDF, DOCX, XLSX, images, text). Local server only. |
+| `list_templates`    | The checklists the organisation wrote for its types of structure.                                      |
+| `apply_template`    | Open a template's questions in a dossier and file the clauses that resolve in the corpus.              |
 
 A dossier is read, annotated, reviewed and exported from
 [stratta.ch/dossiers](https://stratta.ch/dossiers).
 
-**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.                      |
+**Ingest** (10 tools — add YOUR licensed norms; driven by the bundled `ingest-norm` skill; owner or admin role):
+
+| Tool                          | Purpose                                                                          |
+| ----------------------------- | -------------------------------------------------------------------------------- |
+| `ingest_status`               | Check if a norm already exists in your workspace, and its coverage.              |
+| `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`              | Score the document and flip it to published; refuses below 30/100 unless forced. |
+| `ingest_delete`               | Delete a document and all its children.                                          |
 
 ## How agents should use it
 
@@ -205,10 +238,27 @@ For querying:
 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.
+5. Use `search_corpus` when the norm is unknown, `search_in_norm` when the section path is.
 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.
 
+Two skills ship in the package: **`consult-stratta`** (the working method an agent
+follows to answer from the norms, generated from the same text the server serves
+through `get_methodology`) and **`ingest-norm`**.
+
+## Resources and prompts
+
+Four `stratta://` resources can be pinned to a conversation or read without a
+tool call, each scoped to your workspace: `stratta://norms` (JSON),
+`stratta://methodology` (Markdown), `stratta://norm/{code}/toc` (the table of
+contents to depth 2, code URL-encoded, e.g. `stratta://norm/SIA%20267/toc`) and
+`stratta://dossier/{id}` (a project dossier as Markdown). The same four are
+served by the remote connector.
+
+Three prompts appear as slash commands in clients that support them:
+`investigate-question` (question, project?), `resume-dossier` (name) and
+`check-value` (value, norm?).
+
 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
@@ -220,7 +270,7 @@ Requires Python ≥ 3.10 with PyMuPDF (`python -m pip install --user pymupdf`).
 
 ### `Authentication failed` / `Invalid API key`
 
-- Verify the key starts with `sk_strt_` and is not revoked at https://stratta.ch/api-keys.
+- Verify the key starts with `sk_strt_` and is not revoked at https://stratta.ch/settings?tab=keys.
 - Check the env var is reaching the process: `echo $STRATTA_API_KEY` (or `$env:STRATTA_API_KEY` on Windows PowerShell).
 - If you copied from the UI, make sure no leading/trailing whitespace was added.
 
@@ -229,7 +279,7 @@ Requires Python ≥ 3.10 with PyMuPDF (`python -m pip install --user pymupdf`).
 - Confirm outbound HTTPS to `*.convex.cloud` is allowed by your firewall/VPN.
 - Try `curl -I https://stratta.ch` to verify general internet reachability.
 
-### Tools don't appear in Claude
+### Tools don't appear in your agent
 
 - Restart your Claude client after editing the config.
 - Check the MCP server logs (Claude Code: `claude mcp logs stratta`; Claude Desktop: `~/Library/Logs/Claude/mcp-server-stratta.log` on macOS).
@@ -244,16 +294,17 @@ 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       |
-
-Beyond Max, an Enterprise plan scales to 100 members, 300 norms and a million
-monthly queries; the calculator is at https://stratta.ch/tarifs
+| Limit           | Free  | Pro    | Max    | Team   |
+| --------------- | ----- | ------ | ------ | ------ |
+| Norms           | 1     | 15     | 60     | 75     |
+| Sections        | 1,000 | 15,000 | 60,000 | 75,000 |
+| Figures         | 60    | 750    | 3,000  | 3,750  |
+| Queries / month | 500   | 15,000 | 60,000 | 75,000 |
+| Members         | 1     | 1      | 1      | 5      |
+
+Beyond the included queries, paid plans bill the overage per thousand. An
+Enterprise contract scales seats, norms and queries further; 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,

package/dist/confirm.d.ts

@@ -0,0 +1,15 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * The confirmation step before a decision is written, on stdio.
+ *
+ * Same contract as the remote gate: `confirmed: true` in the arguments means
+ * the agent already asked the user; otherwise the client is asked through an
+ * elicitation when it supports one, and told to come back with
+ * `confirmed: true` when it does not. The Convex function never sees the
+ * difference.
+ */
+export declare const CONFIRMED_TOOLS: Record<string, (args: Record<string, unknown>) => string>;
+export declare const CONFIRMATION_HINT: string;
+/** `null` when the call may proceed, a tool result to return otherwise. */
+export declare function confirmWithUser(server: Pick<Server, 'getClientCapabilities' | 'elicitInput'>, toolName: string, args: Record<string, unknown>): Promise<CallToolResult | null>;

package/dist/confirm.js

@@ -0,0 +1,54 @@
+/**
+ * The confirmation step before a decision is written, on stdio.
+ *
+ * Same contract as the remote gate: `confirmed: true` in the arguments means
+ * the agent already asked the user; otherwise the client is asked through an
+ * elicitation when it supports one, and told to come back with
+ * `confirmed: true` when it does not. The Convex function never sees the
+ * difference.
+ */
+export const CONFIRMED_TOOLS = {
+    record_decision: (args) => [
+        args.title,
+        args.value ? `= ${String(args.value)}` : null,
+        args.retainedOption ? `(option ${String(args.retainedOption)})` : null,
+    ]
+        .filter(Boolean)
+        .map(String)
+        .join(' '),
+    resolve_question: (args) => args.resolved === false
+        ? 'reopen this question'
+        : 'close this question without a decision',
+};
+export const CONFIRMATION_HINT = 'Not recorded: this client cannot ask the user directly. Confirm the ' +
+    'decision with the user in the conversation, then call again with ' +
+    'confirmed: true.';
+/** `null` when the call may proceed, a tool result to return otherwise. */
+export async function confirmWithUser(server, toolName, args) {
+    const summary = CONFIRMED_TOOLS[toolName];
+    if (!summary || args.confirmed === true)
+        return null;
+    if (!server.getClientCapabilities()?.elicitation) {
+        return {
+            content: [{ type: 'text', text: CONFIRMATION_HINT }],
+            structuredContent: { outcome: 'confirmation_required' },
+            isError: true,
+        };
+    }
+    const result = await server.elicitInput({
+        mode: 'form',
+        message: `${toolName === 'record_decision' ? 'Decision' : 'Question'}: ${summary(args)}\n\nRecord it in the dossier?`,
+        requestedSchema: {
+            type: 'object',
+            properties: { confirm: { type: 'boolean', title: 'Record it' } },
+            required: ['confirm'],
+        },
+    });
+    if (result.action !== 'accept' || result.content?.confirm === false) {
+        return {
+            content: [{ type: 'text', text: 'Not recorded: the user declined.' }],
+            structuredContent: { outcome: 'declined' },
+        };
+    }
+    return null;
+}

package/dist/errors.js

@@ -4,6 +4,22 @@ function isQuotaPayload(data) {
         data !== null &&
         data.code === 'QUOTA_EXCEEDED');
 }
+function isQualityPayload(data) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        data.code === 'QUALITY_TOO_LOW');
+}
+/** What each coverage flag means, in words the agent can relay. */
+const FLAG_TEXT = {
+    'sparse-text': 'trop peu de texte par page : le contenu des sections est un résumé, pas le texte de la norme',
+    'light-text': 'peu de texte par page',
+    'few-sections': "moins de 5 sections : la détection des titres n'a rien trouvé",
+    'thin-sections': 'sections presque vides (moins de 200 caractères en moyenne)',
+    'low-coverage': 'les chapitres couvrent moins de la moitié des pages',
+    'empty-leaves': 'plus de 20 % des sections feuilles sont vides',
+    'duplicate-paths': 'plusieurs sections portent le même chemin',
+    'no-enrichment': 'aucune formule ni tableau attaché',
+};
 function humanDuration(ms) {
     const days = Math.floor(ms / 86_400_000);
     if (days >= 1)
@@ -22,6 +38,7 @@ const DOCS = 'https://stratta.ch/docs/fr';
  */
 const HELP = {
     QUOTA_EXCEEDED: `${DOCS}/account/plans#quand-une-limite-est-atteinte`,
+    QUALITY_TOO_LOW: `${DOCS}/guides/ingest-a-norm`,
     UNAUTHORIZED: `${DOCS}/guides/get-api-key`,
     NO_ORGANIZATION: `${DOCS}/guides/manage-organization`,
     DOCUMENT_NOT_FOUND: `${DOCS}/guides/ingest-a-norm`,
@@ -59,6 +76,16 @@ export function formatToolError(err) {
             lines.push('Ne relancez pas la même opération : elle échouera à l’identique tant que la limite est atteinte.');
             return withHelp('QUOTA_EXCEEDED', lines);
         }
+        if (isQualityPayload(data)) {
+            const lines = [
+                `Document non publié : score de couverture ${data.score}/100, sous le plancher de ${data.minimum}.`,
+                `Mesures : ${data.charsPerPage} caractères par page, ${Math.round(data.pagesCovered * 100)} % des pages sous un chapitre, ${data.sectionCount} sections.`,
+                ...data.flags.map((f) => `- ${FLAG_TEXT[f] ?? f}`),
+                'Un agent qui lirait ce document répondrait depuis des résumés. Corrigez l’ingestion (le champ `content` de chaque section doit porter le texte de la norme, chaque chapitre ses pages) plutôt que de relancer la publication.',
+                'Si le document est réellement aussi court, demandez à l’utilisateur, puis rappelez `ingest_publish` avec `force: true`.',
+            ];
+            return withHelp('QUALITY_TOO_LOW', lines);
+        }
         if (typeof data === 'string') {
             switch (data) {
                 case 'UNAUTHORIZED':

package/dist/index.js

@@ -8,9 +8,14 @@ import { createConvexClient, api } from './client.js';
 import { formatToolError } from './errors.js';
 import { ensureAuthenticated, resolveApiKey } from './auth.js';
 import { elicitApiKey } from './elicit.js';
+import { confirmWithUser } from './confirm.js';
 import { readTools } from './tools/read.js';
 import { ingestTools } from './tools/ingest.js';
 import { dossierTools } from './tools/dossier.js';
+import { SESSION_ID, usageDigest } from './usage.js';
+import { SERVER_INSTRUCTIONS } from './tools/catalog.gen.js';
+import { registerResources } from './resources.js';
+import { registerPrompts } from './prompts.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
@@ -32,7 +37,14 @@ function packageVersion() {
     }
     return '0.0.0';
 }
-const server = new McpServer({ name: 'stratta-mcp', version: packageVersion() }, { capabilities: { tools: {} } });
+const server = new McpServer({ name: 'stratta-mcp', version: packageVersion() }, 
+// The same sentence the remote transport sends at initialisation. Not every
+// client shows it to the model, which is why each tool description stands
+// on its own; where it is shown, the two transports say the same thing.
+{
+    capabilities: { tools: {}, resources: {}, prompts: {} },
+    instructions: SERVER_INSTRUCTIONS,
+});
 const client = createConvexClient();
 /**
  * Everything every tool call needs, in one place: resolve the key (env, then
@@ -57,6 +69,8 @@ async function call(def, args) {
             toolName: def.name,
             status,
             durationMs: Date.now() - startedAt,
+            sessionId: SESSION_ID,
+            argsDigest: usageDigest(args),
         })
             .catch((e) => console.error('[stratta-mcp] usage report failed:', e));
     };
@@ -64,12 +78,19 @@ async function call(def, args) {
         resolvedKey = resolveApiKey() ?? (await elicitApiKey(server.server, client));
         await ensureAuthenticated(client, resolvedKey);
         authenticated = true;
+        // A decision is written only once the user confirmed it: through the
+        // client when it can ask, through the agent otherwise (`confirm.ts`).
+        const gate = await confirmWithUser(server.server, def.name, (args ?? {}));
+        if (gate)
+            return gate;
         const result = await def.run(client, args);
         reportUsage();
         if (def.toContent)
             return def.toContent(result);
+        // Compact: the two-space indentation was a third more tokens on every
+        // section an agent read, for a reader that never looks at whitespace.
         return {
-            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            content: [{ type: 'text', text: JSON.stringify(result) }],
         };
     }
     catch (err) {
@@ -92,6 +113,10 @@ for (const def of [...readTools, ...dossierTools, ...ingestTools]) {
     // handler receives values that already match the declared shape.
     (args) => call(def, args));
 }
+// Documents an agent can read without a tool call, and the three ways a
+// user starts a conversation. Neither exists on the remote transport yet.
+registerResources(server, client);
+registerPrompts(server);
 /**
  * The help nobody had.
  *

package/dist/prompts.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type PromptEntry } from './tools/catalog.gen.js';
+export declare function renderPrompt(p: PromptEntry, args: Record<string, unknown>): string;
+export declare function registerPrompts(server: McpServer): void;

package/dist/prompts.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { PROMPTS } from './tools/catalog.gen.js';
+/**
+ * Prompts: the three ways a user starts a conversation with Stratta, as
+ * slash commands in the clients that support them (Claude Code, Claude
+ * Desktop, Cursor). stdio only: the remote gateway does not carry prompts yet.
+ *
+ * Text and arguments come from the catalogue, so a wording change is made
+ * once. `{{arg}}` is filled with the argument; an `optional` line is appended
+ * only when its argument was given.
+ */
+const fill = (template, args) => template.replace(/\{\{(\w+)\}\}/g, (_match, key) => String(args[key] ?? ''));
+export function renderPrompt(p, args) {
+    let text = fill(p.text, args);
+    for (const [arg, line] of Object.entries(p.optional ?? {})) {
+        if (args[arg])
+            text += `\n${fill(line, args)}`;
+    }
+    return text;
+}
+export function registerPrompts(server) {
+    for (const p of PROMPTS) {
+        const shape = {};
+        for (const a of p.args) {
+            const s = z.string().describe(a.description);
+            shape[a.name] = a.required ? s : s.optional();
+        }
+        server.registerPrompt(p.name, { title: p.title, description: p.description, argsSchema: shape }, (args) => ({
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: renderPrompt(p, args),
+                    },
+                },
+            ],
+        }));
+    }
+}

package/dist/resources.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ConvexHttpClient } from 'convex/browser';
+export declare function registerResources(server: McpServer, client: ConvexHttpClient): void;

package/dist/resources.js

@@ -0,0 +1,35 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { api } from './client.js';
+import { requireApiKey } from './auth.js';
+async function read(client, uri) {
+    const content = (await client.action(api._mcp.readResource, {
+        apiKey: requireApiKey(),
+        uri,
+    }));
+    if (!content) {
+        throw new Error(`Nothing at ${uri}: the norm or dossier is not in this workspace. Read stratta://norms or call list_dossiers.`);
+    }
+    return { contents: [content] };
+}
+export function registerResources(server, client) {
+    server.registerResource('norms', 'stratta://norms', {
+        title: 'Readable norms',
+        description: 'The norms this workspace can read, with code, year, title, language, scope and coverage. JSON.',
+        mimeType: 'application/json',
+    }, (uri) => read(client, uri.href));
+    server.registerResource('methodology', 'stratta://methodology', {
+        title: 'Working method',
+        description: 'The working method served by get_methodology, as one Markdown document built for this workspace.',
+        mimeType: 'text/markdown',
+    }, (uri) => read(client, uri.href));
+    server.registerResource('norm-toc', new ResourceTemplate('stratta://norm/{code}/toc', { list: undefined }), {
+        title: 'Table of contents of a norm',
+        description: 'Chapters and X.Y sections of one norm with their summaries and pages, as Markdown. {code} is the norm code, URL-encoded (SIA%20267).',
+        mimeType: 'text/markdown',
+    }, (uri) => read(client, uri.href));
+    server.registerResource('dossier', new ResourceTemplate('stratta://dossier/{id}', { list: undefined }), {
+        title: 'Project dossier',
+        description: 'One project dossier as Markdown: its questions with evidence, options and decisions, then the evidence not yet filed. {id} is the dossierId from list_dossiers.',
+        mimeType: 'text/markdown',
+    }, (uri) => read(client, uri.href));
+}

package/dist/tools/catalog.gen.d.ts

@@ -0,0 +1,34 @@
+export type Transport = 'stdio' | 'remote';
+export type ToolAnnotations = {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export type CatalogEntry = {
+    name: string;
+    title: string;
+    description: string;
+    annotations: ToolAnnotations;
+    transports: Transport[];
+    params: Record<string, string>;
+};
+export declare const SERVER_INSTRUCTIONS = "Stratta serves the construction norms of the signed-in organization, and only those. Call `get_methodology` before the first technical question of a conversation: it carries the navigation order, the citation rules and the dossier policy. Never answer a technical question from memory; a norm absent from `list_norms` cannot be read.";
+export declare const CATALOG: CatalogEntry[];
+export type PromptArg = {
+    name: string;
+    description: string;
+    required: boolean;
+};
+export type PromptEntry = {
+    name: string;
+    title: string;
+    description: string;
+    args: PromptArg[];
+    text: string;
+    optional?: Record<string, string>;
+};
+export declare const PROMPTS: PromptEntry[];
+export declare function catalogEntry(name: string): CatalogEntry;
+/** Description of one parameter, as the catalogue words it. */
+export declare function param(tool: string, name: string): string;