@compilr-dev/sdk 0.29.1 → 0.29.3

package/dist/index.d.ts

@@ -67,7 +67,7 @@ export type { GuideEntry, ContentTopic, ContentSection, GuideToolConfig } from '
 export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createCanvasTools, createImageTools, ProjectAnchorStore, FileArtifactService, } from './platform/index.js';
 export type { ProjectAnchorStoreConfig, FileArtifactServiceConfig, ImageToolsConfig, ImageResizer, } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
-export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker, SkillEligibilityContext, SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './skills/index.js';
+export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker, InstalledFromMarker, SkillEligibilityContext, SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './skills/index.js';
 export { RESERVED_MACRO_NAMES, isReservedMacroName, parseSkillMarkdown, loadSkillsFromDir, loadInstalledSkills, resolveLayeredSkills, resolveSkillsForAgent, resolveSkillsForTeamAgent, detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill as validateSkillQuality, getSkillsDir, getSkillFolder, getSkillFile, ensureSkillsDir, isValidSkillName, getScopeConfigPath, readSkillScopeConfig, readSkillScopeConfigSync, writeSkillScopeConfig, getSkillBindings, resolveSkillBinding, } from './skills/index.js';
 export type { SkillScope, SkillPromptResolution, AvailableSkillEntry, SkillSources, } from './skills/index.js';
 export { resolveSkillPrompt, getAllAvailableSkills } from './skills/index.js';
@@ -77,6 +77,8 @@ export { skillReachability, isUnreachable } from './skills/index.js';
 export { patchSkillFrontmatter } from './skills/index.js';
 export { isPlaceholderDescription } from './skills/index.js';
 export { readSkillFolder, unreadSkillFiles } from './skills/index.js';
+export { findInstallableSkills, normaliseSkillName, resolveInstallName, planInstall, describeInstallPlan, buildInstalledFromPatch, } from './skills/index.js';
+export type { InstallCandidate, InstallPlanItem } from './skills/index.js';
 export type { SkillFolderEntry } from './skills/index.js';
 export type { FrontmatterPatch } from './skills/index.js';
 export type { SkillReachability } from './skills/index.js';
@@ -107,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

@@ -160,6 +160,7 @@ export { skillReachability, isUnreachable } from './skills/index.js';
 export { patchSkillFrontmatter } from './skills/index.js';
 export { isPlaceholderDescription } from './skills/index.js';
 export { readSkillFolder, unreadSkillFiles } from './skills/index.js';
+export { findInstallableSkills, normaliseSkillName, resolveInstallName, planInstall, describeInstallPlan, buildInstalledFromPatch, } from './skills/index.js';
 export { generateSkillCatalog, toCatalogEntry, createLoadSkillTool } from './skills/index.js';
 export { platformMacros, designMacro, sketchMacro, prdMacro, refineMacro, refineItemMacro, architectureMacro, sessionNotesMacro, buildMacro, scaffoldMacro, outlineMacro, literatureReviewMacro, draftSectionMacro, peerReviewMacro, researchScaffoldMacro, businessVisionMacro, marketAnalysisMacro, competitorAnalysisMacro, financialModelMacro, pitchOutlineMacro, businessReviewMacro, brandSetupMacro, contentStrategyMacro, contentCalendarMacro, createContentMacro, contentReviewMacro, curriculumDesignMacro, lessonPlanMacro, assessmentDesignMacro, courseReviewMacro, bookOutlineMacro, characterDesignMacro, plotThreadsMacro, sceneBreakdownMacro, bookReviewMacro, } from './skills/index.js';
 // =============================================================================
@@ -231,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));
+    });
+}