@compilr-dev/sdk 0.29.2 → 0.29.3

package/dist/index.d.ts

@@ -109,8 +109,10 @@ export { FileEpisodeStore, EpisodeRecorder, isSignificantWork, extractAffectedFi
 export type { FileEpisodeStoreOptions, EpisodeRecorderConfig, WorkSummaryAnchorConfig, PendingToolSignal, EpisodeFile, } from './episodes/index.js';
 export { resolveNext, evaluateBranchCondition, walkPastBranches, lookupLabel, applyBacktrack, } from './flow-runner/index.js';
 export type { BacktrackResult } from './flow-runner/index.js';
-export { readMCPConfigFile, writeMCPConfigFile, resolveServerEntry, loadMCPServers, saveMCPServerEntry, deleteMCPServerEntry, getServerNames, } from './mcp-config.js';
-export type { MCPServerEntry, MCPConfigFile, ResolvedMCPServer } from './mcp-config.js';
+export { readMCPConfigFile, writeMCPConfigFile, resolveServerEntry, loadMCPServers, saveMCPServerEntry, deleteMCPServerEntry, getServerNames, readMCPConfig, assertWritable, canConnect, } from './mcp-config.js';
+export type { MCPServerEntry, MCPConfigFile, ResolvedMCPServer, MCPConfigRead, ConfigValue, } from './mcp-config.js';
+export { serverHealth, needsAttention, describeHealth, estimateToolTokens, estimateServerCost, formatTokens, disabledTools, isToolEnabled, setToolEnabled, filterMcpToolsByEnablement, isSecretRef, secretRefFor, parseSecretRef, looksLikeSecret, resolveValues, describeMissing, planSecretStorage, toStoredValues, secretRefsOf, } from './mcp/index.js';
+export type { MCPServerHealth, MCPServerState, MCPConnectionStatus, HealthInput, MCPToolShape, ServerCost, SecretRef, ResolveResult, } from './mcp/index.js';
 export { generateProject, isGitConfigured, generateCompilrMd, generateConfigJson, generateReadmeMd, generateCodingStandardsMd, generatePackageJson, generateTsconfig, generateGitignore, generateCompilrMdForImport, detectProjectInfo, detectGitInfo, prettifyName, getLanguageLabel, getFrameworkLabel, validateImportPath, isValidProjectName, projectExists, TECH_STACK_LABELS, CODING_STANDARDS_LABELS, REPO_PATTERN_LABELS, WORKFLOW_VERSION, } from './project-generator/index.js';
 export type { TechStack, CodingStandards, GeneratorRepoPattern, ProjectConfig, GenerationResult, CompilrConfig, DetectedProject, GitInfo, ImportProjectConfig, } from './project-generator/index.js';
 export { readFileTool, writeFileTool, createBashTool, bashTool, bashOutputTool, killShellTool, grepTool, globTool, editTool, todoWriteTool, todoReadTool, createTodoTools, getDefaultTodoStore, TodoStore, webFetchTool, suggestTool, } from '@compilr-dev/agents';

package/dist/index.js

@@ -232,7 +232,9 @@ export { resolveNext, evaluateBranchCondition, walkPastBranches, lookupLabel, ap
 // =============================================================================
 // Shared MCP Configuration
 // =============================================================================
-export { readMCPConfigFile, writeMCPConfigFile, resolveServerEntry, loadMCPServers, saveMCPServerEntry, deleteMCPServerEntry, getServerNames, } from './mcp-config.js';
+export { readMCPConfigFile, writeMCPConfigFile, resolveServerEntry, loadMCPServers, saveMCPServerEntry, deleteMCPServerEntry, getServerNames, readMCPConfig, assertWritable, canConnect, } from './mcp-config.js';
+// MCP — health, per-tool enablement, secrets, cost (mcp-restyling Phase 1)
+export { serverHealth, needsAttention, describeHealth, estimateToolTokens, estimateServerCost, formatTokens, disabledTools, isToolEnabled, setToolEnabled, filterMcpToolsByEnablement, isSecretRef, secretRefFor, parseSecretRef, looksLikeSecret, resolveValues, describeMissing, planSecretStorage, toStoredValues, secretRefsOf, } from './mcp/index.js';
 // =============================================================================
 // Project Generator (templates, scaffolding, detection)
 // =============================================================================

package/dist/mcp/cost.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What a server costs to have configured.
+ *
+ * ⚠️ THE FIGURE THE WHOLE DESIGN TURNS ON. A server's tool descriptions are sent to the model on
+ * every turn whether the tools are called or not — `filesystem` alone is roughly 3.8k tokens of
+ * every agent's context, including a duplicate the server itself marks deprecated. Nothing in the
+ * app has ever said so.
+ *
+ * ⚠️ IT IS AN ESTIMATE AND MUST READ AS ONE. We do not run the provider's tokenizer, and the real
+ * number differs per model. Callers render `~3.0k`, never `3,024`: a figure with no decimals is a
+ * claim about precision we cannot support.
+ */
+export interface MCPToolShape {
+    name: string;
+    description?: string;
+    /** JSON Schema for the tool's arguments. Reaches the model too, so it counts. */
+    inputSchema?: unknown;
+}
+/**
+ * Roughly how many tokens describing this tool costs.
+ *
+ * ⚠️ THE SCHEMA COUNTS. An early version measured the description alone and under-reported badly:
+ * a tool with a one-line summary and fifteen parameters is mostly schema. The name counts too —
+ * it is sent prefixed, as `mcp_<server>_<tool>`.
+ */
+export declare function estimateToolTokens(tool: MCPToolShape, serverName?: string): number;
+export interface ServerCost {
+    /** Tokens for the tools that are actually described to the model. */
+    enabledTokens: number;
+    /** Tokens if every tool were on — the baseline the saving is measured against. */
+    totalTokens: number;
+    enabledCount: number;
+    totalCount: number;
+}
+/**
+ * What this server adds to every agent turn, given which of its tools are on.
+ *
+ * ⚠️ ONE SOURCE, COMPUTED (D-3). The header stat, the row's TOOLS cell, the panel badge and the
+ * document's rail all read this — none of them counts for itself, and no figure is written into
+ * copy. Three of the four defects found while designing this were a number stated in one place
+ * while the truth lived in another.
+ */
+export declare function estimateServerCost(tools: readonly MCPToolShape[], isEnabled: (toolName: string) => boolean, serverName?: string): ServerCost;
+/**
+ * `~3.0k`, `~840`, `—`.
+ *
+ * The dash is for genuinely nothing — a tool that is off, or a server we cannot ask. It is not the
+ * same as `~0`, which would claim we measured and found zero.
+ */
+export declare function formatTokens(tokens: number | null): string;

package/dist/mcp/cost.js

@@ -0,0 +1,69 @@
+/**
+ * What a server costs to have configured.
+ *
+ * ⚠️ THE FIGURE THE WHOLE DESIGN TURNS ON. A server's tool descriptions are sent to the model on
+ * every turn whether the tools are called or not — `filesystem` alone is roughly 3.8k tokens of
+ * every agent's context, including a duplicate the server itself marks deprecated. Nothing in the
+ * app has ever said so.
+ *
+ * ⚠️ IT IS AN ESTIMATE AND MUST READ AS ONE. We do not run the provider's tokenizer, and the real
+ * number differs per model. Callers render `~3.0k`, never `3,024`: a figure with no decimals is a
+ * claim about precision we cannot support.
+ */
+/** Chars per token. Four is the long-standing rule of thumb for English prose and code. */
+const CHARS_PER_TOKEN = 4;
+/**
+ * Roughly how many tokens describing this tool costs.
+ *
+ * ⚠️ THE SCHEMA COUNTS. An early version measured the description alone and under-reported badly:
+ * a tool with a one-line summary and fifteen parameters is mostly schema. The name counts too —
+ * it is sent prefixed, as `mcp_<server>_<tool>`.
+ */
+export function estimateToolTokens(tool, serverName = '') {
+    const prefixed = serverName === '' ? tool.name : `mcp_${serverName}_${tool.name}`;
+    let chars = prefixed.length + (tool.description ?? '').length;
+    if (tool.inputSchema !== undefined) {
+        try {
+            chars += JSON.stringify(tool.inputSchema).length;
+        }
+        catch {
+            /* circular or unserialisable — the rest of the estimate still stands */
+        }
+    }
+    return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+/**
+ * What this server adds to every agent turn, given which of its tools are on.
+ *
+ * ⚠️ ONE SOURCE, COMPUTED (D-3). The header stat, the row's TOOLS cell, the panel badge and the
+ * document's rail all read this — none of them counts for itself, and no figure is written into
+ * copy. Three of the four defects found while designing this were a number stated in one place
+ * while the truth lived in another.
+ */
+export function estimateServerCost(tools, isEnabled, serverName = '') {
+    let enabledTokens = 0;
+    let totalTokens = 0;
+    let enabledCount = 0;
+    for (const tool of tools) {
+        const cost = estimateToolTokens(tool, serverName);
+        totalTokens += cost;
+        if (isEnabled(tool.name)) {
+            enabledTokens += cost;
+            enabledCount++;
+        }
+    }
+    return { enabledTokens, totalTokens, enabledCount, totalCount: tools.length };
+}
+/**
+ * `~3.0k`, `~840`, `—`.
+ *
+ * The dash is for genuinely nothing — a tool that is off, or a server we cannot ask. It is not the
+ * same as `~0`, which would claim we measured and found zero.
+ */
+export function formatTokens(tokens) {
+    if (tokens === null)
+        return '—';
+    if (tokens < 1000)
+        return `~${String(tokens)}`;
+    return `~${(tokens / 1000).toFixed(1)}k`;
+}

package/dist/mcp/health.d.ts

@@ -0,0 +1,61 @@
+/**
+ * What state an MCP server is actually in.
+ *
+ * ⚠️ THE DEFECT THIS MODULE EXISTS TO END. Desktop rendered a green dot and counted a server as
+ * "active" from `entry.disabled` — a CONFIGURATION flag. Whether a server is switched on and
+ * whether it answers are different questions, and the app was answering the second with the first.
+ * A server whose token had expired looked identical to a working one until an agent called it and
+ * the error surfaced mid-conversation.
+ *
+ * So every state here names what it was derived from, and there is a state for **not knowing**.
+ * Guessing green is how we got here (D-1).
+ */
+/** What the connection layer reports. Mirrors `MCPClient.status` in @compilr-dev/agents. */
+export type MCPConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+export type MCPServerState = 
+/** The user switched it off. Config, not connection. */
+'off'
+/** We hold a live client. */
+ | 'connected'
+/** We tried and it did not work. Carries a reason. */
+ | 'failing'
+/** We have not tried yet — no client exists. NEVER rendered as connected. */
+ | 'unknown';
+export interface MCPServerHealth {
+    state: MCPServerState;
+    /** Why it is failing, in the server's own words where we have them. */
+    reason: string | null;
+    /**
+     * ISO timestamp of the last successful connection, or null if it has never connected.
+     *
+     * ⚠️ ONE TIMESTAMP, NOT A HISTORY (D-6). The design asked for "every call has failed for 3 days";
+     * that is a count nothing records, and writing it anyway would be a claim with no measurement
+     * behind it — the same defect as the green dot, in prose.
+     */
+    lastConnectedAt: string | null;
+}
+export interface HealthInput {
+    /** `entry.disabled` from mcp.json. */
+    disabled?: boolean;
+    /** The live client's status, or null when no client exists for this server. */
+    status?: MCPConnectionStatus | null;
+    /** The last error we captured for it. */
+    error?: string | null;
+    lastConnectedAt?: string | null;
+}
+/**
+ * Derive a server's health from what we observed.
+ *
+ * `disabled` wins: a server the user switched off is `off` whatever a stale client says, because
+ * that is the state they chose. Everything else follows the connection.
+ */
+export declare function serverHealth(input: HealthInput): MCPServerHealth;
+/** Does this state need the user's attention? Drives the amber row and the panel icon. */
+export declare function needsAttention(health: MCPServerHealth): boolean;
+/**
+ * One line for the health strip and the list row.
+ *
+ * ⚠️ SAYS ONLY WHAT WE STORED. No counts, no durations — we keep one timestamp (D-6). Callers
+ * render the date; formatting is presentation and differs between a terminal and a window.
+ */
+export declare function describeHealth(health: MCPServerHealth): string;

package/dist/mcp/health.js

@@ -0,0 +1,64 @@
+/**
+ * What state an MCP server is actually in.
+ *
+ * ⚠️ THE DEFECT THIS MODULE EXISTS TO END. Desktop rendered a green dot and counted a server as
+ * "active" from `entry.disabled` — a CONFIGURATION flag. Whether a server is switched on and
+ * whether it answers are different questions, and the app was answering the second with the first.
+ * A server whose token had expired looked identical to a working one until an agent called it and
+ * the error surfaced mid-conversation.
+ *
+ * So every state here names what it was derived from, and there is a state for **not knowing**.
+ * Guessing green is how we got here (D-1).
+ */
+/**
+ * Derive a server's health from what we observed.
+ *
+ * `disabled` wins: a server the user switched off is `off` whatever a stale client says, because
+ * that is the state they chose. Everything else follows the connection.
+ */
+export function serverHealth(input) {
+    const lastConnectedAt = input.lastConnectedAt ?? null;
+    const reason = input.error ?? null;
+    if (input.disabled === true)
+        return { state: 'off', reason: null, lastConnectedAt };
+    switch (input.status) {
+        case 'connected':
+            return { state: 'connected', reason: null, lastConnectedAt };
+        case 'error':
+            return { state: 'failing', reason, lastConnectedAt };
+        case 'connecting':
+        case 'disconnected':
+        case null:
+        case undefined:
+            /*
+              ⚠️ `disconnected` IS NOT `off`. It means we have a client that is not currently connected —
+              we do not know whether the server would answer. The user did not ask for this state and
+              must not be told the server is fine.
+            */
+            return { state: 'unknown', reason, lastConnectedAt };
+    }
+}
+/** Does this state need the user's attention? Drives the amber row and the panel icon. */
+export function needsAttention(health) {
+    return health.state === 'failing';
+}
+/**
+ * One line for the health strip and the list row.
+ *
+ * ⚠️ SAYS ONLY WHAT WE STORED. No counts, no durations — we keep one timestamp (D-6). Callers
+ * render the date; formatting is presentation and differs between a terminal and a window.
+ */
+export function describeHealth(health) {
+    switch (health.state) {
+        case 'off':
+            return 'Switched off. Its tools are not offered to any agent.';
+        case 'connected':
+            return 'Connected.';
+        case 'failing':
+            return health.reason ?? 'The last connection attempt failed.';
+        case 'unknown':
+            return health.lastConnectedAt === null
+                ? 'Not connected yet — it starts when an agent first needs it.'
+                : 'Not connected right now.';
+    }
+}

package/dist/mcp/index.d.ts

@@ -0,0 +1,5 @@
+/** MCP: health, per-tool enablement, secret references and context cost. */
+export { serverHealth, needsAttention, describeHealth, type MCPServerHealth, type MCPServerState, type MCPConnectionStatus, type HealthInput, } from './health.js';
+export { estimateToolTokens, estimateServerCost, formatTokens, type MCPToolShape, type ServerCost, } from './cost.js';
+export { disabledTools, isToolEnabled, setToolEnabled, filterMcpToolsByEnablement, } from './tools.js';
+export { isSecretRef, secretRefFor, parseSecretRef, looksLikeSecret, resolveValues, describeMissing, planSecretStorage, toStoredValues, secretRefsOf, type SecretRef, type ConfigValue, type ResolveResult, } from './secrets.js';

package/dist/mcp/index.js

@@ -0,0 +1,5 @@
+/** MCP: health, per-tool enablement, secret references and context cost. */
+export { serverHealth, needsAttention, describeHealth, } from './health.js';
+export { estimateToolTokens, estimateServerCost, formatTokens, } from './cost.js';
+export { disabledTools, isToolEnabled, setToolEnabled, filterMcpToolsByEnablement, } from './tools.js';
+export { isSecretRef, secretRefFor, parseSecretRef, looksLikeSecret, resolveValues, describeMissing, planSecretStorage, toStoredValues, secretRefsOf, } from './secrets.js';

package/dist/mcp/secrets.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Keeping credentials out of mcp.json.
+ *
+ * ⚠️ THE APP CURRENTLY TEACHES THE OPPOSITE. The environment field's own placeholder is
+ * `{"GITHUB_TOKEN": "ghp_..."}` — so the UI instructs you to paste a live token into a plain file
+ * that is shared with @compilr-dev/cli and sits in a directory people copy between machines and
+ * occasionally paste into a gist.
+ *
+ * A value becomes a REFERENCE in the file; the secret itself goes to the host's encrypted store
+ * (Desktop already has one: Electron safeStorage with an AES-256-GCM fallback, shipping for API
+ * keys). Non-secret settings stay as plain strings where they can be read and diffed.
+ *
+ * ⚠️ THE FILE IS SHARED, SO THIS MUST DEGRADE LOUDLY. A host that cannot resolve a reference must
+ * say which variable and where it lives — never pass an empty string to the server, which produces
+ * a 401 the user cannot explain and we cannot distinguish from a genuinely bad token.
+ */
+import type { MCPServerEntry } from '../mcp-config.js';
+/** What sits in mcp.json in place of a secret. */
+export interface SecretRef {
+    secret: string;
+}
+export type ConfigValue = string | SecretRef;
+export declare function isSecretRef(value: unknown): value is SecretRef;
+/**
+ * The key a secret is stored under: `mcp:<server>:<variable>`.
+ *
+ * Namespaced by server so two servers may each hold a `GITHUB_TOKEN` without collision — which is
+ * the normal case, not an edge one.
+ */
+export declare function secretRefFor(server: string, variable: string): SecretRef;
+/** Parse a reference back into its parts, or null if it is not one of ours. */
+export declare function parseSecretRef(ref: string): {
+    server: string;
+    variable: string;
+} | null;
+/**
+ * Does this look like something that should not sit in a plain file?
+ *
+ * Deliberately conservative and advisory only — it drives an OFFER ("store this in the keychain?"),
+ * never an automatic rewrite. Guessing wrong in the cautious direction costs a click; guessing
+ * wrong the other way writes a token to disk.
+ */
+export declare function looksLikeSecret(variable: string, value: string): boolean;
+export interface ResolveResult {
+    /** Ready to hand to the server. Only present when `missing` is empty. */
+    values: Record<string, string>;
+    /** References we could not resolve, by variable name. */
+    missing: {
+        variable: string;
+        ref: string;
+    }[];
+}
+/**
+ * Turn a stored map into real values, resolving any references through the host's store.
+ *
+ * ⚠️ MISSING SECRETS ARE REPORTED, NEVER SUBSTITUTED. Returning `''` for an unresolvable reference
+ * is what turns a configuration problem into an authentication error three layers away.
+ */
+export declare function resolveValues(stored: Record<string, ConfigValue> | undefined, lookup: (ref: string) => string | null): ResolveResult;
+/** One sentence per unresolvable reference, naming the variable and where the value belongs. */
+export declare function describeMissing(server: string, missing: ResolveResult['missing']): string[];
+/**
+ * Split a pasted plain-text map into what should be stored where.
+ *
+ * Used by the paste-config route to tell the user what will happen BEFORE anything is written.
+ */
+export declare function planSecretStorage(server: string, plain: Record<string, string>): {
+    variable: string;
+    value: string;
+    toKeychain: boolean;
+    ref: SecretRef | null;
+}[];
+/** The map as it should be WRITTEN to mcp.json: secrets as references, the rest verbatim. */
+export declare function toStoredValues(plan: ReturnType<typeof planSecretStorage>): Record<string, ConfigValue>;
+/** Every secret reference an entry holds, for cleanup when a server is deleted. */
+export declare function secretRefsOf(entry: Pick<MCPServerEntry, 'env' | 'headers'>): string[];

package/dist/mcp/secrets.js

@@ -0,0 +1,119 @@
+/**
+ * Keeping credentials out of mcp.json.
+ *
+ * ⚠️ THE APP CURRENTLY TEACHES THE OPPOSITE. The environment field's own placeholder is
+ * `{"GITHUB_TOKEN": "ghp_..."}` — so the UI instructs you to paste a live token into a plain file
+ * that is shared with @compilr-dev/cli and sits in a directory people copy between machines and
+ * occasionally paste into a gist.
+ *
+ * A value becomes a REFERENCE in the file; the secret itself goes to the host's encrypted store
+ * (Desktop already has one: Electron safeStorage with an AES-256-GCM fallback, shipping for API
+ * keys). Non-secret settings stay as plain strings where they can be read and diffed.
+ *
+ * ⚠️ THE FILE IS SHARED, SO THIS MUST DEGRADE LOUDLY. A host that cannot resolve a reference must
+ * say which variable and where it lives — never pass an empty string to the server, which produces
+ * a 401 the user cannot explain and we cannot distinguish from a genuinely bad token.
+ */
+export function isSecretRef(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'secret' in value &&
+        typeof value.secret === 'string');
+}
+/**
+ * The key a secret is stored under: `mcp:<server>:<variable>`.
+ *
+ * Namespaced by server so two servers may each hold a `GITHUB_TOKEN` without collision — which is
+ * the normal case, not an edge one.
+ */
+export function secretRefFor(server, variable) {
+    return { secret: `mcp:${server}:${variable}` };
+}
+/** Parse a reference back into its parts, or null if it is not one of ours. */
+export function parseSecretRef(ref) {
+    const parts = ref.split(':');
+    if (parts.length !== 3 || parts[0] !== 'mcp')
+        return null;
+    if (parts[1] === '' || parts[2] === '')
+        return null;
+    return { server: parts[1], variable: parts[2] };
+}
+/**
+ * Does this look like something that should not sit in a plain file?
+ *
+ * Deliberately conservative and advisory only — it drives an OFFER ("store this in the keychain?"),
+ * never an automatic rewrite. Guessing wrong in the cautious direction costs a click; guessing
+ * wrong the other way writes a token to disk.
+ */
+export function looksLikeSecret(variable, value) {
+    if (/^(ghp|gho|ghs|ghu|github_pat|sk-|xoxb-|xoxp-|AKIA|glpat-|pat_)/i.test(value))
+        return true;
+    if (/^Bearer\s+\S+/i.test(value))
+        return true;
+    if (/(token|secret|password|passwd|api[-_]?key|credential|auth)/i.test(variable)) {
+        // A name that sounds secret plus a value long enough to be one. `TOKEN_PATH=/tmp/t` is not.
+        return value.length >= 16 && !value.startsWith('/') && !value.startsWith('~');
+    }
+    // A long opaque run of base64/hex with no spaces or path separators.
+    return value.length >= 32 && /^[A-Za-z0-9_\-.+/=]+$/.test(value) && !value.includes('/');
+}
+/**
+ * Turn a stored map into real values, resolving any references through the host's store.
+ *
+ * ⚠️ MISSING SECRETS ARE REPORTED, NEVER SUBSTITUTED. Returning `''` for an unresolvable reference
+ * is what turns a configuration problem into an authentication error three layers away.
+ */
+export function resolveValues(stored, lookup) {
+    const values = {};
+    const missing = [];
+    for (const [variable, value] of Object.entries(stored ?? {})) {
+        if (typeof value === 'string') {
+            values[variable] = value;
+            continue;
+        }
+        const found = lookup(value.secret);
+        if (found === null)
+            missing.push({ variable, ref: value.secret });
+        else
+            values[variable] = found;
+    }
+    return { values, missing };
+}
+/** One sentence per unresolvable reference, naming the variable and where the value belongs. */
+export function describeMissing(server, missing) {
+    return missing.map((m) => `${m.variable} for ${server} is stored as a reference (${m.ref}) but no value was found. Open the server and set it again — it is kept in this machine's keychain, not in mcp.json, so it does not travel with the file.`);
+}
+/**
+ * Split a pasted plain-text map into what should be stored where.
+ *
+ * Used by the paste-config route to tell the user what will happen BEFORE anything is written.
+ */
+export function planSecretStorage(server, plain) {
+    return Object.entries(plain).map(([variable, value]) => {
+        const toKeychain = looksLikeSecret(variable, value);
+        return {
+            variable,
+            value,
+            toKeychain,
+            ref: toKeychain ? secretRefFor(server, variable) : null,
+        };
+    });
+}
+/** The map as it should be WRITTEN to mcp.json: secrets as references, the rest verbatim. */
+export function toStoredValues(plan) {
+    const out = {};
+    for (const item of plan)
+        out[item.variable] = item.ref ?? item.value;
+    return out;
+}
+/** Every secret reference an entry holds, for cleanup when a server is deleted. */
+export function secretRefsOf(entry) {
+    const refs = [];
+    for (const map of [entry.env, entry.headers]) {
+        for (const value of Object.values(map ?? {})) {
+            if (isSecretRef(value))
+                refs.push(value.secret);
+        }
+    }
+    return refs;
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Which of a server's tools are described to the model.
+ *
+ * ⚠️ OFF MEANS NOT DESCRIBED — NEVER REMOVED (D-7). The tool stays on the server and stays callable
+ * by anything else pointed at it. We are choosing what goes into the model's context, and the copy
+ * must not imply we uninstalled anything.
+ *
+ * Stored as an OPT-OUT list, deliberately: a server that gains a tool in a later release has it
+ * enabled by default, which is what someone who never touched this screen expects. An opt-in list
+ * would silently hide every new tool and look like the server had stopped offering them.
+ */
+import type { MCPServerEntry } from '../mcp-config.js';
+/** Tools explicitly switched off for this server. Absent means "all of them are on". */
+export declare function disabledTools(entry: Pick<MCPServerEntry, 'disabledTools'>): readonly string[];
+export declare function isToolEnabled(entry: Pick<MCPServerEntry, 'disabledTools'>, toolName: string): boolean;
+/**
+ * The entry with one tool switched on or off.
+ *
+ * Returns a NEW entry; the caller writes it. Switching the last one back on removes the key
+ * entirely rather than leaving `"disabledTools": []` behind, so a file nobody has customised stays
+ * clean and diffs stay small.
+ */
+export declare function setToolEnabled(entry: MCPServerEntry, toolName: string, enabled: boolean): MCPServerEntry;
+/**
+ * Drop the tools this server has switched off.
+ *
+ * ⚠️ MUST BE APPLIED ON EVERY PATH THAT REGISTERS MCP TOOLS. There are two in Desktop — the agent
+ * factory, and the post-connect catch-up for agents built before MCP finished connecting. The same
+ * split already bit MCP grants: filtering one path leaves the feature working except during
+ * startup, which is the same as not working.
+ *
+ * Shaped like `filterMcpToolsByGrant` so the two compose over the same array.
+ */
+export declare function filterMcpToolsByEnablement<T extends {
+    definition: {
+        name: string;
+    };
+}>(tools: readonly T[], serverOf: (toolName: string) => string | null, entryOf: (server: string) => Pick<MCPServerEntry, 'disabledTools'> | undefined, 
+/** Strip the `mcp_<server>_` prefix to get the name the server itself uses. */
+bareName: (toolName: string, server: string) => string): T[];

package/dist/mcp/tools.js

@@ -0,0 +1,61 @@
+/**
+ * Which of a server's tools are described to the model.
+ *
+ * ⚠️ OFF MEANS NOT DESCRIBED — NEVER REMOVED (D-7). The tool stays on the server and stays callable
+ * by anything else pointed at it. We are choosing what goes into the model's context, and the copy
+ * must not imply we uninstalled anything.
+ *
+ * Stored as an OPT-OUT list, deliberately: a server that gains a tool in a later release has it
+ * enabled by default, which is what someone who never touched this screen expects. An opt-in list
+ * would silently hide every new tool and look like the server had stopped offering them.
+ */
+/** Tools explicitly switched off for this server. Absent means "all of them are on". */
+export function disabledTools(entry) {
+    return entry.disabledTools ?? [];
+}
+export function isToolEnabled(entry, toolName) {
+    return !disabledTools(entry).includes(toolName);
+}
+/**
+ * The entry with one tool switched on or off.
+ *
+ * Returns a NEW entry; the caller writes it. Switching the last one back on removes the key
+ * entirely rather than leaving `"disabledTools": []` behind, so a file nobody has customised stays
+ * clean and diffs stay small.
+ */
+export function setToolEnabled(entry, toolName, enabled) {
+    const current = new Set(disabledTools(entry));
+    if (enabled)
+        current.delete(toolName);
+    else
+        current.add(toolName);
+    const next = { ...entry };
+    if (current.size === 0)
+        delete next.disabledTools;
+    else
+        next.disabledTools = [...current].sort();
+    return next;
+}
+/**
+ * Drop the tools this server has switched off.
+ *
+ * ⚠️ MUST BE APPLIED ON EVERY PATH THAT REGISTERS MCP TOOLS. There are two in Desktop — the agent
+ * factory, and the post-connect catch-up for agents built before MCP finished connecting. The same
+ * split already bit MCP grants: filtering one path leaves the feature working except during
+ * startup, which is the same as not working.
+ *
+ * Shaped like `filterMcpToolsByGrant` so the two compose over the same array.
+ */
+export function filterMcpToolsByEnablement(tools, serverOf, entryOf, 
+/** Strip the `mcp_<server>_` prefix to get the name the server itself uses. */
+bareName) {
+    return tools.filter((tool) => {
+        const server = serverOf(tool.definition.name);
+        if (server === null)
+            return true;
+        const entry = entryOf(server);
+        if (!entry)
+            return true;
+        return isToolEnabled(entry, bareName(tool.definition.name, server));
+    });
+}

package/dist/mcp-config.d.ts

@@ -7,6 +7,8 @@
  * File structure:
  *   { "mcpServers": { "name": { command?, url?, ... } } }
  */
+import { type ConfigValue } from './mcp/secrets.js';
+export type { ConfigValue };
 /**
  * Single MCP server entry in the config file.
  * If `command` is present → stdio transport.
@@ -15,12 +17,28 @@
 export interface MCPServerEntry {
     command?: string;
     args?: string[];
-    env?: Record<string, string>;
+    /**
+     * Passed to the process on start.
+     *
+     * ⚠️ A VALUE MAY BE A REFERENCE, NOT A STRING. `{ secret: 'mcp:github:GITHUB_TOKEN' }` means the
+     * real value lives in the host's encrypted store and never in this file — see `src/mcp/secrets`.
+     * Resolve with {@link resolveServerEntry} before handing anything to a server.
+     */
+    env?: Record<string, ConfigValue>;
     cwd?: string;
     url?: string;
-    headers?: Record<string, string>;
+    /** Same reference rule as {@link MCPServerEntry.env}. */
+    headers?: Record<string, ConfigValue>;
     disabled?: boolean;
     timeout?: number;
+    /**
+     * Tools NOT described to the model, by the server's own name for them.
+     *
+     * ⚠️ AN OPT-OUT LIST, SO A SERVER THAT GAINS A TOOL HAS IT ON. An opt-in list would silently hide
+     * every tool added by a later release. Absent means all tools are on. The tools stay on the
+     * server either way — this only decides what reaches the model's context.
+     */
+    disabledTools?: string[];
 }
 /**
  * Shape of the mcp.json config file.
@@ -41,11 +59,52 @@ export interface ResolvedMCPServer {
     url?: string;
     headers?: Record<string, string>;
     timeout?: number;
+    /**
+     * Secret references that could not be resolved. Non-empty means DO NOT CONNECT — see
+     * {@link canConnect}. The variables are named so a host can say which one and where it lives.
+     */
+    missingSecrets?: {
+        variable: string;
+        ref: string;
+    }[];
 }
+/**
+ * The outcome of reading an mcp.json, with "absent" kept distinct from "unreadable".
+ *
+ * ⚠️ THOSE TWO CANNOT SHARE AN ANSWER. Collapsing them to `{}` is what made adding a server to a
+ * hand-edited file DELETE the servers already in it — see {@link assertWritable}.
+ */
+export interface MCPConfigRead {
+    servers: Record<string, MCPServerEntry>;
+    /** Present when the file exists but could not be parsed. The servers are then unknown, not none. */
+    error: string | null;
+    exists: boolean;
+}
+/**
+ * Read an mcp.json, saying which of the three things happened: absent, readable, or broken.
+ *
+ * Prefer this over {@link readMCPConfigFile} anywhere the result could lead to a WRITE.
+ */
+export declare function readMCPConfig(filePath: string): MCPConfigRead;
 /**
  * Read and parse an mcp.json file. Returns empty record on any error.
+ *
+ * ⚠️ LENIENT, AND ONLY SAFE FOR READING. It cannot tell an absent file from a broken one. Use
+ * {@link readMCPConfig} when the answer might be written back.
  */
 export declare function readMCPConfigFile(filePath: string): Record<string, MCPServerEntry>;
+/**
+ * Throw unless this file can be safely rewritten.
+ *
+ * ⚠️ THE DATA-LOSS BUG THIS EXISTS FOR, MEASURED. `readMCPConfigFile` returns `{}` for a file it
+ * cannot parse. `saveMCPServerEntry` then wrote `{}` plus the one new server — so a user whose
+ * mcp.json had a comment in it saw no servers in the app, added one, and **lost the other two**.
+ * Silence, then deletion.
+ *
+ * A file we cannot read is a file we must not overwrite. The host shows the reason and the user
+ * fixes their file; we do not guess at its contents.
+ */
+export declare function assertWritable(filePath: string): Record<string, MCPServerEntry>;
 /**
  * Write servers to an mcp.json file (creates directory if needed).
  */
@@ -53,8 +112,19 @@ export declare function writeMCPConfigFile(filePath: string, servers: Record<str
 /**
  * Convert an MCPServerEntry to a ResolvedMCPServer.
  * Returns null if the entry is invalid (neither command nor url) or disabled.
+ *
+ * ⚠️ SECRET REFERENCES NEED `lookup`. Without one, a referenced value cannot be resolved and is
+ * reported in `missingSecrets` — it is never substituted with an empty string, because that turns
+ * a configuration problem into a 401 three layers away that nobody can trace back.
+ */
+export declare function resolveServerEntry(name: string, entry: MCPServerEntry, lookup?: (ref: string) => string | null): ResolvedMCPServer | null;
+/**
+ * Can this server be started without handing it a credential we could not find?
+ *
+ * Hosts check this before connecting. Connecting anyway produces an authentication failure that
+ * looks like a bad token rather than a missing one.
  */
-export declare function resolveServerEntry(name: string, entry: MCPServerEntry): ResolvedMCPServer | null;
+export declare function canConnect(server: ResolvedMCPServer): boolean;
 /**
  * Load and resolve MCP servers from one or more config file paths.
  * Later paths override earlier ones (by server name).

package/dist/mcp-config.js

@@ -9,26 +9,76 @@
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { dirname } from 'path';
-// =============================================================================
-// File I/O
-// =============================================================================
+import { resolveValues } from './mcp/secrets.js';
 /**
- * Read and parse an mcp.json file. Returns empty record on any error.
+ * Read an mcp.json, saying which of the three things happened: absent, readable, or broken.
+ *
+ * Prefer this over {@link readMCPConfigFile} anywhere the result could lead to a WRITE.
  */
-export function readMCPConfigFile(filePath) {
+export function readMCPConfig(filePath) {
+    if (!existsSync(filePath))
+        return { servers: {}, error: null, exists: false };
+    let data;
     try {
-        if (!existsSync(filePath))
-            return {};
-        const data = readFileSync(filePath, 'utf-8');
-        const parsed = JSON.parse(data);
-        if (parsed.mcpServers && typeof parsed.mcpServers === 'object') {
-            return parsed.mcpServers;
-        }
-        return {};
+        data = readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        return { servers: {}, exists: true, error: `could not be read: ${String(err)}` };
     }
-    catch {
-        return {};
+    /*
+      An empty or whitespace-only file is a normal state — an editor that saved nothing, or a file
+      someone cleared — and treating it as corrupt would block every future write.
+    */
+    if (data.trim() === '')
+        return { servers: {}, error: null, exists: true };
+    let parsed;
+    try {
+        parsed = JSON.parse(data);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        /*
+          Comments are the common cause and worth naming: mcp.json looks like a config file people may
+          annotate, and every editor that speaks JSONC encourages it. Strict JSON is what the format is,
+          so we refuse clearly instead of stripping them — stripping would drop them on the next write.
+        */
+        const hint = /^\s*\/\/|\n\s*\/\/|\/\*/.test(data)
+            ? ' It looks like it contains comments; mcp.json must be strict JSON.'
+            : '';
+        return { servers: {}, exists: true, error: `is not valid JSON (${detail}).${hint}` };
     }
+    if (!parsed.mcpServers || typeof parsed.mcpServers !== 'object') {
+        // A valid JSON document with no `mcpServers` key is empty, not broken.
+        return { servers: {}, error: null, exists: true };
+    }
+    return { servers: parsed.mcpServers, error: null, exists: true };
+}
+/**
+ * Read and parse an mcp.json file. Returns empty record on any error.
+ *
+ * ⚠️ LENIENT, AND ONLY SAFE FOR READING. It cannot tell an absent file from a broken one. Use
+ * {@link readMCPConfig} when the answer might be written back.
+ */
+export function readMCPConfigFile(filePath) {
+    return readMCPConfig(filePath).servers;
+}
+/**
+ * Throw unless this file can be safely rewritten.
+ *
+ * ⚠️ THE DATA-LOSS BUG THIS EXISTS FOR, MEASURED. `readMCPConfigFile` returns `{}` for a file it
+ * cannot parse. `saveMCPServerEntry` then wrote `{}` plus the one new server — so a user whose
+ * mcp.json had a comment in it saw no servers in the app, added one, and **lost the other two**.
+ * Silence, then deletion.
+ *
+ * A file we cannot read is a file we must not overwrite. The host shows the reason and the user
+ * fixes their file; we do not guess at its contents.
+ */
+export function assertWritable(filePath) {
+    const read = readMCPConfig(filePath);
+    if (read.error !== null) {
+        throw new Error(`${filePath} ${read.error} Refusing to write, because saving would replace servers that are still in the file. Fix the file and try again.`);
+    }
+    return read.servers;
 }
 /**
  * Write servers to an mcp.json file (creates directory if needed).
@@ -47,32 +97,49 @@ export function writeMCPConfigFile(filePath, servers) {
 /**
  * Convert an MCPServerEntry to a ResolvedMCPServer.
  * Returns null if the entry is invalid (neither command nor url) or disabled.
+ *
+ * ⚠️ SECRET REFERENCES NEED `lookup`. Without one, a referenced value cannot be resolved and is
+ * reported in `missingSecrets` — it is never substituted with an empty string, because that turns
+ * a configuration problem into a 401 three layers away that nobody can trace back.
  */
-export function resolveServerEntry(name, entry) {
+export function resolveServerEntry(name, entry, lookup = () => null) {
     if (entry.disabled)
         return null;
     if (entry.command) {
+        const env = resolveValues(entry.env, lookup);
         return {
             name,
             transport: 'stdio',
             command: entry.command,
             args: entry.args,
-            env: entry.env,
+            env: Object.keys(env.values).length > 0 ? env.values : undefined,
             cwd: entry.cwd,
             timeout: entry.timeout,
+            missingSecrets: env.missing,
         };
     }
     if (entry.url) {
+        const headers = resolveValues(entry.headers, lookup);
         return {
             name,
             transport: 'http',
             url: entry.url,
-            headers: entry.headers,
+            headers: Object.keys(headers.values).length > 0 ? headers.values : undefined,
             timeout: entry.timeout,
+            missingSecrets: headers.missing,
         };
     }
     return null;
 }
+/**
+ * Can this server be started without handing it a credential we could not find?
+ *
+ * Hosts check this before connecting. Connecting anyway produces an authentication failure that
+ * looks like a bad token rather than a missing one.
+ */
+export function canConnect(server) {
+    return (server.missingSecrets ?? []).length === 0;
+}
 // =============================================================================
 // High-level helpers
 // =============================================================================
@@ -98,7 +165,7 @@ export function loadMCPServers(...configPaths) {
  * Save a single MCP server entry to a config file (add or overwrite by name).
  */
 export function saveMCPServerEntry(filePath, name, entry) {
-    const servers = readMCPConfigFile(filePath);
+    const servers = assertWritable(filePath);
     servers[name] = entry;
     writeMCPConfigFile(filePath, servers);
 }
@@ -106,7 +173,7 @@ export function saveMCPServerEntry(filePath, name, entry) {
  * Delete a single MCP server entry from a config file.
  */
 export function deleteMCPServerEntry(filePath, name) {
-    const servers = readMCPConfigFile(filePath);
+    const servers = assertWritable(filePath);
     const { [name]: _, ...rest } = servers;
     writeMCPConfigFile(filePath, rest);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.29.2",
+  "version": "0.29.3",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",