@jam-mcp/server 1.4.0 → 1.4.1

package/README.md

@@ -74,10 +74,10 @@ auth login   Store Jira credentials in this user's OS secret store
 runtime      Show or change which JAM build this machine runs
 ```
 
-Written out, that is `npx --yes @jam-mcp/launcher@1.4.0 doctor`, or just `jam
+Written out, that is `npx --yes @jam-mcp/launcher@1.4.1 doctor`, or just `jam
 doctor` if you took the launcher's optional global install. Starting from
 nothing — no install, no runtime chosen yet — use
-`npx --yes @jam-mcp/bootstrap@1.4.0 init` instead.
+`npx --yes @jam-mcp/bootstrap@1.4.1 init` instead.
 
 Credentials come from the process environment or this user's OS secret store —
 never from a repository file — and never appear in logs, telemetry, or tool

package/dist/bootstrap/host-mcp.d.ts

@@ -18,6 +18,18 @@ export type HostState = {
     cliAvailable: boolean;
     /** Whether it already has a `jam` entry registered for this user. */
     hasJamEntry: boolean;
+    /**
+     * The launcher pin that entry actually runs, when the listing shows it.
+     *
+     * An entry existing is not the same as an entry being current: a pin written
+     * by an older release keeps running that release's server, which serves a
+     * different set of tools. Reading only the name made a stale registration
+     * indistinguishable from a good one, and setup then reported
+     * `already_configured` over it.
+     */
+    entryVersion?: string;
+    /** The entry is present but does not run the launcher this release registers. */
+    entryStale?: boolean;
 };
 export type HostRunResult = {
     status: number | null;
@@ -29,6 +41,8 @@ export type HostRunResult = {
 export type HostRunner = (command: HostCommand) => HostRunResult;
 export declare const defaultHostRunner: HostRunner;
 export declare function hostRegistration(id: HostId): HostCommand | undefined;
+/** The removal that has to precede re-registering an entry this host already has. */
+export declare function hostUnregistration(id: HostId): HostCommand | undefined;
 /**
  * Is `jam` in this listing?
  *
@@ -42,6 +56,19 @@ export declare function hostRegistration(id: HostId): HostCommand | undefined;
  * `mcp add` on an existing entry writes the same launcher line back.
  */
 export declare function listsJamEntry(stdout: string): boolean;
+/** The listing line for `jam`, ANSI stripped, or null when there is none. */
+export declare function jamEntryLine(stdout: string): string | null;
+/** The launcher version a listing line runs, when the line names one. */
+export declare function entryLauncherVersion(line: string): string | undefined;
+/**
+ * Does this entry run the launcher this release registers?
+ *
+ * Anything else - an older pin, an unpinned spec, a line whose command JAM
+ * cannot read - counts as stale. That direction is deliberate: `mcp add`
+ * rewrites the same entry, so a needless repair costs one command, while a
+ * missed one leaves the agent talking to a server nobody tested it against.
+ */
+export declare function isEntryStale(line: string): boolean;
 /**
  * Ask each host what it has, and whether it is there at all.
  *

package/dist/bootstrap/host-mcp.js

@@ -30,16 +30,22 @@ const ADAPTERS = [
         // `-s user` is the whole point: registered for this user on this machine,
         // not for whichever project happens to be open.
         register: { command: "claude", args: ["mcp", "add", "jam", "-s", "user", ...LAUNCH] },
+        unregister: { command: "claude", args: ["mcp", "remove", "jam", "-s", "user"] },
     },
     {
         id: "codex",
         probe: { command: "codex", args: ["mcp", "list"] },
         register: { command: "codex", args: ["mcp", "add", "jam", ...LAUNCH] },
+        unregister: { command: "codex", args: ["mcp", "remove", "jam"] },
     },
 ];
 export function hostRegistration(id) {
     return ADAPTERS.find((a) => a.id === id)?.register;
 }
+/** The removal that has to precede re-registering an entry this host already has. */
+export function hostUnregistration(id) {
+    return ADAPTERS.find((a) => a.id === id)?.unregister;
+}
 const ANSI = /\[[0-9;?]*[A-Za-z]/g;
 /**
  * Is `jam` in this listing?
@@ -54,11 +60,32 @@ const ANSI = /\[[0-9;?]*[A-Za-z]/g;
  * `mcp add` on an existing entry writes the same launcher line back.
  */
 export function listsJamEntry(stdout) {
-    return stdout
+    return jamEntryLine(stdout) !== null;
+}
+/** The listing line for `jam`, ANSI stripped, or null when there is none. */
+export function jamEntryLine(stdout) {
+    const line = stdout
         .replace(ANSI, "")
         .split(/\r?\n/)
-        .some((line) => /^\s*jam(?=[\s:])/.test(line));
+        .find((candidate) => /^\s*jam(?=[\s:])/.test(candidate));
+    return line ?? null;
+}
+/** The launcher version a listing line runs, when the line names one. */
+export function entryLauncherVersion(line) {
+    return /@jam-mcp\/launcher@([^\s"']+)/.exec(line)?.[1];
+}
+/**
+ * Does this entry run the launcher this release registers?
+ *
+ * Anything else - an older pin, an unpinned spec, a line whose command JAM
+ * cannot read - counts as stale. That direction is deliberate: `mcp add`
+ * rewrites the same entry, so a needless repair costs one command, while a
+ * missed one leaves the agent talking to a server nobody tested it against.
+ */
+export function isEntryStale(line) {
+    return entryLauncherVersion(line) !== EXPECTED_LAUNCHER_VERSION;
 }
+const EXPECTED_LAUNCHER_VERSION = entryLauncherVersion(JAM_MCP_ENTRY.args.join(" "));
 /**
  * Ask each host what it has, and whether it is there at all.
  *
@@ -85,10 +112,16 @@ function probeHosts(run) {
         if (result.failed || result.status !== 0) {
             return { id: adapter.id, cliAvailable: false, hasJamEntry: false };
         }
+        const line = jamEntryLine(result.stdout);
+        if (!line)
+            return { id: adapter.id, cliAvailable: true, hasJamEntry: false };
+        const version = entryLauncherVersion(line);
         return {
             id: adapter.id,
             cliAvailable: true,
-            hasJamEntry: listsJamEntry(result.stdout),
+            hasJamEntry: true,
+            ...(version ? { entryVersion: version } : {}),
+            entryStale: isEntryStale(line),
         };
     });
 }

package/dist/bootstrap/mcp-config-merger.d.ts

@@ -13,7 +13,7 @@ import { LAUNCHER_PACKAGE_SPEC } from "@jam-mcp/launcher";
 export { LAUNCHER_PACKAGE_SPEC };
 export declare const JAM_MCP_ENTRY: {
     readonly command: "npx";
-    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.4.0", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.4.1", "serve"];
 };
 /**
  * Recognise wiring from before the launcher existed: a hard-coded `node` path

package/dist/bootstrap/setup-apply.js

@@ -36,6 +36,11 @@ export function applySetupPlan(plan, options = {}) {
                 // decides nothing. A failure is that host's failure, reported with the
                 // command that produced it - never retried against another host.
                 const run = options.runHost ?? defaultHostRunner;
+                // A repair removes the stale entry first. Its failure is not reported on
+                // its own: if the entry is already gone the removal fails harmlessly, and
+                // if it is still there the registration below fails and says so.
+                if (change.precede)
+                    run({ command: change.precede.command, args: change.precede.args });
                 const result = run({ command: change.command, args: change.args });
                 if (result.failed || result.status !== 0) {
                     throw new Error(`Registering JAM with ${change.host} failed: ${change.command} ${change.args.join(" ")}`);

package/dist/bootstrap/setup-plan.d.ts

@@ -34,7 +34,7 @@ export type SetupChange = {
     /** Present on a rebind, so the preview shows what is being replaced. */
     previousKey?: string;
 } | {
-    type: "create";
+    type: "create" | "replace";
     target: "host-mcp";
     host: HostId;
     /**
@@ -44,6 +44,18 @@ export type SetupChange = {
      */
     command: string;
     args: string[];
+    /**
+     * Run before the registration, on a repair. The host CLI refuses to add an
+     * entry that already exists, so the stale one has to go first - and which
+     * command does that is decided here, not worked out during apply.
+     */
+    precede?: {
+        command: string;
+        args: string[];
+    };
+    /** On a repair: the launcher pin the entry runs today, so the preview names it. */
+    previousVersion?: string;
+    reason?: "stale-registration";
 };
 export type SetupPlan = {
     status: SetupStatus;

package/dist/bootstrap/setup-plan.js

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { CONFIG_RELATIVE_PATH } from "../config/load-config.js";
-import { hostRegistration } from "./host-mcp.js";
+import { hostRegistration, hostUnregistration } from "./host-mcp.js";
 import { projectBindingsPath } from "./project-bindings.js";
 import { decideProjectKey } from "./project-config-bootstrapper.js";
 import { portableBootstrapCommand } from "@jam-mcp/launcher";
@@ -155,17 +155,25 @@ function finish(changes, state, project) {
 function planHostChanges(state) {
     const changes = [];
     for (const host of state.hosts) {
-        if (!host.cliAvailable || host.hasJamEntry)
+        if (!host.cliAvailable)
+            continue;
+        // An entry that exists but runs an older launcher is not "already set up":
+        // that pin decides which server, and so which tools, the agent actually gets.
+        if (host.hasJamEntry && host.entryStale !== true)
             continue;
         const registration = hostRegistration(host.id);
         if (!registration)
             continue;
+        const removal = hostUnregistration(host.id);
         changes.push({
-            type: "create",
+            type: host.hasJamEntry ? "replace" : "create",
             target: "host-mcp",
             host: host.id,
             command: registration.command,
             args: registration.args,
+            ...(host.hasJamEntry && removal ? { precede: { command: removal.command, args: removal.args } } : {}),
+            ...(host.entryVersion ? { previousVersion: host.entryVersion } : {}),
+            ...(host.hasJamEntry ? { reason: "stale-registration" } : {}),
         });
     }
     return changes;

package/dist/cli/agent-api.d.ts

@@ -1,6 +1,7 @@
 import { type MigrationTarget } from "../bootstrap/migration-target.js";
 import type { CredentialPort } from "../ports/credentials.port.js";
-import type { HostRunner } from "../bootstrap/host-mcp.js";
+import { type HostRunner } from "../bootstrap/host-mcp.js";
+import { type ToolsetProbe } from "../bootstrap/live-toolset.js";
 import type { GitRemoteFn } from "../bootstrap/workspace-identity.js";
 /**
  * The machine-readable half of setup.
@@ -27,6 +28,8 @@ export type AgentOptions = {
     env?: NodeJS.ProcessEnv;
     /** Injected by tests so a plan never shells out to npm to verify a migration target. */
     migrationTarget?: MigrationTarget;
+    /** Injected by tests so doctor never launches a real MCP server to read its tools. */
+    toolsetProbe?: ToolsetProbe;
     /** Injected by tests so identity never depends on the checkout under test. */
     git?: GitRemoteFn;
     /** Injected by tests so no test ever registers JAM with a real host. */
@@ -52,7 +55,15 @@ export declare function setupApplyCommand(options?: AgentOptions): Promise<numbe
  * authenticating), and reports exactly how far it got.
  */
 export declare function setupAgentCommand(options?: AgentOptions): Promise<number>;
-/** `jam doctor --json`. */
+/**
+ * `jam doctor --json`.
+ *
+ * Three axes, kept apart on purpose. The package on this machine being current
+ * says nothing about what the host registration launches, and neither says what
+ * the agent can actually call - a stale pin serves an older tool set while every
+ * local check passes. Reporting them as one verdict is how a broken setup was
+ * reported as ready.
+ */
 export declare function doctorJsonCommand(options?: AgentOptions): Promise<number>;
 /**
  * `jam auth status --json` - presence and origin only.

package/dist/cli/agent-api.js

@@ -5,6 +5,9 @@ import { applySetupPlan } from "../bootstrap/setup-apply.js";
 import { detectSetupState } from "../bootstrap/setup-state.js";
 import { buildDeps } from "../deps.js";
 import { toJamError } from "../domain/errors.js";
+import { hostRegistration } from "../bootstrap/host-mcp.js";
+import { checkLiveToolset } from "../bootstrap/live-toolset.js";
+import { SERVER_VERSION } from "@jam-mcp/launcher";
 export function emitJson(payload) {
     process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
 }
@@ -108,17 +111,74 @@ export async function setupAgentCommand(options = {}) {
     });
     return health.passed ? 0 : 1;
 }
-/** `jam doctor --json`. */
+/**
+ * `jam doctor --json`.
+ *
+ * Three axes, kept apart on purpose. The package on this machine being current
+ * says nothing about what the host registration launches, and neither says what
+ * the agent can actually call - a stale pin serves an older tool set while every
+ * local check passes. Reporting them as one verdict is how a broken setup was
+ * reported as ready.
+ */
 export async function doctorJsonCommand(options = {}) {
+    // detect() already probes the hosts for every non-shared path; doctor wants that.
     const state = detect(options);
     const health = await gateResult(state.project.root);
+    const axes = await inspectAxes(state, options);
+    // 등록이 아예 없는 것은 결함이 아니다 — 새 머신, 호스트 CLI 없는 CI, 아직 setup 을
+    // 안 한 사용자 모두 정상 상태다. 전체 판정을 무너뜨리는 것은 **거짓말하는 상태**뿐:
+    // 낡은 핀을 실행 중인 등록(STALE)과, 등록은 맞는데 실제 도구가 다른 경우(MISMATCH).
+    const axesOk = axes.registration !== "HOST_REGISTRATION_STALE" && axes.live !== "LIVE_TOOLSET_MISMATCH";
+    const passed = health.passed && axesOk;
     emitJson({
-        status: health.passed ? "ready" : "failed",
+        status: passed ? "ready" : "failed",
         ...(health.error ? { error: health.error } : {}),
         project: { root: state.project.root, ...(state.project.key ? { key: state.project.key } : {}) },
+        axes,
         checks: health.checks,
     });
-    return health.passed ? 0 : 1;
+    return passed ? 0 : 1;
+}
+async function inspectAxes(state, options) {
+    const packageVersion = state.runtime.version;
+    const axes = {
+        package: packageVersion === SERVER_VERSION ? "PACKAGE_READY" : "PACKAGE_NOT_READY",
+        ...(packageVersion ? { packageVersion } : {}),
+        registration: "UNREGISTERED",
+        live: "UNCHECKED",
+    };
+    const hosts = state.hosts.filter((host) => host.cliAvailable);
+    if (state.hosts.length > 0 && hosts.length === 0) {
+        return { ...axes, registration: "HOST_UNREACHABLE", detail: "no host CLI answered" };
+    }
+    const registered = hosts.find((host) => host.hasJamEntry);
+    if (!registered)
+        return axes;
+    axes.registration = registered.entryStale ? "HOST_REGISTRATION_STALE" : "OK";
+    if (registered.entryVersion)
+        axes.registeredVersion = registered.entryVersion;
+    // A stale entry has already answered the question the live check would ask,
+    // and asking it means launching that older release. Repair first.
+    if (registered.entryStale)
+        return axes;
+    const registration = hostRegistration(registered.id);
+    const launch = registration ? launcherArgv(registration.args) : null;
+    if (!launch)
+        return { ...axes, live: "UNCHECKED", detail: "could not read the registered command" };
+    const result = await checkLiveToolset(launch, options.toolsetProbe);
+    axes.live = result.verdict === "OK" ? "OK" : result.verdict;
+    if (result.missing && result.missing.length > 0)
+        axes.missingTools = result.missing;
+    if (result.detail)
+        axes.detail = result.detail;
+    return axes;
+}
+/** The registration argv carries the launch command after `--`. */
+function launcherArgv(args) {
+    const at = args.indexOf("--");
+    if (at < 0 || args.length <= at + 1)
+        return null;
+    return { command: args[at + 1], args: args.slice(at + 2) };
 }
 /**
  * `jam auth status --json` - presence and origin only.

package/dist/cli/setup.js

@@ -108,7 +108,9 @@ function reportApplied(applied, plan) {
             continue;
         }
         if (change.target === "host-mcp") {
-            line(`[OK]   ${change.host} - jam registered for this user`);
+            line(change.type === "replace"
+                ? `[OK]   ${change.host} - jam re-registered, replacing a stale launcher pin${change.previousVersion ? ` (${change.previousVersion})` : ""}`
+                : `[OK]   ${change.host} - jam registered for this user`);
             continue;
         }
         if (change.target === "project-config") {

package/dist/mcp/create-server.d.ts

@@ -2,6 +2,13 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { JamDeps } from "../deps.js";
 export declare const SERVER_NAME = "jam";
 export declare const TOOL_COUNT: number;
+/**
+ * The same contract by name, for the checks that ask a *running* server what it
+ * serves. The registrars above cannot be introspected for their tool names, and
+ * counting is not enough: five tools with one renamed is still five.
+ * `tests/contract/tools.test.ts` holds this list to what the server registers.
+ */
+export declare const TOOL_NAMES: readonly ["jira_search", "jira_context", "jira_full", "jira_write_plan", "jira_write_apply"];
 /**
  * The external contract: three read tools and two write tools.
  *

package/dist/mcp/create-server.js

@@ -21,6 +21,19 @@ const REGISTER_TOOLS = [
     registerJiraWriteApply,
 ];
 export const TOOL_COUNT = REGISTER_TOOLS.length;
+/**
+ * The same contract by name, for the checks that ask a *running* server what it
+ * serves. The registrars above cannot be introspected for their tool names, and
+ * counting is not enough: five tools with one renamed is still five.
+ * `tests/contract/tools.test.ts` holds this list to what the server registers.
+ */
+export const TOOL_NAMES = [
+    "jira_search",
+    "jira_context",
+    "jira_full",
+    "jira_write_plan",
+    "jira_write_apply",
+];
 /**
  * The external contract: three read tools and two write tools.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jam-mcp/server",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "JAM (Jira Agent MCP) - agent-facing Jira access layer: MCP server, setup core, and CLI",
   "keywords": [
     "jira",
@@ -41,7 +41,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jam-mcp/launcher": "1.4.0",
+    "@jam-mcp/launcher": "1.4.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"