@stratta/mcp 0.9.4 → 0.9.6

package/README.md

@@ -56,6 +56,36 @@ 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
+resolved, so a server can keep launching a version npm replaced weeks ago with
+nothing to tell you.
+
+```bash
+npx -y @stratta/mcp update
+```
+
+Prints the version you are running and the one npm serves, and fetches the new
+one if they differ. Restart your agent afterwards. The server also mentions it
+on stderr at startup when it notices it is behind.
+
 ### Claude Desktop
 
 Sign in once from a terminal — the desktop app cannot prompt you interactively:

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,15 +92,90 @@ 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-mcp ${packageVersion()} — vos normes dans votre agent
+
+USAGE
+  npx -y @stratta/mcp <commande>
+
+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
+  Documentation  https://stratta.ch/docs`);
+}
 async function main() {
-    if (process.argv[2] === 'login') {
+    const command = process.argv[2];
+    if (command === 'login') {
         const { runLogin } = await import('./login.js');
         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());
+        return;
+    }
+    // `--version` because that is what everyone types first, and because
+    // `update` needs a cheap way to make npx materialise a given version.
+    if (command === '--version' || command === '-v' || command === 'version') {
+        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`);
+    // After connect, never before: the check reaches the network, and a server
+    // that starts slowly because of a version lookup is a worse problem than an
+    // out-of-date one.
+    const { noticeIfOutdated } = await import('./update.js');
+    noticeIfOutdated(packageVersion());
 }
 main().catch((err) => {
     console.error('[stratta-mcp] fatal:', err);

package/dist/update.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What version npm would serve right now, or null if we could not ask.
+ *
+ * Deliberately quiet about failures: this runs on a path where being offline,
+ * behind a proxy, or on a flaky connection is ordinary, and none of that is
+ * worth an error. A missed check is not a problem; a server that refuses to
+ * start because a version check failed would be.
+ */
+export declare function latestPublished(timeoutMs?: number): Promise<string | null>;
+/** Numeric compare, so 0.9.10 sorts above 0.9.9. */
+export declare function isNewer(candidate: string, current: string): boolean;
+/**
+ * Tell the user, on stderr, when they are running something old.
+ *
+ * Fire-and-forget from `main`: the server is already listening by the time
+ * this resolves, so a slow registry delays nothing. stdout carries the MCP
+ * protocol and must stay clean.
+ */
+export declare function noticeIfOutdated(current: string): void;
+/**
+ * `npx @stratta/mcp update`.
+ *
+ * npx caches a resolved package and reuses it, so `npx -y @stratta/mcp` can
+ * keep launching a version that npm replaced weeks ago — the user has no way
+ * to tell, and nothing tells them. This says which version is running, which
+ * one is published, and clears the cache entry so the next launch fetches the
+ * new one.
+ */
+export declare function runUpdate(current: string): Promise<void>;

package/dist/update.js

@@ -0,0 +1,88 @@
+import { spawnSync } from 'node:child_process';
+const REGISTRY = 'https://registry.npmjs.org/@stratta/mcp/latest';
+/**
+ * What version npm would serve right now, or null if we could not ask.
+ *
+ * Deliberately quiet about failures: this runs on a path where being offline,
+ * behind a proxy, or on a flaky connection is ordinary, and none of that is
+ * worth an error. A missed check is not a problem; a server that refuses to
+ * start because a version check failed would be.
+ */
+export async function latestPublished(timeoutMs = 3000) {
+    try {
+        const res = await fetch(REGISTRY, {
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: { accept: 'application/json' },
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return body.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Numeric compare, so 0.9.10 sorts above 0.9.9. */
+export function isNewer(candidate, current) {
+    const a = candidate.split('.').map(Number);
+    const b = current.split('.').map(Number);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x !== y)
+            return x > y;
+    }
+    return false;
+}
+/**
+ * Tell the user, on stderr, when they are running something old.
+ *
+ * Fire-and-forget from `main`: the server is already listening by the time
+ * this resolves, so a slow registry delays nothing. stdout carries the MCP
+ * protocol and must stay clean.
+ */
+export function noticeIfOutdated(current) {
+    void latestPublished().then((latest) => {
+        if (!latest || !isNewer(latest, current))
+            return;
+        console.error(`[stratta-mcp] version ${latest} disponible (vous avez ${current}) — ` +
+            `lancez : npx -y @stratta/mcp update`);
+    });
+}
+/**
+ * `npx @stratta/mcp update`.
+ *
+ * npx caches a resolved package and reuses it, so `npx -y @stratta/mcp` can
+ * keep launching a version that npm replaced weeks ago — the user has no way
+ * to tell, and nothing tells them. This says which version is running, which
+ * one is published, and clears the cache entry so the next launch fetches the
+ * new one.
+ */
+export async function runUpdate(current) {
+    console.log(`Version installée : ${current}`);
+    const latest = await latestPublished(8000);
+    if (!latest) {
+        console.log('Impossible de joindre npm. Vérifiez votre connexion et réessayez.');
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`Dernière publiée  : ${latest}`);
+    if (!isNewer(latest, current)) {
+        console.log('\nVous êtes à jour.');
+        return;
+    }
+    console.log('\nRécupération de la nouvelle version…');
+    // `npx -y pkg@version` bypasses whatever npx had cached for the bare name,
+    // and populates the cache with the new one in the same step.
+    const r = spawnSync(process.platform === 'win32' ? 'npx.cmd' : 'npx', ['-y', `@stratta/mcp@${latest}`, '--version'], { stdio: 'inherit' });
+    if (r.status === 0) {
+        console.log(`\n@stratta/mcp ${latest} est prêt.\n` +
+            'Redémarrez votre agent pour que le serveur reparte sur cette version.');
+    }
+    else {
+        console.log(`\nLa récupération a échoué. À lancer à la main :\n` +
+            `  npx -y @stratta/mcp@${latest}`);
+        process.exitCode = 1;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stratta/mcp",
   "mcpName": "ch.stratta/mcp",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "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>",