@jam-mcp/server 1.0.1 → 1.1.0

package/dist/mcp/create-server.js

@@ -3,13 +3,32 @@ import { createRequire } from "node:module";
 import { registerJiraContext } from "./tools/jira-context.tool.js";
 import { registerJiraFull } from "./tools/jira-full.tool.js";
 import { registerJiraSearch } from "./tools/jira-search.tool.js";
+import { registerJiraWriteApply } from "./tools/jira-write-apply.tool.js";
+import { registerJiraWritePlan } from "./tools/jira-write-plan.tool.js";
 const require = createRequire(import.meta.url);
 const pkg = require("../../package.json");
 export const SERVER_NAME = "jam";
 /**
- * The external contract: exactly three read tools, stable from the first
- * release. Internal changes (cache, Rovo, remote transport) must not add or
- * rename anything here.
+ * Every tool registration, in one list. `TOOL_COUNT` is derived from it, so a
+ * tool added here is counted everywhere it is reported - doctor included -
+ * without anyone having to remember a second place to edit.
+ */
+const REGISTER_TOOLS = [
+    registerJiraSearch,
+    registerJiraContext,
+    registerJiraFull,
+    registerJiraWritePlan,
+    registerJiraWriteApply,
+];
+export const TOOL_COUNT = REGISTER_TOOLS.length;
+/**
+ * The external contract: three read tools and two write tools.
+ *
+ * The read three have been stable since the first release and do not change.
+ * The write pair is a single operation split in half on purpose - deciding and
+ * doing are separate calls, so an agent cannot mutate Jira without first
+ * having been shown what it is about to change. Internal changes (cache, Rovo,
+ * remote transport) must not add or rename anything here.
  */
 export function createServer(deps) {
     const server = new McpServer({ name: SERVER_NAME, version: pkg.version ?? "0.0.0" }, {
@@ -23,10 +42,15 @@ export function createServer(deps) {
             "Every result carries a `meta` block; if meta.complete is false the answer is partial and must be reported as such.",
             "meta.complete describes JAM's retrieval, not the project: it means the Jira read finished with no known loss, never that Jira holds the whole story.",
             "meta.evidenceScope and meta.limitations name what was not evaluated - the repository and every external source among them. Judge Jira evidence from these results; judge execution reality elsewhere.",
+            "",
+            "Writing Jira is two steps: jira_write_plan, then jira_write_apply with the planId it returned.",
+            "jira_write_plan changes nothing - it reads the issue, checks the change is possible, and describes what would happen.",
+            "jira_write_apply takes only a planId. There is no way to write without planning first, and no payload to override what the plan decided.",
+            "Writes are confined to the configured Jira project, and confirmed by reading the issue back. A write JAM could not verify is never reported as done.",
+            "On JAM_WRITE_CONFLICT or JAM_WRITE_PLAN_EXPIRED, plan again against the current state. On JAM_WRITE_UNCERTAIN, read the issue - never retry the apply, which could apply the change twice.",
         ].join("\n"),
     });
-    registerJiraSearch(server, deps);
-    registerJiraContext(server, deps);
-    registerJiraFull(server, deps);
+    for (const register of REGISTER_TOOLS)
+        register(server, deps);
     return server;
 }

package/dist/mcp/tools/jira-write-apply.tool.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { JamDeps } from "../../deps.js";
+export declare function registerJiraWriteApply(server: McpServer, deps: JamDeps): void;

package/dist/mcp/tools/jira-write-apply.tool.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { applyWritePlan } from "../../application/apply-write.js";
+import { runTool } from "../tool-result.js";
+const DESCRIPTION = `Apply a plan from jira_write_plan. This changes Jira.
+
+Takes a planId and nothing else. The change was decided when the plan was made, so there is no field, payload or override to pass here - that is deliberate, and it is what stops a write happening without the state check that planning did.
+
+Before writing, JAM re-reads the issue and compares it to what the plan saw. If it moved, you get JAM_WRITE_CONFLICT and no write happens: call jira_write_plan again against the new state rather than treating the conflict as a transient failure.
+
+After writing, JAM reads the issue back and checks the intended result is actually there. Only then does it return "applied". Jira accepting a request is not the same as the issue having changed.
+
+Failures worth handling differently:
+- JAM_WRITE_CONFLICT             the issue moved; re-plan
+- JAM_WRITE_PLAN_EXPIRED         the plan aged out; re-plan
+- JAM_WRITE_VERIFICATION_FAILED  Jira accepted it but the issue does not show it; read the issue and tell the user
+- JAM_WRITE_UNCERTAIN            JAM does not know whether it landed; read the issue. Do NOT call this tool again - the write may already have been applied, and applying it twice is a second comment or a second transition.
+
+Never report an uncertain or unverified write as done.`;
+export function registerJiraWriteApply(server, deps) {
+    server.registerTool("jira_write_apply", {
+        title: "Apply a planned change to a Jira issue (writes)",
+        description: DESCRIPTION,
+        inputSchema: {
+            planId: z
+                .string()
+                .min(1)
+                .describe("The planId returned by jira_write_plan. Single use."),
+        },
+        // Mutating, but not destructive in the sense hosts warn about: every
+        // supported operation adds or changes a field, and none delete anything.
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args) => runTool("jira_write_apply", deps.telemetry, () => applyWritePlan(deps, { planId: args.planId })));
+}

package/dist/mcp/tools/jira-write-plan.tool.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { JamDeps } from "../../deps.js";
+export declare function registerJiraWritePlan(server: McpServer, deps: JamDeps): void;

package/dist/mcp/tools/jira-write-plan.tool.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { planWrite } from "../../application/plan-write.js";
+import { WRITABLE_FIELDS, WRITE_OPERATIONS } from "../../domain/write.js";
+import { runTool } from "../tool-result.js";
+const DESCRIPTION = `Work out how to change one Jira issue, and get back a plan. Changes nothing.
+
+This is the first half of every write. Call it, read what it says the issue looks like now and what it would become, then pass the returned planId to jira_write_apply. There is no way to write to Jira without a plan, and a plan cannot be assembled by hand - only jira_write_plan issues one.
+
+Operations:
+- comment.add        input: { "text": "..." }        plain text; JAM converts it, do not send ADF
+- field.update       input: { "summary"?, "priority"?, "labels"?, "components"? }
+- status.transition  input: { "status": "Done" }     JAM asks Jira which transitions exist and matches yours
+
+Writes are limited to the Jira project this workspace is bound to; a key from another project is refused rather than attempted.
+
+The plan records what the issue looked like when it was made, and expires. If the issue changes in the meantime, jira_write_apply refuses with JAM_WRITE_CONFLICT - re-plan against the new state rather than forcing the old one through.
+
+A plan is a statement about what is possible right now, not a promise that it will happen. Nothing is written until jira_write_apply runs.`;
+export function registerJiraWritePlan(server, deps) {
+    server.registerTool("jira_write_plan", {
+        title: "Plan a change to a Jira issue (writes nothing)",
+        description: DESCRIPTION,
+        inputSchema: {
+            key: z.string().min(1).describe('Issue key, e.g. "PROJECT-123". Must be in the configured project.'),
+            operation: z
+                .enum(WRITE_OPERATIONS)
+                .describe(`What to do: ${WRITE_OPERATIONS.join(", ")}.`),
+            input: z
+                .object({
+                text: z.string().min(1).optional().describe("comment.add: the comment, as plain text."),
+                status: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe("status.transition: the status to move to, e.g. \"Done\"."),
+                summary: z.string().min(1).optional(),
+                priority: z.string().min(1).optional().describe('Priority name, e.g. "High".'),
+                labels: z.array(z.string()).optional().describe("Replaces the whole label set."),
+                components: z
+                    .array(z.string())
+                    .optional()
+                    .describe("Component names. Replaces the whole component set."),
+            })
+                .describe(`Operation input. field.update accepts only ${WRITABLE_FIELDS.join(", ")} - custom fields and assignee are not writable.`),
+        },
+        // Planning reads Jira and decides; it never mutates. Hosts are free to
+        // run it without asking, which is what keeps the two-step shape cheap.
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    }, async (args) => runTool("jira_write_plan", deps.telemetry, async () => {
+        const { receipt } = await planWrite(deps, {
+            key: args.key,
+            operation: args.operation,
+            input: args.input,
+        });
+        return receipt;
+    }));
+}

package/dist/policy/write-policy.d.ts

@@ -0,0 +1,60 @@
+import { type FieldUpdateInput, type JiraTransition, type WriteOperation } from "../domain/write.js";
+/**
+ * What a write is allowed to be, decided before anything reaches Jira.
+ *
+ * These checks exist so a refusal is a JAM answer rather than a Jira 403 or a
+ * 404 with no explanation. "You asked to change an issue in another project"
+ * and "Jira says that issue does not exist" look identical from the REST layer
+ * and mean entirely different things to whoever has to act next.
+ */
+/**
+ * How long a plan stays applicable.
+ *
+ * Short on purpose. A plan carries a snapshot of the issue, and the older that
+ * snapshot is the more likely apply is about to reject it anyway - so the
+ * window is measured in the time an agent needs to decide, not in how long a
+ * person might leave a terminal open.
+ */
+export declare const PLAN_TTL_MS: number;
+/**
+ * Which project an issue key belongs to.
+ *
+ * Parsed rather than looked up: a malformed key should be refused before it is
+ * spent on a Jira round trip.
+ */
+export declare function projectKeyOf(issueKey: string): string | undefined;
+/**
+ * Writes stay inside the project this workspace is bound to.
+ *
+ * The binding is what the user consented to when they set JAM up. An agent
+ * holding a key from somewhere else - copied from a link, inferred from a
+ * comment - must not be able to reach into another team's project through it.
+ */
+export declare function assertWriteScope(issueKey: string, configuredProject: string): string;
+export declare function assertOperationAllowed(operation: string): WriteOperation;
+/**
+ * Reject anything outside the field whitelist before planning goes further.
+ *
+ * Returns the requested fields in whitelist order so a plan's `before` and
+ * `intendedAfter` are comparable regardless of how the caller ordered them.
+ */
+export declare function assertFieldsAllowed(input: FieldUpdateInput): FieldUpdateInput;
+/**
+ * Match a requested status against what Jira currently offers.
+ *
+ * Jira's transition ids are per-workflow and not derivable from a status name,
+ * so this only ever selects from transitions Jira just reported. When nothing
+ * matches, the available names go back with the error - the agent's next move
+ * is to pick one of them, not to try harder at the same one.
+ */
+export declare function resolveTransition(target: string, available: JiraTransition[]): JiraTransition;
+export declare function planExpired(expiresAt: string, now: Date): boolean;
+/**
+ * Has the issue moved since the plan was made?
+ *
+ * Jira's `updated` timestamp is the revision marker: it changes on any edit,
+ * including ones JAM did not make and cannot see the shape of. Comparing it is
+ * what stops an agent applying a decision it made against an issue that no
+ * longer exists in that form.
+ */
+export declare function assertUnchanged(issueKey: string, baseUpdated: string, currentUpdated: string): void;

package/dist/policy/write-policy.js

@@ -0,0 +1,114 @@
+import { JamError } from "../domain/errors.js";
+import { isWritableField, isWriteOperation, WRITABLE_FIELDS, WRITE_OPERATIONS, } from "../domain/write.js";
+/**
+ * What a write is allowed to be, decided before anything reaches Jira.
+ *
+ * These checks exist so a refusal is a JAM answer rather than a Jira 403 or a
+ * 404 with no explanation. "You asked to change an issue in another project"
+ * and "Jira says that issue does not exist" look identical from the REST layer
+ * and mean entirely different things to whoever has to act next.
+ */
+/**
+ * How long a plan stays applicable.
+ *
+ * Short on purpose. A plan carries a snapshot of the issue, and the older that
+ * snapshot is the more likely apply is about to reject it anyway - so the
+ * window is measured in the time an agent needs to decide, not in how long a
+ * person might leave a terminal open.
+ */
+export const PLAN_TTL_MS = 10 * 60 * 1000;
+const KEY_PATTERN = /^([A-Z][A-Z0-9_]*)-(\d+)$/;
+/**
+ * Which project an issue key belongs to.
+ *
+ * Parsed rather than looked up: a malformed key should be refused before it is
+ * spent on a Jira round trip.
+ */
+export function projectKeyOf(issueKey) {
+    return KEY_PATTERN.exec(issueKey.trim().toUpperCase())?.[1];
+}
+/**
+ * Writes stay inside the project this workspace is bound to.
+ *
+ * The binding is what the user consented to when they set JAM up. An agent
+ * holding a key from somewhere else - copied from a link, inferred from a
+ * comment - must not be able to reach into another team's project through it.
+ */
+export function assertWriteScope(issueKey, configuredProject) {
+    const project = projectKeyOf(issueKey);
+    if (!project) {
+        throw new JamError("JAM_WRITE_SCOPE_VIOLATION", `"${issueKey}" is not a Jira issue key.`, { issueKey });
+    }
+    const configured = configuredProject.trim().toUpperCase();
+    if (!configured) {
+        throw new JamError("JAM_SETUP_REQUIRED", "No Jira project is configured for this workspace, so JAM cannot tell whether this write is in scope.", { issueKey });
+    }
+    if (project !== configured) {
+        throw new JamError("JAM_WRITE_SCOPE_VIOLATION", `${issueKey} belongs to project ${project}, but this workspace is bound to ${configured}. JAM writes only within the configured project.`, { issueKey, project, configuredProject: configured });
+    }
+    return project;
+}
+export function assertOperationAllowed(operation) {
+    if (!isWriteOperation(operation)) {
+        throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", `"${operation}" is not a JAM write operation. Supported: ${WRITE_OPERATIONS.join(", ")}.`, { operation, supported: [...WRITE_OPERATIONS] });
+    }
+    return operation;
+}
+/**
+ * Reject anything outside the field whitelist before planning goes further.
+ *
+ * Returns the requested fields in whitelist order so a plan's `before` and
+ * `intendedAfter` are comparable regardless of how the caller ordered them.
+ */
+export function assertFieldsAllowed(input) {
+    const requested = Object.keys(input).filter((key) => input[key] !== undefined);
+    if (requested.length === 0) {
+        throw new JamError("JAM_WRITE_FIELD_NOT_ALLOWED", `field.update needs at least one field. Supported: ${WRITABLE_FIELDS.join(", ")}.`, { supported: [...WRITABLE_FIELDS] });
+    }
+    const rejected = requested.filter((key) => !isWritableField(key));
+    if (rejected.length > 0) {
+        throw new JamError("JAM_WRITE_FIELD_NOT_ALLOWED", `JAM cannot write ${rejected.join(", ")}. Supported: ${WRITABLE_FIELDS.join(", ")}.`, { rejected, supported: [...WRITABLE_FIELDS] });
+    }
+    const ordered = {};
+    for (const field of WRITABLE_FIELDS) {
+        const value = input[field];
+        if (value !== undefined)
+            Object.assign(ordered, { [field]: value });
+    }
+    return ordered;
+}
+/**
+ * Match a requested status against what Jira currently offers.
+ *
+ * Jira's transition ids are per-workflow and not derivable from a status name,
+ * so this only ever selects from transitions Jira just reported. When nothing
+ * matches, the available names go back with the error - the agent's next move
+ * is to pick one of them, not to try harder at the same one.
+ */
+export function resolveTransition(target, available) {
+    const wanted = target.trim().toLowerCase();
+    const match = available.find((t) => t.to.toLowerCase() === wanted) ??
+        available.find((t) => t.name.toLowerCase() === wanted);
+    if (!match) {
+        throw new JamError("JAM_WRITE_TRANSITION_NOT_AVAILABLE", available.length === 0
+            ? `Jira offers no transitions from this issue's current status for this account, so it cannot be moved to "${target}".`
+            : `"${target}" is not reachable from this issue's current status. Available: ${available.map((t) => t.to).join(", ")}.`, { target, available: available.map((t) => ({ id: t.id, name: t.name, to: t.to })) });
+    }
+    return match;
+}
+export function planExpired(expiresAt, now) {
+    return now.getTime() >= Date.parse(expiresAt);
+}
+/**
+ * Has the issue moved since the plan was made?
+ *
+ * Jira's `updated` timestamp is the revision marker: it changes on any edit,
+ * including ones JAM did not make and cannot see the shape of. Comparing it is
+ * what stops an agent applying a decision it made against an issue that no
+ * longer exists in that form.
+ */
+export function assertUnchanged(issueKey, baseUpdated, currentUpdated) {
+    if (baseUpdated === currentUpdated)
+        return;
+    throw new JamError("JAM_WRITE_CONFLICT", `${issueKey} changed after this plan was made, so the plan no longer describes the issue. Re-plan against the current state.`, { issueKey, planUpdated: baseUpdated, currentUpdated });
+}

package/dist/ports/jira-write.port.d.ts

@@ -1,12 +1,26 @@
+import type { JiraTransition } from "../domain/write.js";
 /**
- * Write path is out of scope for the first release - the structural boundary
- * exists so adding writes later does not reshape the application layer.
- * See ConsistencyPolicy: a write must be confirmed with a direct issue GET,
- * never with a JQL search result.
+ * The mutating half of Jira, kept apart from reading on purpose.
+ *
+ * Two rules govern everything behind this port:
+ *
+ *  - A write is not confirmed by its own HTTP response. ConsistencyPolicy
+ *    requires a direct issue GET afterwards, which is the read port's job -
+ *    this port never reads back its own work.
+ *  - Nothing here retries. A read that times out can be repeated; a POST that
+ *    times out may already have been applied, and repeating it is how one
+ *    comment becomes two. Ambiguity is resolved by looking, not by trying
+ *    again.
+ *
+ * The field map is generic at this layer because Jira's is. The public MCP
+ * surface is not: only whitelisted operations reach it (see domain/write.ts).
  */
 export interface JiraWritePort {
     updateIssue(key: string, fields: Record<string, unknown>): Promise<void>;
     addComment(key: string, body: string): Promise<{
         id: string;
     }>;
+    /** Transitions Jira offers for this issue right now, for this account. */
+    getTransitions(key: string): Promise<JiraTransition[]>;
+    transitionIssue(key: string, transitionId: string): Promise<void>;
 }

package/package.json

@@ -1,69 +1,69 @@
-{
-  "name": "@jam-mcp/server",
-  "version": "1.0.1",
-  "description": "JAM (Jira Agent MCP) - agent-facing Jira access layer: MCP server, setup core, and CLI",
-  "keywords": [
-    "jira",
-    "mcp",
-    "model-context-protocol",
-    "claude-code",
-    "codex",
-    "jira-api"
-  ],
-  "homepage": "https://github.com/colosair/jam#readme",
-  "bugs": {
-    "url": "https://github.com/colosair/jam/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/colosair/jam.git",
-    "directory": "packages/server"
-  },
-  "author": "colosair (https://github.com/colosair)",
-  "type": "module",
-  "bin": {
-    "jam-server": "dist/index.js"
-  },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "engines": {
-    "node": ">=20"
-  },
-  "files": [
-    "dist",
-    "!dist/**/*.js.map",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "dependencies": {
-    "@jam-mcp/launcher": "1.0.1",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "yaml": "^2.9.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^5.9.0",
-    "vitest": "^4.1.11"
-  },
-  "license": "MIT",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./cli-entry": {
-      "types": "./dist/cli-entry.d.ts",
-      "default": "./dist/cli-entry.js"
-    }
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
-}
+{
+  "name": "@jam-mcp/server",
+  "version": "1.1.0",
+  "description": "JAM (Jira Agent MCP) - agent-facing Jira access layer: MCP server, setup core, and CLI",
+  "keywords": [
+    "jira",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "codex",
+    "jira-api"
+  ],
+  "homepage": "https://github.com/colosair/jam#readme",
+  "bugs": {
+    "url": "https://github.com/colosair/jam/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/colosair/jam.git",
+    "directory": "packages/server"
+  },
+  "author": "colosair (https://github.com/colosair)",
+  "type": "module",
+  "bin": {
+    "jam-server": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.js.map",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@jam-mcp/launcher": "1.1.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.11"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli-entry": {
+      "types": "./dist/cli-entry.d.ts",
+      "default": "./dist/cli-entry.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}