@stratta/mcp 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# @stratta/mcp
+
+MCP server exposing Swiss engineering norms (SIA / Eurocodes) to Claude clients via Stratta TreeRAG.
+
+> Requires a free Stratta account. Sign up at https://stratta.ch and generate an API key at https://stratta.ch/api-keys.
+
+> [!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.
+
+## Install
+
+### Claude Code (recommended)
+
+Export your key once, then register the server at **user** scope (so the key
+never lands in a committable project `.mcp.json`):
+
+```bash
+export STRATTA_API_KEY=sk_strt_xxx   # or set it in your shell profile
+claude mcp add stratta --scope user --command "npx -y @stratta/mcp" --env STRATTA_API_KEY="$STRATTA_API_KEY"
+```
+
+### Claude Desktop
+
+Edit your `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "stratta": {
+      "command": "npx",
+      "args": ["-y", "@stratta/mcp"],
+      "env": {
+        "STRATTA_API_KEY": "sk_strt_xxx"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The Stratta tools should appear in the MCP indicator.
+
+> `claude_desktop_config.json` stores the key in plaintext on your machine —
+> keep the file private and out of any synced/backed-up repo.
+
+### Global install (optional)
+
+```bash
+npm install -g @stratta/mcp
+```
+
+Then use `"command": "stratta-mcp"` instead of `npx`.
+
+## Configuration
+
+The server reads its config from environment variables. See [`.env.example`](./.env.example) for a template.
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `STRATTA_API_KEY` | yes | – | API key from https://stratta.ch/api-keys. |
+| `STRATTA_CONVEX_URL` | no | Stratta prod backend | Override only if you self-host. |
+
+## Tools exposed
+
+| Tool | Purpose |
+|---|---|
+| `list_norms` | List all available norms (code, year, title, language). |
+| `get_toc` | Get the hierarchical table of contents for a norm. |
+| `get_section` | Fetch the full enriched content of a section (with formulas, tables, cross-refs). |
+| `search_in_norm` | Search sections within a norm by keyword. |
+| `get_figure` | Retrieve a figure (image) inline (base64) to reason about diagrams. |
+| `get_cross_refs` | List outgoing cross-references from a section to other norms. |
+
+## How agents should use it
+
+1. Call `list_norms` to see what's available.
+2. Call `get_toc(norm)` to navigate the structure.
+3. Call `get_section(norm, path)` to read specific content.
+4. Use `search_in_norm` when the section path is unknown.
+5. Follow `crossRefs` for compound questions (e.g. SIA 261 → SIA 263 → EC).
+6. Call `get_figure` when the section references a figure relevant to the answer.
+
+## Troubleshooting
+
+### `Authentication failed` / `Invalid API key`
+
+- Verify the key starts with `sk_strt_` and is not revoked at https://stratta.ch/api-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.
+
+### `ECONNREFUSED` / network errors
+
+- 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
+
+- 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).
+- Make sure your Node.js version is `>=20` (`node --version`).
+
+### Rate-limited
+
+- Each user can create up to 50 active keys and 20 new keys per 24h. Revoke unused keys in the dashboard.
+
+## License
+
+Proprietary — © SmartFlow (Hugo Gebel). All rights reserved. This package is the
+official Stratta MCP client; redistribution, modification, or reuse of the source
+is not permitted without prior written consent.

package/dist/auth.d.ts

@@ -0,0 +1,7 @@
+import type { ConvexHttpClient } from 'convex/browser';
+export type AuthContext = {
+    userId: string;
+    apiKeyId: string;
+    organizationId: string | null;
+};
+export declare function ensureAuthenticated(client: ConvexHttpClient): Promise<AuthContext>;

package/dist/auth.js

@@ -0,0 +1,42 @@
+import { api } from './client.js';
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1h
+let state = { kind: 'unvalidated' };
+export async function ensureAuthenticated(client) {
+    const plaintext = process.env.STRATTA_API_KEY;
+    if (!plaintext) {
+        throw new Error('STRATTA_API_KEY environment variable is not set. Generate a key at https://stratta.ch/api-keys');
+    }
+    if (state.kind === 'valid' &&
+        Date.now() - state.validatedAt < CACHE_TTL_MS) {
+        return {
+            userId: state.userId,
+            apiKeyId: state.apiKeyId,
+            organizationId: state.organizationId,
+        };
+    }
+    if (state.kind === 'invalid') {
+        throw new Error(state.error);
+    }
+    const result = (await client.action(api.apiKeys.validateApiKey, {
+        plaintext,
+    }));
+    if (!result.valid || !result.userId || !result.apiKeyId) {
+        state = {
+            kind: 'invalid',
+            error: 'Invalid STRATTA_API_KEY. Generate a new one at https://stratta.ch/api-keys',
+        };
+        throw new Error(state.error);
+    }
+    state = {
+        kind: 'valid',
+        userId: result.userId,
+        apiKeyId: result.apiKeyId,
+        organizationId: result.organizationId,
+        validatedAt: Date.now(),
+    };
+    return {
+        userId: result.userId,
+        apiKeyId: result.apiKeyId,
+        organizationId: result.organizationId,
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,3 @@
+import { ConvexHttpClient } from 'convex/browser';
+export declare function createConvexClient(): ConvexHttpClient;
+export declare const api: import("convex/server").AnyApi;

package/dist/client.js

@@ -0,0 +1,11 @@
+import { ConvexHttpClient } from 'convex/browser';
+import { anyApi } from 'convex/server';
+const DEFAULT_CONVEX_URL = 'https://blessed-salmon-237.convex.cloud';
+export function createConvexClient() {
+    const url = process.env.STRATTA_CONVEX_URL ?? DEFAULT_CONVEX_URL;
+    return new ConvexHttpClient(url);
+}
+// Untyped api references — Convex resolves by string name at runtime.
+// Trade-off: lose compile-time type safety, gain a standalone package
+// that doesn't depend on the stratta workspace's generated types.
+export const api = anyApi;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { createConvexClient, api } from './client.js';
+import { ensureAuthenticated } from './auth.js';
+import { getMethodologyTool, handleGetMethodology } from './tools/get-methodology.js';
+import { listNormsTool, handleListNorms } from './tools/list-norms.js';
+import { getTocTool, handleGetToc } from './tools/get-toc.js';
+import { getSubtreeTool, handleGetSubtree } from './tools/get-subtree.js';
+import { getSectionTool, handleGetSection } from './tools/get-section.js';
+import { searchInNormTool, handleSearchInNorm } from './tools/search-in-norm.js';
+import { getFigureTool, handleGetFigure } from './tools/get-figure.js';
+import { getCrossRefsTool, handleGetCrossRefs } from './tools/get-cross-refs.js';
+import { ingestTools, isIngestTool, handleIngestTool } from './tools/ingest.js';
+const tools = [
+    getMethodologyTool,
+    listNormsTool,
+    getTocTool,
+    getSubtreeTool,
+    getSectionTool,
+    searchInNormTool,
+    getFigureTool,
+    getCrossRefsTool,
+    ...ingestTools,
+];
+const server = new Server({ name: 'stratta-mcp', version: '0.1.0' }, { capabilities: { tools: {} } });
+const client = createConvexClient();
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools,
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const startedAt = Date.now();
+    let apiKeyId = null;
+    let status = 'success';
+    const recordUsage = () => {
+        // Only record once authenticated. Send the plaintext key (proof of
+        // possession) — the server derives the identity, so usage can't be forged
+        // for another user's key.
+        const apiKey = process.env.STRATTA_API_KEY;
+        if (!apiKeyId || !apiKey)
+            return;
+        void client
+            .action(api.apiKeys.recordToolUsage, {
+            apiKey,
+            toolName: name,
+            status,
+            durationMs: Date.now() - startedAt,
+        })
+            .catch((e) => console.error('[stratta-mcp] track failed:', e));
+    };
+    try {
+        const auth = await ensureAuthenticated(client);
+        apiKeyId = auth.apiKeyId;
+        let result;
+        if (isIngestTool(name)) {
+            result = await handleIngestTool(client, name, (args ?? {}));
+            recordUsage();
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        switch (name) {
+            case 'get_methodology':
+                result = await handleGetMethodology(client, args);
+                break;
+            case 'list_norms':
+                result = await handleListNorms(client);
+                break;
+            case 'get_toc':
+                result = await handleGetToc(client, args);
+                break;
+            case 'get_subtree':
+                result = await handleGetSubtree(client, args);
+                break;
+            case 'get_section':
+                result = await handleGetSection(client, args);
+                break;
+            case 'search_in_norm':
+                result = await handleSearchInNorm(client, args);
+                break;
+            case 'get_figure':
+                result = await handleGetFigure(client, args);
+                break;
+            case 'get_cross_refs':
+                result = await handleGetCrossRefs(client, args);
+                break;
+            default:
+                return {
+                    content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+                    isError: true,
+                };
+        }
+        // Special handling for get_figure: return ImageContent inline
+        if (name === 'get_figure' &&
+            typeof result === 'object' &&
+            result !== null &&
+            'image' in result) {
+            const r = result;
+            recordUsage();
+            return {
+                content: [
+                    {
+                        type: 'image',
+                        data: r.image.base64,
+                        mimeType: r.image.mimeType,
+                    },
+                    {
+                        type: 'text',
+                        text: `${r.figureNumber} — ${r.caption}`,
+                    },
+                ],
+            };
+        }
+        recordUsage();
+        return {
+            content: [
+                { type: 'text', text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    }
+    catch (err) {
+        status = 'error';
+        recordUsage();
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Stderr-only logging; stdout is reserved for MCP protocol.
+    console.error('[stratta-mcp] started, listening on stdio');
+}
+main().catch((err) => {
+    console.error('[stratta-mcp] fatal:', err);
+    process.exit(1);
+});

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

@@ -0,0 +1,24 @@
+import type { ConvexHttpClient } from 'convex/browser';
+export declare const getCrossRefsTool: {
+    readonly name: "get_cross_refs";
+    readonly description: "List outgoing cross-references from a section to other norms (e.g. SIA 261 §4.2 → SIA 263). For compound questions you MUST follow these refs: fetch each target via get_section before concluding. Skipping cross-refs is the #1 cause of incomplete answers — SIA norms intentionally distribute the rule, the coefficient, and the action across separate norms (260 / 261 / domain).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly norm: {
+                readonly type: "string";
+                readonly description: "Norm code, e.g. \"SIA 261\".";
+            };
+            readonly path: {
+                readonly type: "string";
+                readonly description: "Section path, e.g. \"4.2.1\".";
+            };
+        };
+        readonly required: readonly ["norm", "path"];
+        readonly additionalProperties: false;
+    };
+};
+export declare function handleGetCrossRefs(client: ConvexHttpClient, args: {
+    norm: string;
+    path: string;
+}): Promise<unknown>;

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

@@ -0,0 +1,24 @@
+import { api } from '../client.js';
+import { ensureAuthenticated } from '../auth.js';
+export const getCrossRefsTool = {
+    name: 'get_cross_refs',
+    description: "List outgoing cross-references from a section to other norms (e.g. SIA 261 §4.2 → SIA 263). For compound questions you MUST follow these refs: fetch each target via get_section before concluding. Skipping cross-refs is the #1 cause of incomplete answers — SIA norms intentionally distribute the rule, the coefficient, and the action across separate norms (260 / 261 / domain).",
+    inputSchema: {
+        type: 'object',
+        properties: {
+            norm: { type: 'string', description: 'Norm code, e.g. "SIA 261".' },
+            path: { type: 'string', description: 'Section path, e.g. "4.2.1".' },
+        },
+        required: ['norm', 'path'],
+        additionalProperties: false,
+    },
+};
+export async function handleGetCrossRefs(client, args) {
+    await ensureAuthenticated(client);
+    const result = await client.action(api._mcp.getCrossRefs, {
+        apiKey: process.env.STRATTA_API_KEY,
+        code: args.norm,
+        path: args.path,
+    });
+    return { norm: args.norm, path: args.path, crossRefs: result };
+}

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

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

package/dist/tools/get-figure.js

@@ -0,0 +1,50 @@
+import { api } from '../client.js';
+import { ensureAuthenticated } from '../auth.js';
+export const getFigureTool = {
+    name: 'get_figure',
+    description: 'Retrieve a figure (image) referenced in a section. Returns the image inline (base64) so you can see and reason about diagrams, charts, and technical drawings. Use the `id` returned by get_section in its `figures` array.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            norm: { type: 'string', description: 'Norm code, e.g. "SIA 261".' },
+            figureId: {
+                type: 'string',
+                description: 'Figure ID from get_section response (figures[].id).',
+            },
+        },
+        required: ['norm', 'figureId'],
+        additionalProperties: false,
+    },
+};
+export async function handleGetFigure(client, args) {
+    await ensureAuthenticated(client);
+    const apiKey = process.env.STRATTA_API_KEY;
+    const meta = (await client.action(api._mcp.getFigureMeta, {
+        apiKey,
+        code: args.norm,
+        figureId: args.figureId,
+    }));
+    if (!meta) {
+        return { error: `Figure not found.` };
+    }
+    const url = (await client.action(api._mcp.getStorageUrl, {
+        apiKey,
+        code: args.norm,
+        figureId: args.figureId,
+    }));
+    if (!url) {
+        return { error: 'Figure storage is unavailable.' };
+    }
+    const response = await fetch(url);
+    if (!response.ok) {
+        return { error: `Failed to download figure: HTTP ${response.status}` };
+    }
+    const buffer = await response.arrayBuffer();
+    const base64 = Buffer.from(buffer).toString('base64');
+    const mimeType = response.headers.get('content-type') ?? 'image/png';
+    return {
+        caption: meta.caption,
+        figureNumber: meta.figureNumber,
+        image: { base64, mimeType },
+    };
+}

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

@@ -0,0 +1,18 @@
+import type { ConvexHttpClient } from 'convex/browser';
+export declare const getMethodologyTool: {
+    readonly name: "get_methodology";
+    readonly description: "MANDATORY FIRST CALL when answering any technical question about Swiss civil engineering norms via Stratta. Returns the canonical persona, navigation workflow, meta-routing hints (which SIA norms cover which topics), tree-navigation rules (where to look for formulas vs coefficients vs definitions), citation format and answer rules. Adopt these rules verbatim for the rest of the consultation. If you skip this call you WILL produce lower-quality answers (wrong citation format, missing cross-norm dependencies, hallucinated values).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly norm: {
+                readonly type: "string";
+                readonly description: "Optional: norm code the user is asking about, if already known. Used to scope methodology hints (currently informational only).";
+            };
+        };
+        readonly additionalProperties: false;
+    };
+};
+export declare function handleGetMethodology(client: ConvexHttpClient, args: {
+    norm?: string;
+}): Promise<unknown>;

package/dist/tools/get-methodology.js

@@ -0,0 +1,23 @@
+import { api } from '../client.js';
+import { ensureAuthenticated } from '../auth.js';
+export const getMethodologyTool = {
+    name: 'get_methodology',
+    description: "MANDATORY FIRST CALL when answering any technical question about Swiss civil engineering norms via Stratta. Returns the canonical persona, navigation workflow, meta-routing hints (which SIA norms cover which topics), tree-navigation rules (where to look for formulas vs coefficients vs definitions), citation format and answer rules. Adopt these rules verbatim for the rest of the consultation. If you skip this call you WILL produce lower-quality answers (wrong citation format, missing cross-norm dependencies, hallucinated values).",
+    inputSchema: {
+        type: 'object',
+        properties: {
+            norm: {
+                type: 'string',
+                description: "Optional: norm code the user is asking about, if already known. Used to scope methodology hints (currently informational only).",
+            },
+        },
+        additionalProperties: false,
+    },
+};
+export async function handleGetMethodology(client, args) {
+    await ensureAuthenticated(client);
+    const result = await client.query(api._mcp.getMethodology, {
+        norm: args.norm,
+    });
+    return result;
+}

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

@@ -0,0 +1,24 @@
+import type { ConvexHttpClient } from 'convex/browser';
+export declare const getSectionTool: {
+    readonly name: "get_section";
+    readonly description: "Fetch the full enriched content of a section: markdown text with formulas in LaTeX and tables inline, pageStart/pageEnd, figures (call get_figure for the image), attached tables/formulas, and cross-references to other norms. ALL technical claims in your answer MUST be backed by a [<norm> <path>, p. <pageStart>] citation pointing to a section you actually fetched via get_section — never cite from memory. When a section's crossRefs list non-empty targets, follow them with another get_section call if the answer depends on them.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly norm: {
+                readonly type: "string";
+                readonly description: "Norm code, e.g. \"SIA 261\".";
+            };
+            readonly path: {
+                readonly type: "string";
+                readonly description: "Section path as it appears in the document, e.g. \"4.2.1\" or \"Annexe A\".";
+            };
+        };
+        readonly required: readonly ["norm", "path"];
+        readonly additionalProperties: false;
+    };
+};
+export declare function handleGetSection(client: ConvexHttpClient, args: {
+    norm: string;
+    path: string;
+}): Promise<unknown>;

package/dist/tools/get-section.js

@@ -0,0 +1,35 @@
+import { api } from '../client.js';
+import { ensureAuthenticated } from '../auth.js';
+export const getSectionTool = {
+    name: 'get_section',
+    description: "Fetch the full enriched content of a section: markdown text with formulas in LaTeX and tables inline, pageStart/pageEnd, figures (call get_figure for the image), attached tables/formulas, and cross-references to other norms. ALL technical claims in your answer MUST be backed by a [<norm> <path>, p. <pageStart>] citation pointing to a section you actually fetched via get_section — never cite from memory. When a section's crossRefs list non-empty targets, follow them with another get_section call if the answer depends on them.",
+    inputSchema: {
+        type: 'object',
+        properties: {
+            norm: {
+                type: 'string',
+                description: 'Norm code, e.g. "SIA 261".',
+            },
+            path: {
+                type: 'string',
+                description: 'Section path as it appears in the document, e.g. "4.2.1" or "Annexe A".',
+            },
+        },
+        required: ['norm', 'path'],
+        additionalProperties: false,
+    },
+};
+export async function handleGetSection(client, args) {
+    await ensureAuthenticated(client);
+    const result = await client.action(api._mcp.getSection, {
+        apiKey: process.env.STRATTA_API_KEY,
+        code: args.norm,
+        path: args.path,
+    });
+    if (result === null) {
+        return {
+            error: `Section "${args.path}" not found in norm "${args.norm}".`,
+        };
+    }
+    return { norm: args.norm, section: result };
+}

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

@@ -0,0 +1,29 @@
+import type { ConvexHttpClient } from 'convex/browser';
+export declare const getSubtreeTool: {
+    readonly name: "get_subtree";
+    readonly 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.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly norm: {
+                readonly type: "string";
+                readonly description: "Norm code, e.g. \"SIA 261-1\".";
+            };
+            readonly path: {
+                readonly type: "string";
+                readonly description: "Section path to root the subtree at, e.g. \"14\" or \"14.2\".";
+            };
+            readonly maxDepth: {
+                readonly type: "number";
+                readonly description: "Max nesting depth relative to the root. Default: unlimited. depth=1 returns the root + direct children only.";
+            };
+        };
+        readonly required: readonly ["norm", "path"];
+        readonly additionalProperties: false;
+    };
+};
+export declare function handleGetSubtree(client: ConvexHttpClient, args: {
+    norm: string;
+    path: string;
+    maxDepth?: number;
+}): Promise<unknown>;

package/dist/tools/get-subtree.js

@@ -0,0 +1,40 @@
+import { api } from '../client.js';
+import { ensureAuthenticated } from '../auth.js';
+export const getSubtreeTool = {
+    name: 'get_subtree',
+    description: 'Drill down into a specific chapter or section. Returns the subtree rooted at `path` with optional depth limit (relative to the root). Use this after get_toc to explore one chapter in detail without fetching the entire TOC. Each node has nodeId, path, title, summary, depth, pageStart, pageEnd, and recursive children.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            norm: {
+                type: 'string',
+                description: 'Norm code, e.g. "SIA 261-1".',
+            },
+            path: {
+                type: 'string',
+                description: 'Section path to root the subtree at, e.g. "14" or "14.2".',
+            },
+            maxDepth: {
+                type: 'number',
+                description: 'Max nesting depth relative to the root. Default: unlimited. depth=1 returns the root + direct children only.',
+            },
+        },
+        required: ['norm', 'path'],
+        additionalProperties: false,
+    },
+};
+export async function handleGetSubtree(client, args) {
+    await ensureAuthenticated(client);
+    const result = await client.action(api._mcp.getSubtree, {
+        apiKey: process.env.STRATTA_API_KEY,
+        code: args.norm,
+        path: args.path,
+        maxDepth: args.maxDepth,
+    });
+    if (result === null) {
+        return {
+            error: `Section "${args.path}" not found in norm "${args.norm}".`,
+        };
+    }
+    return { norm: args.norm, root: args.path, tree: result };
+}

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

@@ -0,0 +1,24 @@
+import type { ConvexHttpClient } from 'convex/browser';
+export declare const getTocTool: {
+    readonly name: "get_toc";
+    readonly 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).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly norm: {
+                readonly type: "string";
+                readonly description: "Norm code, e.g. \"SIA 261\", \"SIA 263\", \"EN 1992-1-1\".";
+            };
+            readonly maxDepth: {
+                readonly type: "number";
+                readonly description: "Maximum nesting depth to include. Defaults to 1 (chapters only). depth=2 includes sections X.Y. depth=3 includes sub-subsections X.Y.Z (may exceed response size limit on large norms).";
+            };
+        };
+        readonly required: readonly ["norm"];
+        readonly additionalProperties: false;
+    };
+};
+export declare function handleGetToc(client: ConvexHttpClient, args: {
+    norm: string;
+    maxDepth?: number;
+}): Promise<unknown>;