@flareum/mcp 0.2.1 → 0.2.3

package/README.md

@@ -13,7 +13,7 @@ typing literal values.
 2. Copy the command it shows you. It looks like this:
 
 ```bash
-claude mcp add flareum --env FLAREUM_TOKEN=pk_… -- npx -y @flareum/mcp
+claude mcp add flareum --env FLAREUM_TOKEN=pk_… -- npx -y -p @flareum/mcp flareum-mcp
 ```
 
 3. Run it in **your project's** terminal — the repo where you write CSS/SCSS, not the Flareum repo.
@@ -29,7 +29,7 @@ The key is shown once and cannot be retrieved again. If you lose it, revoke it a
 the newest:
 
 ```bash
-npx -y @flareum/mcp@latest --help
+npx -y -p @flareum/mcp@latest flareum --help
 ```
 
 Naming `@latest` is what refreshes the cache. Then restart your editor session — a running MCP
@@ -39,7 +39,7 @@ Check which version you are actually on:
 
 ```bash
 npm view @flareum/mcp version   # the newest published
-npx -y @flareum/mcp@latest --version
+npx -y -p @flareum/mcp@latest flareum --version
 ```
 
 If you installed it globally instead of through `npx`:
@@ -50,6 +50,24 @@ npm install -g @flareum/mcp@latest
 
 ---
 
+## Removing it
+
+```bash
+claude mcp remove flareum
+```
+
+Run it in the same project directory you added it from — `claude mcp add` registers the server for
+that directory, so a removal elsewhere finds nothing. `claude mcp list` shows what is registered. If
+you added it with `-s user` or `-s project`, pass the same scope to remove it.
+
+That takes the key with it: it lived in the `--env FLAREUM_TOKEN=…` of the entry it just deleted.
+There is nothing else on disk unless you wrote a `.flareum/config.json` yourself.
+
+**The key still works.** Removing the server is a local change — anyone holding that string can
+still read the project's tokens. If it leaked, or the machine is gone, revoke it too.
+
+---
+
 ## What your agent can do with it
 
 Ask in plain language — the agent picks the tool:
@@ -80,8 +98,8 @@ The tools tell an agent what a token is CALLED. The stylesheets that give those
 from a Push, and this fetches them:
 
 ```bash
-npx flareum pull                 # into src/styles/flareum
-npx flareum watch                # and again every time you Push in Flareum
+npx -y -p @flareum/mcp flareum pull    # into src/styles/flareum
+npx -y -p @flareum/mcp flareum watch   # and again every time you Push in Flareum
 ```
 
 Then import them once, in your global stylesheet:
@@ -108,6 +126,40 @@ nothing; only a Push does.
 
 ---
 
+## Revoking a key
+
+A key grants read access to one project's tokens until you revoke it. Revoke as soon as one is
+pasted into a chat, a ticket, a screenshot, or a repository — and when a laptop or a contractor
+leaves.
+
+**1. In Flareum**, open **Project settings → Connect**. Each connected editor is a row showing the
+last four characters of its key, when it was added and when it was last used. Click the delete
+button on the row you want gone.
+
+It takes effect immediately: every later call with that key answers `401`, and the key cannot be
+un-revoked. A revoked row disappears from the list rather than lingering as history — it is not a
+connection any more.
+
+If you cannot tell two rows apart, the key hint matches the last four characters of the key the
+editor is using, and **Last used** tells you which one is live.
+
+**2. On the machine that had it**, remove what is still holding the key — revoking stops it
+working, it does not delete the copy:
+
+```bash
+claude mcp remove flareum        # the entry, and the key inside it
+rm .flareum/config.json          # only if you wrote one by hand
+```
+
+Skip this and everything keeps trying the dead key, which reads as a broken integration rather than
+a revoked one.
+
+**3. To reconnect**, mint a new key from the same Connect screen and run the command it gives you.
+Keys are per editor, not per person — connecting a second machine means minting a second key, so
+losing one never means rotating the other.
+
+---
+
 ## Configuration
 
 | Variable | |
@@ -115,10 +167,24 @@ nothing; only a Push does.
 | `FLAREUM_TOKEN` | **required.** The project is read from the key itself. |
 | `FLAREUM_API` | optional. Defaults to production. Set it to point at a local Flareum. |
 | `FLAREUM_PROJECT` | optional. Overrides the project in the key. |
+| `FLAREUM_OUT` | optional. Where stylesheets are written. Same meaning as `out` in the config file, which it beats. |
+| `FLAREUM_AUTO_PULL` | optional. `off` stops the first-connection pull below. Anything else leaves it on. |
+
+On start it writes `.claude/skills/flareum/` into the working directory — the rules your agent needs
+to apply the tokens correctly. `SKILL.md` is the workflow and the router: how to read a search
+result, and where to go for the area being worked in. Each `references/*.md` beside it is one such
+area — `naming.md` for how a token name is built, `typography.md` for applying a text style with
+its class rather than the mixin behind it. The whole folder is rewritten every run, so do not edit
+it, and it prints where it wrote (or why it could not) on stderr.
+
+On the first connection it also **pulls the stylesheets**, once. It looks for the folder this project
+already keeps its styles in — `src/styles`, `app/styles`, `scss`, and the rest — and writes them to
+`<that folder>/flareum`, falling back to `styles/flareum` in a project that has none. It says on
+stderr where they landed.
 
-On start it writes `.claude/skills/flareum/SKILL.md` into the working directory — the naming rules
-your agent needs to propose a token name correctly. It is regenerated every run, so do not edit it,
-and it prints where it wrote (or why it could not) on stderr.
+It runs only when that folder does not exist yet. After that the files are yours: `flareum pull`
+updates them on demand and `flareum watch` on every Push, both into the same folder. A failed pull
+is reported and nothing else — the token tools work without it. `FLAREUM_AUTO_PULL=off` turns it off.
 
 ---
 
@@ -126,7 +192,7 @@ and it prints where it wrote (or why it could not) on stderr.
 
 | What you see | Cause |
 |---|---|
-| The server fails to connect / closes immediately | The package is not installed. Check `npx -y @flareum/mcp` resolves — if it 404s, it has not been published yet. |
+| The server fails to connect / closes immediately | The package is not installed. Check `npx -y -p @flareum/mcp flareum-mcp` resolves — if it 404s, it has not been published yet. |
 | A command the docs describe is not recognised | `npx` is running a cached older copy. Re-run it as `@latest` — see Updating. |
 | The agent types literal values anyway | The skill did not land. Look for `[flareum] skill written to …` in the MCP server's stderr. |
 | Values labelled with long ids instead of mode names | The Flareum server is older than the client. Restart it. |
@@ -181,7 +247,9 @@ to fetch.
 | `src/tools.ts` | The TEXT each tool returns. This is what the agent reads, so its wording is guarded. |
 | `src/server.ts` | MCP stdio transport. Glue only — no behaviour lives here. |
 | `src/skill.ts` | Writes the skill into the consuming project. |
-| `skill/SKILL.md` | The naming rules shipped to the agent. |
+| `src/first-pull.ts` | Chooses the styles folder, and pulls into it on a first connection. |
+| `skill/SKILL.md` | The router shipped to the agent: the workflow, and where each rule lives. |
+| `skill/references/` | One page per rule area. Every file here must be linked from SKILL.md. |
 
 `server.ts` has no tests because it holds no logic; everything it calls is covered. Imports inside
 the package carry a `.js` extension — TypeScript does not rewrite specifiers, and Node's ESM loader

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { FlareumClient } from './client.js';
+import { FlareumApiError, FlareumClient } from './client.js';
 import { CONFIG_PATH, cliErrorReport, parseArgs, resolveConfig } from './config.js';
-import { pullReport, pullStyles } from './pull.js';
-import { DEFAULT_INTERVAL_MS, watchPublished, watchStartedReport } from './watch.js';
+import { isRetryable, pullReport, pullStyles } from './pull.js';
+import { watchIntervalMs, watchPublished, watchStartedReport } from './watch.js';
 const DEFAULT_OUT = 'src/styles/flareum';
 // Read rather than restated: a hardcoded version is wrong the moment `npm version` runs.
 const VERSION = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version;
@@ -19,28 +19,42 @@ const HELP = `flareum — read a Flareum project's design tokens
 
 The key is taken from --token, then FLAREUM_TOKEN, then "token" in ${CONFIG_PATH}.
 Mint one in the project's Connect screen in Flareum.`;
-const readConfigFile = async () => readFile(join(process.cwd(), CONFIG_PATH), 'utf8').then(JSON.parse).catch(() => null);
-const { command, flags } = parseArgs(process.argv.slice(2));
+// An absent config is normal; one that fails to parse is a typo the user is staring at, and
+// collapsing both to null reported "No Flareum key" about the file holding the key.
+const readConfigFile = async () => {
+    const raw = await readFile(join(process.cwd(), CONFIG_PATH), 'utf8').catch(() => null);
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Could not read ${CONFIG_PATH} — ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
 const COMMANDS = ['pull', 'watch'];
-// Read from flags, not `command`: parseArgs takes every leading `--x` as a flag, so checking the
-// command alone printed the help instead.
-if (flags.version || command === '-v') {
-    console.log(VERSION);
-    process.exit(0);
-}
-if (flags.help || command === '-h') {
-    console.log(HELP);
-    process.exit(0);
-}
-if (!COMMANDS.includes(command)) {
-    console.log(HELP);
-    process.exit(command ? 1 : 0);
-}
+// Everything the user can get wrong lives inside this one try, argument parsing included: a throw
+// above it printed a Node stack trace, which is the failure cliErrorReport exists to prevent.
 try {
+    const { command, flags } = parseArgs(process.argv.slice(2));
+    // Read from flags, not `command`: parseArgs takes every leading `--x` as a flag, so checking the
+    // command alone printed the help instead.
+    if (flags.version || command === '-v') {
+        console.log(VERSION);
+        process.exit(0);
+    }
+    if (flags.help || command === '-h') {
+        console.log(HELP);
+        process.exit(0);
+    }
+    if (!COMMANDS.includes(command)) {
+        console.log(HELP);
+        process.exit(command ? 1 : 0);
+    }
     const config = resolveConfig({ flags, env: process.env, file: await readConfigFile() });
     const outDir = config.out ?? DEFAULT_OUT;
-    const root = resolve(process.cwd(), outDir);
     const client = new FlareumClient({ token: config.token, api: config.api });
+    const root = resolve(process.cwd(), outDir);
     const write = async (path, contents) => {
         const target = join(root, path);
         await mkdir(dirname(target), { recursive: true });
@@ -52,13 +66,30 @@ try {
         return result;
     };
     if (command === 'watch') {
-        const intervalMs = Number(flags.interval) > 0 ? Number(flags.interval) * 1000 : DEFAULT_INTERVAL_MS;
+        const intervalMs = watchIntervalMs(flags.interval);
         console.log(watchStartedReport(outDir, intervalMs));
         let running = true;
         process.on('SIGINT', () => { running = false; console.log('\nStopped watching.'); process.exit(0); });
         await watchPublished({
-            publishedVersion: async () => (await client.files()).publishedVersionId,
-            onPublish: async () => { await runPull(); },
+            // watch treats null as "nothing published yet, wait quietly". Without this the CLI threw
+            // the 409 instead, so a never-pushed project printed an error on every tick forever.
+            publishedVersion: async () => {
+                try {
+                    return (await client.published()).publishedVersionId;
+                }
+                catch (error) {
+                    if (error instanceof FlareumApiError && error.code === 'NOT_PUBLISHED')
+                        return null;
+                    throw error;
+                }
+            },
+            // Throwing is what stops watch marking the version done: a file that failed for a
+            // retryable reason must be fetched again, not skipped until the next push.
+            onPublish: async () => {
+                const result = await runPull();
+                if (isRetryable(result))
+                    throw new Error(`${result.failed.length} file(s) failed — retrying on the next tick.`);
+            },
             onError: error => console.error(error instanceof Error ? error.message : String(error)),
             sleep: ms => new Promise(done => { setTimeout(done, ms); }),
             keepGoing: () => running,

package/dist/client.d.ts

@@ -22,6 +22,7 @@ export declare class FlareumClient {
     catalog(updatedSince?: string): Promise<CatalogResponse>;
     search(query: string, limit?: number): Promise<SearchResponse>;
     /** The stylesheets the last push published. They exist only after a push, never from a save. */
+    published(): Promise<PublishedResponse>;
     files(): Promise<FilesResponse>;
     file(path: string): Promise<string>;
     variable(path: string): Promise<VariableResponse>;
@@ -69,6 +70,9 @@ export type FilesResponse = {
     publishedVersionId: string;
     files: string[];
 };
+export type PublishedResponse = {
+    publishedVersionId: string;
+};
 export type VariableMode = {
     id: string;
     name: string;

package/dist/client.js

@@ -60,6 +60,8 @@ export class FlareumClient {
         const url = `${this.#api}/api/v1/projects/${this.projectId}${path}`;
         const response = await this.#fetch(url, {
             headers: { Authorization: `Bearer ${this.#token}`, Accept: 'text/plain' },
+        }).catch(error => {
+            throw new Error(`Could not reach ${this.#api} — ${error instanceof Error ? error.message : String(error)}`);
         });
         if (response.ok)
             return response.text();
@@ -75,6 +77,19 @@ export class FlareumClient {
         return this.#get('/search', { q: query, ...(limit ? { limit: String(limit) } : {}) });
     }
     /** The stylesheets the last push published. They exist only after a push, never from a save. */
+    // The watch's every-tick question. `/files` answers it too, but lists the whole bucket first — so
+    // ask the cheap endpoint, and fall back for a server older than it.
+    async published() {
+        try {
+            return await this.#get('/published');
+        }
+        catch (error) {
+            if (!(error instanceof FlareumApiError) || error.code !== 'HTTP_404')
+                throw error;
+            const { publishedVersionId } = await this.files();
+            return { publishedVersionId };
+        }
+    }
     files() {
         return this.#get('/files');
     }

package/dist/config.d.ts

@@ -12,6 +12,9 @@ export declare const CONFIG_PATH = ".flareum/config.json";
 export declare class MissingToken extends Error {
     constructor();
 }
+export declare class BareFlag extends Error {
+    constructor(name: string);
+}
 /** A flag beats the environment beats the file — nearest to the command wins. */
 export declare const resolveConfig: ({ flags, env, file }: ConfigSources) => Resolved;
 /** `--out dir --token x` and `--out=dir`, both. Anything else is a positional. */

package/dist/config.js

@@ -11,17 +11,29 @@ export class MissingToken extends Error {
         this.name = 'MissingToken';
     }
 }
+export class BareFlag extends Error {
+    constructor(name) {
+        super(`--${name} needs a value, e.g. --${name} <value> or --${name}=<value>.`);
+        this.name = 'BareFlag';
+    }
+}
 /** A flag beats the environment beats the file — nearest to the command wins. */
 export const resolveConfig = ({ flags, env, file }) => {
     const token = flags.token || env.FLAREUM_TOKEN || file?.token;
     if (!token)
         throw new MissingToken();
+    // The file's host travels only with the file's token. A checked-in config is somebody else's
+    // input, and pointing an ambient FLAREUM_TOKEN at their host is how the key leaves the machine.
+    const fileApi = file?.token && token === file.token ? file.api : undefined;
     return {
         token,
-        api: flags.api || env.FLAREUM_API || file?.api,
+        api: flags.api || env.FLAREUM_API || fileApi,
         out: flags.out || file?.out,
     };
 };
+// Flags that mean nothing without a value. --version / --help are deliberately absent: a bare one
+// is the whole point of them.
+const VALUE_FLAGS = new Set(['out', 'token', 'api', 'interval']);
 /** `--out dir --token x` and `--out=dir`, both. Anything else is a positional. */
 export const parseArgs = (argv) => {
     const flags = {};
@@ -42,6 +54,8 @@ export const parseArgs = (argv) => {
             flags[name] = next;
             i += 1;
         }
+        else if (VALUE_FLAGS.has(name))
+            throw new BareFlag(name);
         else
             flags[name] = 'true';
     }

package/dist/pull.d.ts

@@ -5,8 +5,11 @@ export type PullResult = {
     failed: Array<{
         path: string;
         reason: string;
+        permanent: boolean;
     }>;
 };
 export type Writer = (path: string, contents: string) => Promise<void>;
+export declare const isWritablePath: (path: string) => boolean;
 export declare const pullStyles: (client: Pick<FlareumClient, "files" | "file">, write: Writer) => Promise<PullResult>;
+export declare const isRetryable: ({ failed }: PullResult) => boolean;
 export declare const pullReport: ({ publishedVersionId, written, failed }: PullResult, outDir: string) => string;

package/dist/pull.js

@@ -1,3 +1,15 @@
+const STYLESHEET = /\.s?css$/i;
+// The server says where to write, and a --api flag lets anyone be the server. Refused rather than
+// normalised: repairing a path that climbs out of the output directory is how traversal gets through.
+export const isWritablePath = (path) => {
+    if (!path || !STYLESHEET.test(path))
+        return false;
+    if (path.startsWith('/') || path.includes('\\') || path.includes('\0'))
+        return false;
+    if (/^[a-zA-Z]:/.test(path))
+        return false;
+    return !path.split('/').includes('..');
+};
 // Copies the ARTIFACT a push generated; never rebuilds CSS from the catalog, so a name here and a
 // name the API reports cannot disagree.
 export const pullStyles = async (client, write) => {
@@ -6,15 +18,24 @@ export const pullStyles = async (client, write) => {
     const failed = [];
     for (const path of files)
         try {
+            if (!isWritablePath(path)) {
+                failed.push({ path, reason: 'refused — not a stylesheet inside the output directory',
+                    permanent: true });
+                continue;
+            }
             await write(path, await client.file(path));
             written.push(path);
         }
         catch (error) {
-            // One unreadable file must not lose the rest, and must not be reported as written.
-            failed.push({ path, reason: error instanceof Error ? error.message : String(error) });
+            // One unreadable file must not lose the rest, and must not be reported as written. Marked
+            // retryable: unlike a refusal, a read or write that failed once can succeed next time.
+            failed.push({ path, reason: error instanceof Error ? error.message : String(error),
+                permanent: false });
         }
     return { publishedVersionId, written, failed };
 };
+// A refusal will fail identically forever; anything else is worth another attempt.
+export const isRetryable = ({ failed }) => failed.some(f => !f.permanent);
 export const pullReport = ({ publishedVersionId, written, failed }, outDir) => {
     const lines = [`Pulled ${written.length} stylesheet(s) from version ${publishedVersionId} into ${outDir}`];
     for (const path of written)

package/dist/server.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // Transport glue only. Every behaviour worth guarding lives in client.ts and tools.ts, which have
 // no SDK dependency and are tested without one.
+import { readFileSync } from 'node:fs';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
@@ -12,7 +13,9 @@ const client = new FlareumClient({
     api: process.env.FLAREUM_API,
     projectId: process.env.FLAREUM_PROJECT,
 });
-const server = new Server({ name: 'flareum', version: '0.1.0' }, { capabilities: { tools: {} } });
+// Read, never restated: the hardcoded 0.1.0 kept reporting itself from a 0.2.1 package.
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const server = new Server({ name: 'flareum', version }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {

package/dist/watch.d.ts

@@ -7,5 +7,7 @@ export type WatchDeps = {
     keepGoing: () => boolean;
 };
 export declare const DEFAULT_INTERVAL_MS = 15000;
+export declare const MIN_INTERVAL_MS = 2000;
+export declare const watchIntervalMs: (seconds: string | undefined) => number;
 export declare const watchPublished: ({ publishedVersion, onPublish, onError, sleep, keepGoing }: WatchDeps, intervalMs?: number) => Promise<void>;
 export declare const watchStartedReport: (outDir: string, intervalMs: number) => string;

package/dist/watch.js

@@ -1,4 +1,13 @@
 export const DEFAULT_INTERVAL_MS = 15_000;
+export const MIN_INTERVAL_MS = 2_000;
+// A floor, not a default: `--interval 0.001` asked for a thousand polls a second, which the API
+// answers with 429s rather than data.
+export const watchIntervalMs = (seconds) => {
+    const asked = Number(seconds) * 1000;
+    if (!Number.isFinite(asked) || asked <= 0)
+        return DEFAULT_INTERVAL_MS;
+    return Math.max(asked, MIN_INTERVAL_MS);
+};
 // Re-pulls when the PUBLISHED version changes — a push, never a save, so a designer mid-edit cannot
 // rewrite a file the developer is looking at.
 export const watchPublished = async ({ publishedVersion, onPublish, onError, sleep, keepGoing }, intervalMs = DEFAULT_INTERVAL_MS) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flareum/mcp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Connect a coding agent to a Flareum project's design tokens.",
   "license": "MIT",
   "author": "Flareum",