@jam-mcp/server 1.3.0 → 1.3.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 colosair
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 colosair
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,86 +1,90 @@
-# @jam-mcp/server
-
-JAM (Jira Agent MCP) itself: the MCP server, the setup core, and the `jam` CLI.
-
-JAM is an agent-facing Jira **read** layer. It takes over the decisions an agent
-should not be making — which fields to request, when to paginate, when to read
-the comment thread, what to do when a result is too big — so everyday reads stay
-cheap and important judgements still get full context.
-
-## The tools
-
-The external contract is five tools. Adding or renaming one is a breaking
-change.
-
-| Tool | Use it for |
-|---|---|
-| `jira_search` | listing, discovery, "what's open", picking candidates |
-| `jira_context` | readiness, blockers, dependencies, priority |
-| `jira_full` | agreement, contract, approval, closure |
-| `jira_write_plan` | work out how to change an issue — changes nothing |
-| `jira_write_apply` | apply a plan, then confirm it by reading the issue back |
-
-A `jira_search` result is never complete issue context — nothing about
-agreement, approval, or done-ness follows from it.
-
-Writing is deliberately two calls. `jira_write_apply` takes a `planId` and no
-payload, so a change cannot be made that JAM has not first read the issue for,
-checked against the configured project, and described. Before writing it
-re-reads the issue and refuses if it moved; after writing it reads again and
-refuses to report success unless the intended result is actually there. An
-ambiguous failure is reported as uncertain rather than retried — retrying a
-write that may have landed is how one comment becomes two.
-
-Three operations: `comment.add` (plain text, converted to ADF here),
-`field.update` (summary, priority, labels, components), and `status.transition`
-(matched against the transitions Jira currently offers, never a guessed id).
-
-## Evidence boundary
-
-Every result carries a `meta` block, and nothing is ever truncated silently.
-
-`meta.complete` means **JAM finished the Jira retrieval with no known loss**. It
-is not a statement about the project: not readiness, not "unblocked", not "the
-whole story". What JAM did not look at is named in the same block —
-`evidenceScope` and `limitations` call out the repository, external sources, and
-dependencies that live outside Jira. `provenance` and `source` say where the
-records came from.
-
-So an empty comment thread on a complete read is a complete read *of Jira*, not
-proof that nothing was agreed. If the issue points at an external canonical
-source, that source is what settles the question.
-
-## Running it
-
-Don't install this package to use JAM. Your coding agent launches
-[`@jam-mcp/launcher`](https://www.npmjs.com/package/@jam-mcp/launcher), which
-reads your `~/.jam/config.yaml`, decides which JAM build this machine should
-run, and dispatches here. Naming the server directly instead pins one machine
-to one build and bypasses that choice — and it is what keeps a committed
-`.mcp.json` free of machine-specific paths.
-
-The same binary carries the CLI, and every command below is reachable through
-the launcher:
-
-```text
-serve        Run the MCP server over stdio
-doctor       Diagnose config, credentials and Jira connectivity
-setup        Wire up JAM and verify (personal by default; --shared for the team)
-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.3.0 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.3.0 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
-results. `stdout` is reserved for the MCP protocol and for JSON output;
-diagnostics go to `stderr`.
-
-## More
-
-- [Repository README](https://github.com/colosair/jam#readme)
-- [JAM design of record](https://github.com/colosair/jam/blob/main/docs/architecture/jira-agent-mcp-design.md)
+# @jam-mcp/server
+
+JAM (Jira Agent MCP) itself: the MCP server, the setup core, and the `jam` CLI.
+
+JAM is an agent-facing Jira **read** layer. It takes over the decisions an agent
+should not be making — which fields to request, when to paginate, when to read
+the comment thread, what to do when a result is too big — so everyday reads stay
+cheap and important judgements still get full context.
+
+## The tools
+
+The external contract is five tools. Adding or renaming one is a breaking
+change.
+
+| Tool | Use it for |
+|---|---|
+| `jira_search` | listing, discovery, "what's open", picking candidates |
+| `jira_context` | readiness, blockers, dependencies, priority |
+| `jira_full` | agreement, contract, approval, closure |
+| `jira_write_plan` | work out how to change an issue — changes nothing |
+| `jira_write_apply` | apply a plan, then confirm it by reading the issue back |
+
+A `jira_search` result is never complete issue context — nothing about
+agreement, approval, or done-ness follows from it.
+
+Writing is deliberately two calls. `jira_write_apply` takes a `planId` and no
+payload, so a change cannot be made that JAM has not first read the issue for,
+checked against the configured project, and described. Before writing it
+re-reads the issue and refuses if it moved; after writing it reads again and
+refuses to report success unless the intended result is actually there. An
+ambiguous failure is reported as uncertain rather than retried — retrying a
+write that may have landed is how one comment becomes two.
+
+Five operations: `comment.add` (plain text, converted to ADF here),
+`field.update` (summary, priority, labels, components), `status.transition`
+(matched against the transitions Jira currently offers, never a guessed id),
+`assignee.update` (resolved to an account by exact display name or accountId,
+never a substring match), and `issue.create` (planned against the project's own
+create schema, so an unavailable issue type is a refusal here rather than a
+Jira 400 later).
+
+## Evidence boundary
+
+Every result carries a `meta` block, and nothing is ever truncated silently.
+
+`meta.complete` means **JAM finished the Jira retrieval with no known loss**. It
+is not a statement about the project: not readiness, not "unblocked", not "the
+whole story". What JAM did not look at is named in the same block —
+`evidenceScope` and `limitations` call out the repository, external sources, and
+dependencies that live outside Jira. `provenance` and `source` say where the
+records came from.
+
+So an empty comment thread on a complete read is a complete read *of Jira*, not
+proof that nothing was agreed. If the issue points at an external canonical
+source, that source is what settles the question.
+
+## Running it
+
+Don't install this package to use JAM. Your coding agent launches
+[`@jam-mcp/launcher`](https://www.npmjs.com/package/@jam-mcp/launcher), which
+reads your `~/.jam/config.yaml`, decides which JAM build this machine should
+run, and dispatches here. Naming the server directly instead pins one machine
+to one build and bypasses that choice — and it is what keeps a committed
+`.mcp.json` free of machine-specific paths.
+
+The same binary carries the CLI, and every command below is reachable through
+the launcher:
+
+```text
+serve        Run the MCP server over stdio
+doctor       Diagnose config, credentials and Jira connectivity
+setup        Wire up JAM and verify (personal by default; --shared for the team)
+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.3.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.3.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
+results. `stdout` is reserved for the MCP protocol and for JSON output;
+diagnostics go to `stderr`.
+
+## More
+
+- [Repository README](https://github.com/colosair/jam#readme)
+- [JAM design of record](https://github.com/colosair/jam/blob/main/docs/architecture/jira-agent-mcp-design.md)

package/dist/adapters/jira-cloud/jira-edit-metadata.adapter.d.ts

@@ -0,0 +1,25 @@
+import type { EditFieldMetadata } from "../../domain/write.js";
+import type { CredentialPort } from "../../ports/credentials.port.js";
+import type { JiraEditMetadataPort } from "../../ports/jira-edit-metadata.port.js";
+/**
+ * Jira Cloud REST v3 edit metadata for one issue.
+ *
+ * `GET /rest/api/3/issue/{key}/editmeta`, `retry: false`. Its answer decides
+ * whether a mutation may proceed and what shape it takes, so a
+ * retried-and-stale answer is worse than a failure - the same argument that
+ * keeps `getTransitions`, the create metadata calls and the assignability
+ * check on the non-retrying side.
+ *
+ * Jira keys the response by field id, and describes each field with a `schema`
+ * and a list of `operations`. Both travel, because both are what the decision
+ * is made in; the rest of the document does not.
+ *
+ * Anything JAM cannot read is dropped rather than half-understood. A field
+ * that survives here with the wrong shape would be a field JAM claims to
+ * understand well enough to write.
+ */
+export declare class JiraCloudEditMetadataAdapter implements JiraEditMetadataPort {
+    private readonly client;
+    constructor(credentials: CredentialPort, fetchImpl?: typeof fetch);
+    getEditableFields(issueKey: string): Promise<EditFieldMetadata[]>;
+}

package/dist/adapters/jira-cloud/jira-edit-metadata.adapter.js

@@ -0,0 +1,84 @@
+import { JiraClient } from "./jira-client.js";
+/**
+ * Jira Cloud REST v3 edit metadata for one issue.
+ *
+ * `GET /rest/api/3/issue/{key}/editmeta`, `retry: false`. Its answer decides
+ * whether a mutation may proceed and what shape it takes, so a
+ * retried-and-stale answer is worse than a failure - the same argument that
+ * keeps `getTransitions`, the create metadata calls and the assignability
+ * check on the non-retrying side.
+ *
+ * Jira keys the response by field id, and describes each field with a `schema`
+ * and a list of `operations`. Both travel, because both are what the decision
+ * is made in; the rest of the document does not.
+ *
+ * Anything JAM cannot read is dropped rather than half-understood. A field
+ * that survives here with the wrong shape would be a field JAM claims to
+ * understand well enough to write.
+ */
+export class JiraCloudEditMetadataAdapter {
+    client;
+    constructor(credentials, fetchImpl) {
+        this.client = fetchImpl ? new JiraClient(credentials, fetchImpl) : new JiraClient(credentials);
+    }
+    async getEditableFields(issueKey) {
+        const { data } = await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(issueKey)}/editmeta`,
+            retry: false,
+        });
+        const fields = data?.fields;
+        if (!fields || typeof fields !== "object")
+            return [];
+        return Object.entries(fields)
+            .map(([id, raw]) => toEditField(id, raw))
+            .filter((f) => f !== undefined);
+    }
+}
+function toEditField(id, raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    // A field with no schema type is a field JAM cannot classify, and an
+    // unclassifiable field is one it must not decide it can write.
+    const type = typeof raw.schema?.type === "string" ? raw.schema.type : undefined;
+    if (!type)
+        return undefined;
+    const allowed = toOptions(raw.allowedValues);
+    return {
+        id,
+        name: typeof raw.name === "string" ? raw.name : id,
+        required: raw.required === true,
+        operations: Array.isArray(raw.operations)
+            ? raw.operations.filter((op) => typeof op === "string")
+            : [],
+        schema: {
+            type,
+            ...(typeof raw.schema?.items === "string" ? { items: raw.schema.items } : {}),
+            ...(typeof raw.schema?.custom === "string" ? { custom: raw.schema.custom } : {}),
+            ...(typeof raw.schema?.customId === "number" ? { customId: raw.schema.customId } : {}),
+        },
+        ...(allowed ? { allowedValues: allowed } : {}),
+    };
+}
+/**
+ * The options Jira offers, when it constrains the field at all.
+ *
+ * Absent and empty mean different things and stay apart: absent is "Jira did
+ * not constrain this", empty is "Jira constrains it and offers nothing". The
+ * first permits a free value, the second permits none.
+ *
+ * Jira labels an option `value` on a select and `name` on some other pickers.
+ * Both are read; an option with neither an id nor a label is dropped, because
+ * it can be neither chosen nor recognised afterwards.
+ */
+function toOptions(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    return raw
+        .map((entry) => {
+        const o = entry;
+        const id = typeof o?.id === "string" ? o.id : typeof o?.id === "number" ? String(o.id) : undefined;
+        const label = typeof o?.value === "string" ? o.value : typeof o?.name === "string" ? o.name : undefined;
+        return id && label ? { id, label } : undefined;
+    })
+        .filter((o) => o !== undefined);
+}

package/dist/adapters/jira-cloud/jira-read.adapter.js

@@ -45,11 +45,21 @@ export class JiraCloudReadAdapter {
         // Read straight off the raw payload rather than through the mapper: the
         // mapper's job is the shape the read tools see, and this identity is only
         // for the write plane. Raw DTOs still stop here.
-        const assignee = data.fields?.assignee;
+        const raw = data.fields;
+        const assignee = raw?.["assignee"];
         const accountId = typeof assignee?.accountId === "string" ? assignee.accountId : undefined;
+        // Only the ids that were asked for, and only when some were: a caller that
+        // did not request a custom field gets no entry rather than an empty object
+        // it has to tell apart from a field that is genuinely unset.
+        const customFieldValues = {};
+        for (const field of req.fields) {
+            if (field.startsWith("customfield_"))
+                customFieldValues[field] = raw?.[field] ?? null;
+        }
         return {
             issue: mapIssueWithMeta(data, this.config).issue,
             ...(accountId ? { assigneeAccountId: accountId } : {}),
+            ...(Object.keys(customFieldValues).length > 0 ? { customFieldValues } : {}),
             responseBytes: bytes,
         };
     }

package/dist/application/apply-write.js

@@ -1,9 +1,10 @@
 import { JamError, toJamError } from "../domain/errors.js";
 import { readModeAfterWrite } from "../policy/consistency-policy.js";
 import { assertAssignable } from "../policy/assignee-policy.js";
+import { assertCustomFieldUnchanged } from "../policy/custom-field-policy.js";
 import { assertUnchanged } from "../policy/write-policy.js";
 import { applyCreateIssue } from "./apply-create-issue.js";
-import { readIssue } from "./plan-write.js";
+import { currentCustomFieldView, readIssue } from "./plan-write.js";
 /**
  * Execute a plan JAM made, then go and look at what happened.
  *
@@ -62,10 +63,18 @@ export async function applyWritePlan(deps, request) {
  * own state, which `assertUnchanged` already compared.
  */
 async function revalidate(deps, plan) {
-    if (plan.mutation.kind !== "assignee")
+    if (plan.mutation.kind === "assignee") {
+        const target = plan.intendedAfter["assignee"];
+        assertAssignable(plan.issueKey, target, await deps.jiraAssignees.isAssignable(plan.issueKey, plan.mutation.accountId));
         return;
-    const target = plan.intendedAfter["assignee"];
-    assertAssignable(plan.issueKey, target, await deps.jiraAssignees.isAssignable(plan.issueKey, plan.mutation.accountId));
+    }
+    if (plan.mutation.kind === "custom-field" && plan.customFieldRequirements) {
+        // A field can be taken off a screen, lose its `set` operation, change type
+        // or have an option renamed without the issue's own revision moving, so
+        // `assertUnchanged` cannot see any of it. These are the premises the plan
+        // actually rested on, re-derived.
+        assertCustomFieldUnchanged(plan.issueKey, plan.customFieldRequirements, await deps.jiraEditMetadata.getEditableFields(plan.issueKey));
+    }
 }
 /**
  * Send the mutation, once.
@@ -92,6 +101,14 @@ async function mutate(deps, plan) {
             case "assignee":
                 await deps.jiraWrite.assignIssue(plan.issueKey, plan.mutation.accountId);
                 return {};
+            case "custom-field":
+                // The ordinary issue edit endpoint. A custom field is a field; what
+                // made it need its own operation was deciding whether it may be
+                // written and in what shape, and that is already settled here.
+                await deps.jiraWrite.updateIssue(plan.issueKey, {
+                    [plan.mutation.fieldId]: plan.mutation.value,
+                });
+                return {};
             case "create":
                 // Unreachable: a create plan is routed to applyCreateIssue above. The
                 // case exists so adding a mutation kind is a compile error here rather
@@ -124,7 +141,7 @@ function isAmbiguous(err) {
  * ours.
  */
 async function verify(deps, plan) {
-    const snapshot = await readIssue(deps, plan.issueKey);
+    const snapshot = await readIssue(deps, plan.issueKey, plan.mutation.kind === "custom-field" ? [plan.mutation.fieldId] : []);
     const issue = snapshot.issue;
     if (plan.mutation.kind === "assignee") {
         // On the accountId, never on the display name. Two people can share a
@@ -156,6 +173,15 @@ async function verify(deps, plan) {
         }
         return { comments: comments.length, commentAdded: wanted };
     }
+    if (plan.mutation.kind === "custom-field" && plan.customFieldRequirements) {
+        const requirements = plan.customFieldRequirements;
+        const expected = plan.intendedAfter["customField"];
+        const observedValue = currentCustomFieldView({ id: requirements.fieldId, name: requirements.fieldName }, requirements.kind, snapshot.customFieldValues?.[requirements.fieldId]);
+        if (!sameCustomFieldValue(requirements.kind, expected.value, observedValue.value)) {
+            throw verificationFailed(plan, { customField: expected }, { customField: observedValue });
+        }
+        return { customField: observedValue };
+    }
     const observed = observedFor(plan, issue);
     for (const [field, expected] of Object.entries(plan.intendedAfter)) {
         if (!sameValue(observed[field], expected)) {
@@ -189,6 +215,27 @@ function observedFor(plan, issue) {
     }
     return observed;
 }
+/**
+ * Did the field end up holding what was planned?
+ *
+ * Options are compared on their ids, never on their labels - an option is
+ * identified by its id, and a label is what a person reads. For a multi-select
+ * the comparison is set-wise: Jira is free to return the same selection in a
+ * different order, and that is not a different selection.
+ */
+function sameCustomFieldValue(kind, expected, observed) {
+    if (kind === "multi-option") {
+        const ids = (v) => (Array.isArray(v) ? v.map((o) => o.id) : []).sort();
+        const a = ids(expected);
+        const b = ids(observed);
+        return a.length === b.length && a.every((id, i) => id === b[i]);
+    }
+    if (kind === "single-option") {
+        const id = (v) => v && typeof v === "object" && !Array.isArray(v) ? v.id : undefined;
+        return id(expected) === id(observed);
+    }
+    return expected === observed;
+}
 function sameValue(observed, expected) {
     if (Array.isArray(expected) || Array.isArray(observed)) {
         const a = Array.isArray(observed) ? [...observed].map(String).sort() : [];

package/dist/application/plan-write.d.ts

@@ -1,6 +1,6 @@
 import type { JamDeps } from "../deps.js";
 import type { FullIssueContext } from "../domain/context.js";
-import type { WritePlan, WritePlanReceipt } from "../domain/write.js";
+import type { CustomFieldKind, CustomFieldValueView, WritePlan, WritePlanReceipt } from "../domain/write.js";
 export type PlanWriteRequest = {
     /** Absent for `issue.create`, which names a project rather than an issue. */
     key?: string;
@@ -40,5 +40,18 @@ export type IssueSnapshot = {
     issue: FullIssueContext;
     /** Identity of the current assignee, which `issue.assignee` cannot supply. */
     assigneeAccountId?: string;
+    /** Raw values for any custom field ids that were asked for. */
+    customFieldValues?: Record<string, unknown>;
 };
-export declare function readIssue(deps: JamDeps, issueKey: string): Promise<IssueSnapshot>;
+export declare function readIssue(deps: JamDeps, issueKey: string, extraFields?: string[]): Promise<IssueSnapshot>;
+/**
+ * What the field holds now, in the shape a receipt shows.
+ *
+ * Jira stores an option as an object and a scalar as itself; a person reading
+ * `before` wants the same canonical form they will see in `intendedAfter`, so
+ * they can compare the two rather than a payload against a summary.
+ */
+export declare function currentCustomFieldView(field: {
+    id: string;
+    name: string;
+}, kind: CustomFieldKind, raw: unknown): CustomFieldValueView;