@jam-mcp/server 1.4.5 → 1.4.6

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.5 doctor`, or just `jam
+Written out, that is `npx --yes @jam-mcp/launcher@1.4.6 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.5 init` instead.
+`npx --yes @jam-mcp/bootstrap@1.4.6 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/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.5", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.4.6", "serve"];
 };
 /**
  * Recognise wiring from before the launcher existed: a hard-coded `node` path

package/dist/cli/jira-read.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Reading Jira without the MCP channel.
+ *
+ * JAM's reads have lived only behind MCP tools. That is the right home when the
+ * agent's session already has them - but a session that registers JAM cannot be
+ * shown the new tools: Claude Code has no reload surface (`claude mcp` offers
+ * add / get / list / login / remove / reset-project-choices / serve, and nothing
+ * that re-reads registrations for a running session). So the agent that just
+ * installed JAM has to wait for its next session before it can read anything.
+ *
+ * What it did instead was worse: it answered Jira questions from whatever was at
+ * hand - git log, the code host, project documents - which is the exact
+ * substitution JAM exists to prevent.
+ *
+ * This is the same read, addressed differently. `search` / `context` / `full`
+ * call the same application functions the tools call, with the same deps, the
+ * same policies and the same `meta`. Nothing here re-implements a read, and
+ * nothing here is a second source of truth.
+ *
+ * Contract, enforced by tests:
+ *   stdout - one JSON document and nothing else, no ANSI, no prompts
+ *   stderr - diagnostics only
+ */
+import { type BuildDepsOptions, type JamDeps } from "../deps.js";
+export declare const JIRA_READ_USAGE = "Usage:\n  jam jira search <jql> [--scope preview|complete]\n  jam jira context <KEY> [KEY...]\n  jam jira full <KEY> [KEY...]\n\nReads only. Output is one JSON document on stdout - the same result the MCP\ntools return, for a session that cannot see them yet.\n";
+export type JiraReadOptions = BuildDepsOptions & {
+    /** Injected by tests so no test reaches a real Jira. */
+    deps?: JamDeps;
+    /** Where the JSON document goes. Defaults to stdout. */
+    write?: (text: string) => void;
+    /** Where diagnostics go. Defaults to stderr. */
+    warn?: (text: string) => void;
+};
+export declare function runJiraRead(argv: readonly string[], options?: JiraReadOptions): Promise<number>;

package/dist/cli/jira-read.js

@@ -0,0 +1,98 @@
+/**
+ * Reading Jira without the MCP channel.
+ *
+ * JAM's reads have lived only behind MCP tools. That is the right home when the
+ * agent's session already has them - but a session that registers JAM cannot be
+ * shown the new tools: Claude Code has no reload surface (`claude mcp` offers
+ * add / get / list / login / remove / reset-project-choices / serve, and nothing
+ * that re-reads registrations for a running session). So the agent that just
+ * installed JAM has to wait for its next session before it can read anything.
+ *
+ * What it did instead was worse: it answered Jira questions from whatever was at
+ * hand - git log, the code host, project documents - which is the exact
+ * substitution JAM exists to prevent.
+ *
+ * This is the same read, addressed differently. `search` / `context` / `full`
+ * call the same application functions the tools call, with the same deps, the
+ * same policies and the same `meta`. Nothing here re-implements a read, and
+ * nothing here is a second source of truth.
+ *
+ * Contract, enforced by tests:
+ *   stdout - one JSON document and nothing else, no ANSI, no prompts
+ *   stderr - diagnostics only
+ */
+import { getFullIssueContext } from "../application/get-full-issue-context.js";
+import { getIssueContext } from "../application/get-issue-context.js";
+import { searchIssues } from "../application/search-issues.js";
+import { buildDeps } from "../deps.js";
+import { toJamError } from "../domain/errors.js";
+export const JIRA_READ_USAGE = `Usage:
+  jam jira search <jql> [--scope preview|complete]
+  jam jira context <KEY> [KEY...]
+  jam jira full <KEY> [KEY...]
+
+Reads only. Output is one JSON document on stdout - the same result the MCP
+tools return, for a session that cannot see them yet.
+`;
+/** `--scope complete` / `--scope=complete`, and nothing invented when absent. */
+function flagValue(argv, flag) {
+    const index = argv.indexOf(flag);
+    if (index >= 0)
+        return argv[index + 1];
+    const inline = argv.find((arg) => arg.startsWith(`${flag}=`));
+    return inline ? inline.slice(flag.length + 1) : undefined;
+}
+const positional = (argv) => {
+    const out = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--scope") {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--"))
+            continue;
+        out.push(arg);
+    }
+    return out;
+};
+export async function runJiraRead(argv, options = {}) {
+    const write = options.write ?? ((text) => process.stdout.write(text));
+    const warn = options.warn ?? ((text) => process.stderr.write(text));
+    const [subcommand, ...rest] = argv;
+    if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+        warn(JIRA_READ_USAGE);
+        return subcommand ? 0 : 1;
+    }
+    if (subcommand !== "search" && subcommand !== "context" && subcommand !== "full") {
+        warn(`Unknown jira command: ${subcommand}\n\n${JIRA_READ_USAGE}`);
+        return 1;
+    }
+    const args = positional(rest);
+    if (args.length === 0) {
+        warn(subcommand === "search" ? "jam jira search needs a JQL query.\n" : `jam jira ${subcommand} needs at least one issue key.\n`);
+        return 1;
+    }
+    const scope = flagValue(rest, "--scope");
+    if (scope !== undefined && scope !== "preview" && scope !== "complete") {
+        warn(`--scope is preview|complete (got ${scope}).\n`);
+        return 1;
+    }
+    try {
+        const { deps: injected, write: _w, warn: _n, ...depsOptions } = options;
+        const deps = injected ?? (await buildDeps(depsOptions));
+        const result = subcommand === "search"
+            ? await searchIssues(deps, { jql: args.join(" "), ...(scope ? { scope } : {}) })
+            : subcommand === "context"
+                ? await getIssueContext(deps, { issueKeys: args })
+                : await getFullIssueContext(deps, { issueKeys: args });
+        write(`${JSON.stringify(result)}\n`);
+        return 0;
+    }
+    catch (err) {
+        // The same normalized codes the tools produce - an agent reads one contract,
+        // not two.
+        write(`${JSON.stringify(toJamError(err).toPayload())}\n`);
+        return 1;
+    }
+}

package/dist/cli-entry.d.ts

@@ -3,5 +3,5 @@
  * points (notably @jam-mcp/bootstrap) can forward to exactly these commands
  * instead of reimplementing them.
  */
-export declare const USAGE = "jam - Jira Agent MCP\n\nUsage:\n  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)\n  jam doctor              Diagnose config, credentials and Jira connectivity\n  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]\n                          Wire up this project and run doctor. Binds it to you\n                          alone, writing nothing to the repository; --shared\n                          adopts JAM for the team (project.yaml, .mcp.json)\n  jam runtime             Show which JAM build this machine runs\n  jam runtime use package | development <path>\n                          Change it (writes ~/.jam/config.yaml only, never a project)\n  jam auth login          Store Jira credentials in this user's OS secret store\n  jam auth logout         Remove them again\n\nFor coding agents and scripts (stdout is JSON only, never prompts):\n  jam setup --agent       One shot: detect, plan, apply what is safe, verify\n  jam setup plan --json   Report what setup would change, changing nothing\n  jam setup apply --non-interactive --json\n                          Execute the plan\n  jam doctor --json       Health check as structured output\n  jam auth status --json  Whether Jira credentials are configured (never their value)\n\nEnvironment:\n  JIRA_BASE_URL     https://your-site.atlassian.net\n  JIRA_EMAIL        Atlassian account email\n  JIRA_API_TOKEN    Atlassian API token\n  JAM_PROJECT_KEY   Jira project key, used by `jam setup`/`jam serve` when no\n                     .jira-agent/project.yaml exists yet\n\nCredentials and JAM_PROJECT_KEY are read from the current shell's environment\nfirst, then (on Windows) from the User environment - so a value set with\n`setx` works without opening a new terminal.\n";
+export declare const USAGE = "jam - Jira Agent MCP\n\nUsage:\n  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)\n  jam doctor              Diagnose config, credentials and Jira connectivity\n  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]\n                          Wire up this project and run doctor. Binds it to you\n                          alone, writing nothing to the repository; --shared\n                          adopts JAM for the team (project.yaml, .mcp.json)\n  jam runtime             Show which JAM build this machine runs\n  jam runtime use package | development <path>\n                          Change it (writes ~/.jam/config.yaml only, never a project)\n  jam auth login          Store Jira credentials in this user's OS secret store\n  jam auth logout         Remove them again\n\nFor coding agents and scripts (stdout is JSON only, never prompts):\n  jam setup --agent       One shot: detect, plan, apply what is safe, verify\n  jam setup plan --json   Report what setup would change, changing nothing\n  jam setup apply --non-interactive --json\n                          Execute the plan\n  jam doctor --json       Health check as structured output\n  jam auth status --json  Whether Jira credentials are configured (never their value)\n  jam jira search <jql> [--scope preview|complete]\n  jam jira context <KEY> [KEY...]\n  jam jira full <KEY> [KEY...]\n                          Read Jira from the shell - the same reads the MCP\n                          tools do, for a session that cannot see them yet\n\nEnvironment:\n  JIRA_BASE_URL     https://your-site.atlassian.net\n  JIRA_EMAIL        Atlassian account email\n  JIRA_API_TOKEN    Atlassian API token\n  JAM_PROJECT_KEY   Jira project key, used by `jam setup`/`jam serve` when no\n                     .jira-agent/project.yaml exists yet\n\nCredentials and JAM_PROJECT_KEY are read from the current shell's environment\nfirst, then (on Windows) from the User environment - so a value set with\n`setx` works without opening a new terminal.\n";
 export declare function runJamCommand(argv: string[]): Promise<number>;

package/dist/cli-entry.js

@@ -6,6 +6,7 @@ import { setup } from "./cli/setup.js";
 import { runSetupWizard } from "./cli/setup-wizard.js";
 import { reportPromptError, Ui } from "./cli/ui.js";
 import { authStatusCommand, doctorJsonCommand, setupAgentCommand, setupApplyCommand, setupPlanCommand, } from "./cli/agent-api.js";
+import { runJiraRead } from "./cli/jira-read.js";
 /**
  * Command dispatch for the JAM CLI, separated from the bin so other entry
  * points (notably @jam-mcp/bootstrap) can forward to exactly these commands
@@ -33,6 +34,11 @@ For coding agents and scripts (stdout is JSON only, never prompts):
                           Execute the plan
   jam doctor --json       Health check as structured output
   jam auth status --json  Whether Jira credentials are configured (never their value)
+  jam jira search <jql> [--scope preview|complete]
+  jam jira context <KEY> [KEY...]
+  jam jira full <KEY> [KEY...]
+                          Read Jira from the shell - the same reads the MCP
+                          tools do, for a session that cannot see them yet
 
 Environment:
   JIRA_BASE_URL     https://your-site.atlassian.net
@@ -112,6 +118,10 @@ export async function runJamCommand(argv) {
             process.stderr.write("Usage: jam auth login | status [--json] | logout\n");
             return 1;
         }
+        case "jira":
+            // Reads addressed to the shell, for a session that cannot see the MCP
+            // tools yet. Same application path as the tools - see cli/jira-read.ts.
+            return runJiraRead(rest);
         case "help":
         case "--help":
         case "-h":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jam-mcp/server",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "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.5",
+    "@jam-mcp/launcher": "1.4.6",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"