@stratta/mcp 0.10.0 → 0.12.0

package/README.md

@@ -152,18 +152,35 @@ 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):
+**Read** (9 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).              |
+| `whoami`          | Which organisation, role and plan this key 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) + public URL.                           |
 | `get_cross_refs`  | Outgoing cross-refs from a section to other norms.                                     |
 
@@ -205,10 +222,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

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;