@stratta/mcp 0.1.0 → 0.2.0

package/README.md

@@ -15,27 +15,46 @@ MCP server exposing Swiss engineering norms (SIA / Eurocodes) to Claude clients
 
 ### 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`):
+Add the server — no key needed up front:
 
 ```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 mcp add stratta -- npx -y @stratta/mcp
+```
+
+On the first call, Claude Code prompts you to paste your Stratta API key. It's
+validated and saved to `~/.stratta/config.json` (owner-only, `0600`), so you
+only do this once.
+
+Prefer to set it up ahead of time? Log in via the CLI:
+
+```bash
+npx -y @stratta/mcp login
+```
+
+…or pass the key explicitly as an environment variable (it then takes
+precedence over the saved key):
+
+```bash
+claude mcp add stratta --scope user --env STRATTA_API_KEY=sk_strt_xxx -- npx -y @stratta/mcp
 ```
 
 ### Claude Desktop
 
-Edit your `claude_desktop_config.json` (Settings → Developer → Edit Config):
+Save your key once via the CLI:
+
+```bash
+npx -y @stratta/mcp login
+```
+
+Then add the server to `claude_desktop_config.json` (Settings → Developer →
+Edit Config) — no key needed in the file:
 
 ```json
 {
   "mcpServers": {
     "stratta": {
       "command": "npx",
-      "args": ["-y", "@stratta/mcp"],
-      "env": {
-        "STRATTA_API_KEY": "sk_strt_xxx"
-      }
+      "args": ["-y", "@stratta/mcp"]
     }
   }
 }
@@ -43,8 +62,9 @@ Edit your `claude_desktop_config.json` (Settings → Developer → Edit Config):
 
 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.
+> Prefer to keep the key in the config instead of `~/.stratta/config.json`? Add
+> an `"env": { "STRATTA_API_KEY": "sk_strt_xxx" }` block to the server entry —
+> but that file then stores the key in plaintext, so keep it private and unsynced.
 
 ### Global install (optional)
 
@@ -56,11 +76,13 @@ 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.
+The API key is resolved in this order: the `STRATTA_API_KEY` env var, then
+`~/.stratta/config.json` (written by `login` or the first-run prompt). Other
+settings come from environment variables — see [`.env.example`](./.env.example).
 
 | Variable | Required | Default | Purpose |
 |---|---|---|---|
-| `STRATTA_API_KEY` | yes | – | API key from https://stratta.ch/api-keys. |
+| `STRATTA_API_KEY` | no¹ | – | API key from https://stratta.ch. ¹If unset, the server falls back to `~/.stratta/config.json`, or prompts you on first use (clients that support elicitation). |
 | `STRATTA_CONVEX_URL` | no | Stratta prod backend | Override only if you self-host. |
 
 ## Tools exposed

package/dist/auth.d.ts

@@ -4,4 +4,6 @@ export type AuthContext = {
     apiKeyId: string;
     organizationId: string | null;
 };
-export declare function ensureAuthenticated(client: ConvexHttpClient): Promise<AuthContext>;
+export declare function resolveApiKey(): string | null;
+export declare function requireApiKey(): string;
+export declare function ensureAuthenticated(client: ConvexHttpClient, plaintext: string): Promise<AuthContext>;

package/dist/auth.js

@@ -1,12 +1,25 @@
 import { api } from './client.js';
+import { readStoredApiKey } from './config.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');
+// Resolve the API key from the environment first (explicit, ephemeral), then
+// fall back to the persisted config file (written by `login` or elicitation).
+export function resolveApiKey() {
+    const fromEnv = process.env.STRATTA_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    return readStoredApiKey();
+}
+export function requireApiKey() {
+    const key = resolveApiKey();
+    if (!key) {
+        throw new Error('No Stratta API key found. Set STRATTA_API_KEY or run: npx @stratta/mcp login');
     }
+    return key;
+}
+export async function ensureAuthenticated(client, plaintext) {
     if (state.kind === 'valid' &&
+        state.plaintext === plaintext &&
         Date.now() - state.validatedAt < CACHE_TTL_MS) {
         return {
             userId: state.userId,
@@ -14,7 +27,7 @@ export async function ensureAuthenticated(client) {
             organizationId: state.organizationId,
         };
     }
-    if (state.kind === 'invalid') {
+    if (state.kind === 'invalid' && state.plaintext === plaintext) {
         throw new Error(state.error);
     }
     const result = (await client.action(api.apiKeys.validateApiKey, {
@@ -23,12 +36,14 @@ export async function ensureAuthenticated(client) {
     if (!result.valid || !result.userId || !result.apiKeyId) {
         state = {
             kind: 'invalid',
+            plaintext,
             error: 'Invalid STRATTA_API_KEY. Generate a new one at https://stratta.ch/api-keys',
         };
         throw new Error(state.error);
     }
     state = {
         kind: 'valid',
+        plaintext,
         userId: result.userId,
         apiKeyId: result.apiKeyId,
         organizationId: result.organizationId,

package/dist/config.d.ts

@@ -0,0 +1,3 @@
+export declare const CONFIG_PATH: string;
+export declare function readStoredApiKey(path?: string): string | null;
+export declare function writeStoredApiKey(apiKey: string, path?: string): void;

package/dist/config.js

@@ -0,0 +1,23 @@
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+// The API key persists here so a user only enters it once. chmod 0600 on the
+// file (best-effort on Windows) keeps it readable by the owner only. This is
+// the same pattern used by gh / aws / auth0 CLIs.
+export const CONFIG_PATH = join(homedir(), '.stratta', 'config.json');
+export function readStoredApiKey(path = CONFIG_PATH) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        const key = parsed.apiKey?.trim();
+        return key && key.length > 0 ? key : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeStoredApiKey(apiKey, path = CONFIG_PATH) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify({ apiKey }, null, 2) + '\n', {
+        mode: 0o600,
+    });
+}

package/dist/elicit.d.ts

@@ -0,0 +1,3 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ConvexHttpClient } from 'convex/browser';
+export declare function elicitApiKey(server: Server, client: ConvexHttpClient): Promise<string>;

package/dist/elicit.js

@@ -0,0 +1,42 @@
+import { api } from './client.js';
+import { writeStoredApiKey } from './config.js';
+// Ask the user for their API key through the MCP client (an interactive
+// dialog shown by Claude), validate it, and persist it so they only do this
+// once. The key travels over the client<->user channel, not through the LLM.
+export async function elicitApiKey(server, client) {
+    const caps = server.getClientCapabilities();
+    if (!caps?.elicitation) {
+        throw new Error('No Stratta API key found, and this MCP client cannot prompt for one. ' +
+            'Set STRATTA_API_KEY in the server env, or run: npx @stratta/mcp login');
+    }
+    const result = await server.elicitInput({
+        mode: 'form',
+        message: 'Stratta needs your API key. Generate one at https://stratta.ch (API keys page) and paste it below.',
+        requestedSchema: {
+            type: 'object',
+            properties: {
+                apiKey: {
+                    type: 'string',
+                    title: 'Stratta API key',
+                    description: 'Starts with sk_strt_',
+                },
+            },
+            required: ['apiKey'],
+        },
+    });
+    if (result.action !== 'accept' || !result.content) {
+        throw new Error('API key entry was cancelled. Set STRATTA_API_KEY or run: npx @stratta/mcp login');
+    }
+    const apiKey = String(result.content.apiKey ?? '').trim();
+    if (!apiKey) {
+        throw new Error('No API key was provided.');
+    }
+    const res = (await client.action(api.apiKeys.validateApiKey, {
+        plaintext: apiKey,
+    }));
+    if (!res?.valid) {
+        throw new Error('That API key is invalid. Generate a new one at https://stratta.ch and try again.');
+    }
+    writeStoredApiKey(apiKey);
+    return apiKey;
+}

package/dist/index.js

@@ -3,7 +3,8 @@ 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 { ensureAuthenticated, resolveApiKey } from './auth.js';
+import { elicitApiKey } from './elicit.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';
@@ -24,7 +25,7 @@ const tools = [
     getCrossRefsTool,
     ...ingestTools,
 ];
-const server = new Server({ name: 'stratta-mcp', version: '0.1.0' }, { capabilities: { tools: {} } });
+const server = new Server({ name: 'stratta-mcp', version: '0.2.0' }, { capabilities: { tools: {} } });
 const client = createConvexClient();
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools,
@@ -33,17 +34,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const startedAt = Date.now();
     let apiKeyId = null;
+    let resolvedKey = 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)
+        if (!apiKeyId || !resolvedKey)
             return;
         void client
             .action(api.apiKeys.recordToolUsage, {
-            apiKey,
+            apiKey: resolvedKey,
             toolName: name,
             status,
             durationMs: Date.now() - startedAt,
@@ -51,7 +52,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             .catch((e) => console.error('[stratta-mcp] track failed:', e));
     };
     try {
-        const auth = await ensureAuthenticated(client);
+        resolvedKey = resolveApiKey();
+        if (!resolvedKey) {
+            resolvedKey = await elicitApiKey(server, client);
+        }
+        const auth = await ensureAuthenticated(client, resolvedKey);
         apiKeyId = auth.apiKeyId;
         let result;
         if (isIngestTool(name)) {
@@ -131,6 +136,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
 });
 async function main() {
+    if (process.argv[2] === 'login') {
+        const { runLogin } = await import('./login.js');
+        await runLogin();
+        return;
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Stderr-only logging; stdout is reserved for MCP protocol.

package/dist/login.d.ts

@@ -0,0 +1 @@
+export declare function runLogin(): Promise<void>;

package/dist/login.js

@@ -0,0 +1,40 @@
+import { createInterface } from 'node:readline';
+import { createConvexClient, api } from './client.js';
+import { writeStoredApiKey, CONFIG_PATH } from './config.js';
+// Prompt for a secret on the TTY without echoing it back.
+function promptSecret(query) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        let muted = false;
+        rl._writeToOutput =
+            (s) => {
+                if (!muted)
+                    process.stdout.write(s);
+            };
+        rl.question(query, (answer) => {
+            rl.close();
+            process.stdout.write('\n');
+            resolve(answer.trim());
+        });
+        muted = true;
+    });
+}
+export async function runLogin() {
+    const apiKey = await promptSecret('Paste your Stratta API key (from https://stratta.ch): ');
+    if (!apiKey) {
+        console.error('No key entered. Aborting.');
+        process.exitCode = 1;
+        return;
+    }
+    const client = createConvexClient();
+    const res = (await client.action(api.apiKeys.validateApiKey, {
+        plaintext: apiKey,
+    }));
+    if (!res?.valid) {
+        console.error('That API key is invalid. Generate a new one at https://stratta.ch and try again.');
+        process.exitCode = 1;
+        return;
+    }
+    writeStoredApiKey(apiKey);
+    console.log(`Saved. Stratta MCP will use this key (stored at ${CONFIG_PATH}).`);
+}

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

@@ -1,5 +1,5 @@
 import { api } from '../client.js';
-import { ensureAuthenticated } from '../auth.js';
+import { requireApiKey } 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).",
@@ -14,9 +14,8 @@ export const getCrossRefsTool = {
     },
 };
 export async function handleGetCrossRefs(client, args) {
-    await ensureAuthenticated(client);
     const result = await client.action(api._mcp.getCrossRefs, {
-        apiKey: process.env.STRATTA_API_KEY,
+        apiKey: requireApiKey(),
         code: args.norm,
         path: args.path,
     });

package/dist/tools/get-figure.js

@@ -1,5 +1,5 @@
 import { api } from '../client.js';
-import { ensureAuthenticated } from '../auth.js';
+import { requireApiKey } 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.',
@@ -17,8 +17,7 @@ export const getFigureTool = {
     },
 };
 export async function handleGetFigure(client, args) {
-    await ensureAuthenticated(client);
-    const apiKey = process.env.STRATTA_API_KEY;
+    const apiKey = requireApiKey();
     const meta = (await client.action(api._mcp.getFigureMeta, {
         apiKey,
         code: args.norm,

package/dist/tools/get-methodology.js

@@ -1,5 +1,4 @@
 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).",
@@ -15,7 +14,6 @@ export const getMethodologyTool = {
     },
 };
 export async function handleGetMethodology(client, args) {
-    await ensureAuthenticated(client);
     const result = await client.query(api._mcp.getMethodology, {
         norm: args.norm,
     });

package/dist/tools/get-section.js

@@ -1,5 +1,5 @@
 import { api } from '../client.js';
-import { ensureAuthenticated } from '../auth.js';
+import { requireApiKey } 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.",
@@ -20,9 +20,8 @@ export const getSectionTool = {
     },
 };
 export async function handleGetSection(client, args) {
-    await ensureAuthenticated(client);
     const result = await client.action(api._mcp.getSection, {
-        apiKey: process.env.STRATTA_API_KEY,
+        apiKey: requireApiKey(),
         code: args.norm,
         path: args.path,
     });

package/dist/tools/get-subtree.js

@@ -1,5 +1,5 @@
 import { api } from '../client.js';
-import { ensureAuthenticated } from '../auth.js';
+import { requireApiKey } 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.',
@@ -24,9 +24,8 @@ export const getSubtreeTool = {
     },
 };
 export async function handleGetSubtree(client, args) {
-    await ensureAuthenticated(client);
     const result = await client.action(api._mcp.getSubtree, {
-        apiKey: process.env.STRATTA_API_KEY,
+        apiKey: requireApiKey(),
         code: args.norm,
         path: args.path,
         maxDepth: args.maxDepth,

package/dist/tools/get-toc.js

@@ -1,5 +1,5 @@
 import { api } from '../client.js';
-import { ensureAuthenticated } from '../auth.js';
+import { requireApiKey } from '../auth.js';
 export const getTocTool = {
     name: 'get_toc',
     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).",
@@ -20,9 +20,8 @@ export const getTocTool = {
     },
 };
 export async function handleGetToc(client, args) {
-    await ensureAuthenticated(client);
     const result = await client.action(api._mcp.getDocumentToc, {
-        apiKey: process.env.STRATTA_API_KEY,
+        apiKey: requireApiKey(),
         code: args.norm,
         maxDepth: args.maxDepth,
     });

package/dist/tools/ingest.js

@@ -1,5 +1,5 @@
 import { api } from '../client.js';
-import { ensureAuthenticated } from '../auth.js';
+import { requireApiKey } from '../auth.js';
 // Ingestion tools — let an engineering office add ITS OWN licensed norms to its
 // Stratta workspace, agentically, from the user's own Claude. Every call is
 // authenticated by the user's STRATTA_API_KEY and scoped server-side to their
@@ -159,8 +159,7 @@ export function isIngestTool(name) {
     return ingestTools.some((t) => t.name === name);
 }
 export async function handleIngestTool(client, name, args) {
-    await ensureAuthenticated(client);
-    const apiKey = process.env.STRATTA_API_KEY;
+    const apiKey = requireApiKey();
     switch (name) {
         case 'ingest_status':
             return await client.action(api.ingestionApi.ingestStatus, {

package/dist/tools/list-norms.js

@@ -1,5 +1,5 @@
 import { api } from '../client.js';
-import { ensureAuthenticated } from '../auth.js';
+import { requireApiKey } from '../auth.js';
 export const listNormsTool = {
     name: 'list_norms',
     description: "List all engineering norms (SIA, Eurocodes, etc.) currently available in Stratta. Returns code, year, title, and language for each. Workflow: call get_methodology FIRST (persona + rules), then list_norms to know what is queryable, then meta-route the user's question to the relevant norms before drilling in.",
@@ -10,9 +10,8 @@ export const listNormsTool = {
     },
 };
 export async function handleListNorms(client) {
-    await ensureAuthenticated(client);
     const result = await client.action(api._mcp.listPublishedNorms, {
-        apiKey: process.env.STRATTA_API_KEY,
+        apiKey: requireApiKey(),
     });
     return { norms: result };
 }

package/dist/tools/search-in-norm.js

@@ -1,5 +1,5 @@
 import { api } from '../client.js';
-import { ensureAuthenticated } from '../auth.js';
+import { requireApiKey } from '../auth.js';
 export const searchInNormTool = {
     name: 'search_in_norm',
     description: 'Search for sections within a norm by keyword (case-insensitive). Returns up to `limit` matches with path, title, and a snippet of matching content. Use this when you do not yet know which section to read — e.g. "charges variables" or "béton armé".',
@@ -21,9 +21,8 @@ export const searchInNormTool = {
     },
 };
 export async function handleSearchInNorm(client, args) {
-    await ensureAuthenticated(client);
     const result = await client.action(api._mcp.searchInNorm, {
-        apiKey: process.env.STRATTA_API_KEY,
+        apiKey: requireApiKey(),
         code: args.norm,
         keyword: args.keyword,
         limit: args.limit,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stratta/mcp",
   "mcpName": "io.github.hugogebel-boop/stratta",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server exposing Swiss engineering norms (SIA / Eurocodes) to Claude clients via Stratta TreeRAG.",
   "license": "UNLICENSED",
   "author": "Hugo Gebel <hugo.gebel@epfl.ch>",