@stratta/mcp 0.9.5 → 0.9.7

package/README.md

@@ -56,6 +56,22 @@ precedence over the saved key):
 claude mcp add stratta --scope user --env STRATTA_API_KEY=sk_strt_xxx -- npx -y @stratta/mcp
 ```
 
+## Commands
+
+| Command                             | Purpose                                            |
+| ----------------------------------- | -------------------------------------------------- |
+| `npx -y @stratta/mcp login`         | Authorise this machine from your browser           |
+| `npx -y @stratta/mcp login --paste` | Paste a key, when there is no browser              |
+| `npx -y @stratta/mcp logout`        | Remove the key stored on this machine              |
+| `npx -y @stratta/mcp whoami`        | Which account and workspace this machine speaks as |
+| `npx -y @stratta/mcp doctor`        | Diagnose an install that is not responding         |
+| `npx -y @stratta/mcp update`        | Check your version and fetch the latest            |
+| `npx -y @stratta/mcp --help`        | All of the above                                   |
+
+Run `doctor` first when norms are missing: a revoked key, a stale
+`STRATTA_API_KEY` in your shell and an unreachable backend all look identical
+from inside the agent, and are fixed differently.
+
 ## Staying up to date
 
 `npx -y @stratta/mcp` fetches the published package, but npx caches what it

package/dist/account.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `whoami` — which account and organisation this machine speaks as.
+ *
+ * Asks the backend rather than reading the file: a key that was revoked from
+ * the dashboard still sits on disk looking perfectly valid, and reporting it
+ * as fine is exactly the wrong answer to "why can't I see my norms?".
+ */
+export declare function runWhoami(): Promise<void>;
+/**
+ * `logout` — remove the stored key.
+ *
+ * Only touches the file. An environment variable is set by whoever set it,
+ * and silently doing nothing about it while claiming to have logged the user
+ * out is how someone ends up convinced the command is broken.
+ */
+export declare function runLogout(): void;

package/dist/account.js

@@ -0,0 +1,81 @@
+import { existsSync, rmSync } from 'node:fs';
+import { CONFIG_PATH, readStoredApiKey } from './config.js';
+import { resolveApiKey } from './auth.js';
+import { api, createConvexClient } from './client.js';
+/** `sk_strt_abcd…` — enough to tell two keys apart, not enough to use one. */
+function mask(key) {
+    return key.length > 12 ? `${key.slice(0, 12)}…` : '…';
+}
+/**
+ * Where the key came from, which is half the answer when the wrong one is in
+ * use: the environment variable wins over the file, so someone who ran
+ * `login` and still sees the old organisation has a stale `STRATTA_API_KEY`
+ * in their shell, not a broken login.
+ */
+function keySource() {
+    if (process.env.STRATTA_API_KEY?.trim())
+        return 'env';
+    if (readStoredApiKey())
+        return 'config';
+    return null;
+}
+/**
+ * `whoami` — which account and organisation this machine speaks as.
+ *
+ * Asks the backend rather than reading the file: a key that was revoked from
+ * the dashboard still sits on disk looking perfectly valid, and reporting it
+ * as fine is exactly the wrong answer to "why can't I see my norms?".
+ */
+export async function runWhoami() {
+    const key = resolveApiKey();
+    if (!key) {
+        console.log('Aucune clé sur cette machine.');
+        console.log('\n  npx -y @stratta/mcp login');
+        process.exitCode = 1;
+        return;
+    }
+    const source = keySource();
+    console.log(`Clé      : ${mask(key)}`);
+    console.log(`Source   : ${source === 'env' ? 'variable STRATTA_API_KEY' : CONFIG_PATH}`);
+    try {
+        const client = createConvexClient();
+        const info = (await client.action(api.apiKeys.describeApiKey, {
+            plaintext: key,
+        }));
+        if (!info.valid) {
+            console.log('\nCette clé n’est plus valide (révoquée, ou compte retiré).');
+            console.log('\n  npx -y @stratta/mcp login');
+            process.exitCode = 1;
+            return;
+        }
+        console.log(`Compte   : ${info.email ?? '—'}`);
+        console.log(`Espace   : ${info.organizationName ?? '—'}`);
+        if (info.keyName)
+            console.log(`Nom      : ${info.keyName}`);
+    }
+    catch {
+        console.log('\nImpossible de joindre Stratta pour vérifier la clé.');
+        process.exitCode = 1;
+    }
+}
+/**
+ * `logout` — remove the stored key.
+ *
+ * Only touches the file. An environment variable is set by whoever set it,
+ * and silently doing nothing about it while claiming to have logged the user
+ * out is how someone ends up convinced the command is broken.
+ */
+export function runLogout() {
+    const hadFile = existsSync(CONFIG_PATH);
+    if (hadFile) {
+        rmSync(CONFIG_PATH, { force: true });
+        console.log(`Clé supprimée de ${CONFIG_PATH}`);
+    }
+    else {
+        console.log('Aucune clé enregistrée sur cette machine.');
+    }
+    if (process.env.STRATTA_API_KEY?.trim()) {
+        console.log('\n⚠ STRATTA_API_KEY est définie dans votre environnement et reste active.\n' +
+            '  Retirez-la de votre shell ou de la configuration de votre agent.');
+    }
+}

package/dist/doctor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `doctor` — everything that has to be true, checked in the order it breaks.
+ *
+ * Written because the failures this product produces are all silent from the
+ * user's side: the agent says a norm is unavailable, and the cause is four
+ * layers away — a revoked key, a stale environment variable, a Python that
+ * was never installed. Each check here corresponds to a real support
+ * question, and each failure carries the command that fixes it.
+ */
+export declare function runDoctor(current: string): Promise<void>;

package/dist/doctor.js

@@ -0,0 +1,134 @@
+import { spawnSync } from 'node:child_process';
+import { CONFIG_PATH, readStoredApiKey } from './config.js';
+import { resolveApiKey } from './auth.js';
+import { api, createConvexClient } from './client.js';
+import { latestPublished, isNewer } from './update.js';
+function line(c) {
+    console.log(`${c.ok ? '✓' : '✗'} ${c.label}${c.detail ? ` — ${c.detail}` : ''}`);
+    if (!c.ok && c.fix)
+        console.log(`    → ${c.fix}`);
+}
+/**
+ * `doctor` — everything that has to be true, checked in the order it breaks.
+ *
+ * Written because the failures this product produces are all silent from the
+ * user's side: the agent says a norm is unavailable, and the cause is four
+ * layers away — a revoked key, a stale environment variable, a Python that
+ * was never installed. Each check here corresponds to a real support
+ * question, and each failure carries the command that fixes it.
+ */
+export async function runDoctor(current) {
+    const checks = [];
+    // Node. The package declares >=20; ingestion tooling assumes a modern one.
+    const major = Number(process.versions.node.split('.')[0]);
+    checks.push({
+        ok: major >= 20,
+        label: 'Node.js',
+        detail: process.versions.node,
+        fix: 'Installez Node 20 ou plus récent : https://nodejs.org',
+    });
+    // The key, and where it comes from — the env var wins, which surprises
+    // people who just ran `login`.
+    const key = resolveApiKey();
+    const fromEnv = !!process.env.STRATTA_API_KEY?.trim();
+    checks.push({
+        ok: !!key,
+        label: 'Clé API',
+        detail: key
+            ? fromEnv
+                ? 'variable STRATTA_API_KEY'
+                : CONFIG_PATH
+            : 'absente',
+        fix: 'npx -y @stratta/mcp login',
+    });
+    if (key && fromEnv && readStoredApiKey()) {
+        checks.push({
+            ok: false,
+            label: 'Deux clés en présence',
+            detail: 'la variable d’environnement masque le fichier',
+            fix: 'Retirez STRATTA_API_KEY si vous vouliez utiliser celle du login',
+        });
+    }
+    // Reachability and validity in one call: a revoked key and an unreachable
+    // backend look identical from the agent's side, and are fixed differently.
+    if (key) {
+        try {
+            const client = createConvexClient();
+            const info = (await client.action(api.apiKeys.describeApiKey, {
+                plaintext: key,
+            }));
+            checks.push({
+                ok: true,
+                label: 'Connexion à Stratta',
+                detail: 'joignable',
+            });
+            checks.push({
+                ok: info.valid,
+                label: 'Clé acceptée',
+                detail: info.valid
+                    ? `${info.email ?? '—'} · ${info.organizationName ?? '—'}`
+                    : 'révoquée ou expirée',
+                fix: 'npx -y @stratta/mcp login',
+            });
+            if (info.valid) {
+                // Its own try: a corpus read failing is a different diagnosis from an
+                // unreachable backend, and folding them together reports "check your
+                // network" to someone whose network is fine.
+                try {
+                    const norms = (await client.action(api._mcp.listPublishedNorms, {
+                        apiKey: key,
+                    }));
+                    const n = Array.isArray(norms) ? norms.length : 0;
+                    checks.push({
+                        ok: n > 0,
+                        label: 'Normes accessibles',
+                        detail: `${n}`,
+                        fix: 'Votre espace est vide — ingérez une norme, ou vérifiez l’organisation ci-dessus',
+                    });
+                }
+                catch (err) {
+                    checks.push({
+                        ok: false,
+                        label: 'Lecture du corpus',
+                        detail: err instanceof Error ? err.message.slice(0, 70) : 'échec',
+                        fix: 'La clé est bonne mais la lecture échoue — signalez-le à hello@stratta.ch',
+                    });
+                }
+            }
+        }
+        catch (err) {
+            checks.push({
+                ok: false,
+                label: 'Connexion à Stratta',
+                detail: err instanceof Error ? err.message.slice(0, 70) : 'échec',
+                fix: 'Vérifiez votre connexion réseau et votre proxy',
+            });
+        }
+    }
+    // Python, needed only for ingestion — a warning, not a failure, since most
+    // people read norms without ever ingesting one.
+    const py = ['python', 'python3'].some((bin) => {
+        const r = spawnSync(bin, ['--version'], { stdio: 'ignore', shell: false });
+        return r.status === 0;
+    });
+    checks.push({
+        ok: py,
+        label: 'Python (ingestion seulement)',
+        detail: py ? 'présent' : 'absent',
+        fix: 'Requis uniquement pour ingérer vos propres normes : https://python.org',
+    });
+    const latest = await latestPublished();
+    checks.push({
+        ok: !latest || !isNewer(latest, current),
+        label: 'Version',
+        detail: latest ? `${current} (dernière : ${latest})` : current,
+        fix: 'npx -y @stratta/mcp update',
+    });
+    checks.forEach(line);
+    const failed = checks.filter((c) => !c.ok);
+    console.log(failed.length === 0
+        ? '\nTout est en ordre.'
+        : `\n${failed.length} point${failed.length > 1 ? 's' : ''} à régler.`);
+    if (failed.length > 0)
+        process.exitCode = 1;
+}

package/dist/index.js

@@ -92,6 +92,38 @@ for (const def of [...readTools, ...dossierTools, ...ingestTools]) {
     // handler receives values that already match the declared shape.
     (args) => call(def, args));
 }
+/**
+ * The help nobody had.
+ *
+ * Every command here existed and was invisible: `login` shipped in 0.9.0 and
+ * did not appear in the app for months, `update` answers a question people
+ * were solving with cache-clearing folklore. A CLI whose only discovery path
+ * is the documentation site has no discovery path.
+ */
+function printHelp() {
+    console.log(`stratta ${packageVersion()} — vos normes dans votre agent
+
+USAGE
+  stratta <commande>              après npm install -g @stratta/mcp
+  npx -y @stratta/mcp <commande>  sans rien installer
+
+COMMANDES
+  login            Autoriser cette machine depuis votre navigateur
+  login --paste    Coller une clé, quand il n'y a pas de navigateur
+  logout           Supprimer la clé enregistrée sur cette machine
+  whoami           Compte et espace de travail utilisés
+  doctor           Diagnostiquer une installation qui ne répond pas
+  update           Vérifier la version et récupérer la dernière
+  --version        Version installée
+  --help           Cet écran
+
+Sans commande, le serveur MCP démarre sur stdio : c'est ce que fait votre
+agent, vous n'avez pas à le lancer vous-même.
+
+  Installation   claude mcp add stratta --scope user -- npx -y @stratta/mcp
+  Raccourci      npm install -g @stratta/mcp   puis   stratta doctor
+  Documentation  https://stratta.ch/docs`);
+}
 async function main() {
     const command = process.argv[2];
     if (command === 'login') {
@@ -99,6 +131,21 @@ async function main() {
         await runLogin(process.argv.slice(3));
         return;
     }
+    if (command === 'logout') {
+        const { runLogout } = await import('./account.js');
+        runLogout();
+        return;
+    }
+    if (command === 'whoami') {
+        const { runWhoami } = await import('./account.js');
+        await runWhoami();
+        return;
+    }
+    if (command === 'doctor') {
+        const { runDoctor } = await import('./doctor.js');
+        await runDoctor(packageVersion());
+        return;
+    }
     if (command === 'update') {
         const { runUpdate } = await import('./update.js');
         await runUpdate(packageVersion());
@@ -110,6 +157,19 @@ async function main() {
         console.log(packageVersion());
         return;
     }
+    if (command === '--help' || command === '-h' || command === 'help') {
+        printHelp();
+        return;
+    }
+    // An unknown word is a typo, not a request to start a server on stdio. Left
+    // unhandled it looks like a hang: the process waits for MCP frames that
+    // never come, and says nothing.
+    if (command && !command.startsWith('-')) {
+        console.error(`Commande inconnue : ${command}\n`);
+        printHelp();
+        process.exitCode = 1;
+        return;
+    }
     await server.connect(new StdioServerTransport());
     // Stderr only; stdout carries the MCP protocol.
     console.error(`[stratta-mcp] v${packageVersion()} listening on stdio`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stratta/mcp",
   "mcpName": "ch.stratta/mcp",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "MCP server exposing the engineering norms your firm is licensed for (SIA / Eurocodes) to any MCP client, via Stratta TreeRAG.",
   "license": "UNLICENSED",
   "author": "SmartFlow <hello@stratta.ch>",
@@ -24,6 +24,7 @@
   "type": "module",
   "main": "dist/index.js",
   "bin": {
+    "stratta": "dist/index.js",
     "stratta-mcp": "dist/index.js"
   },
   "files": [