@jam-mcp/server 1.2.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.2.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.2.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-assignee-resolution.adapter.d.ts

@@ -0,0 +1,39 @@
+import type { AssigneeCandidate } from "../../domain/write.js";
+import type { CredentialPort } from "../../ports/credentials.port.js";
+import type { JiraAssigneeResolutionPort } from "../../ports/jira-assignee-resolution.port.js";
+/**
+ * Jira Cloud REST v3 user directory, read-only.
+ *
+ * Two endpoints, two questions:
+ *
+ *  - `GET /rest/api/3/user/search?query=` - who might this name mean. Jira
+ *    matches display name and, where privacy settings allow it, email. The
+ *    answers are candidates.
+ *  - `GET /rest/api/3/user/assignable/search?issueKey=&accountId=` - may this
+ *    exact account hold this exact issue. Jira answers with the account when
+ *    it may and with nothing when it may not, which is the assignability check
+ *    without JAM having to interpret a permission model it does not own.
+ *
+ * `retry: false` on both. Their answers decide a mutation, so a
+ * retried-and-stale answer is worse than a failure.
+ *
+ * Email is deliberately not part of the identity JAM works with. Jira's
+ * privacy settings routinely blank it - most users on a real site come back
+ * with `emailAddress: ""` - so resolving on it would work for some people and
+ * silently fail for others on the same site.
+ */
+export declare class JiraCloudAssigneeResolutionAdapter implements JiraAssigneeResolutionPort {
+    private readonly client;
+    constructor(credentials: CredentialPort, fetchImpl?: typeof fetch);
+    searchUsers(query: string): Promise<AssigneeCandidate[]>;
+    /**
+     * `GET /rest/api/3/user?accountId=` - the exact lookup, not a search.
+     *
+     * Jira answers 404 when no such account exists or this token cannot see it.
+     * Both mean the same thing to a caller who wanted to assign it, so both
+     * become `undefined` rather than an error: "there is nobody to assign" is an
+     * answer, and the policy layer is where it turns into a refusal.
+     */
+    getUserByAccountId(accountId: string): Promise<AssigneeCandidate | undefined>;
+    isAssignable(issueKey: string, accountId: string): Promise<boolean>;
+}

package/dist/adapters/jira-cloud/jira-assignee-resolution.adapter.js

@@ -0,0 +1,94 @@
+import { JamError } from "../../domain/errors.js";
+import { JiraClient } from "./jira-client.js";
+/** How many candidates are worth reporting back to a human. */
+const SEARCH_LIMIT = 20;
+/**
+ * Jira Cloud REST v3 user directory, read-only.
+ *
+ * Two endpoints, two questions:
+ *
+ *  - `GET /rest/api/3/user/search?query=` - who might this name mean. Jira
+ *    matches display name and, where privacy settings allow it, email. The
+ *    answers are candidates.
+ *  - `GET /rest/api/3/user/assignable/search?issueKey=&accountId=` - may this
+ *    exact account hold this exact issue. Jira answers with the account when
+ *    it may and with nothing when it may not, which is the assignability check
+ *    without JAM having to interpret a permission model it does not own.
+ *
+ * `retry: false` on both. Their answers decide a mutation, so a
+ * retried-and-stale answer is worse than a failure.
+ *
+ * Email is deliberately not part of the identity JAM works with. Jira's
+ * privacy settings routinely blank it - most users on a real site come back
+ * with `emailAddress: ""` - so resolving on it would work for some people and
+ * silently fail for others on the same site.
+ */
+export class JiraCloudAssigneeResolutionAdapter {
+    client;
+    constructor(credentials, fetchImpl) {
+        this.client = fetchImpl ? new JiraClient(credentials, fetchImpl) : new JiraClient(credentials);
+    }
+    async searchUsers(query) {
+        const { data } = await this.client.request({
+            path: "rest/api/3/user/search",
+            query: { query, maxResults: SEARCH_LIMIT },
+            retry: false,
+        });
+        return toCandidates(data);
+    }
+    /**
+     * `GET /rest/api/3/user?accountId=` - the exact lookup, not a search.
+     *
+     * Jira answers 404 when no such account exists or this token cannot see it.
+     * Both mean the same thing to a caller who wanted to assign it, so both
+     * become `undefined` rather than an error: "there is nobody to assign" is an
+     * answer, and the policy layer is where it turns into a refusal.
+     */
+    async getUserByAccountId(accountId) {
+        try {
+            const { data } = await this.client.request({
+                path: "rest/api/3/user",
+                query: { accountId },
+                retry: false,
+            });
+            return toCandidates([data])[0];
+        }
+        catch (err) {
+            if (err instanceof JamError && err.code === "ISSUE_NOT_FOUND")
+                return undefined;
+            throw err;
+        }
+    }
+    async isAssignable(issueKey, accountId) {
+        const { data } = await this.client.request({
+            path: "rest/api/3/user/assignable/search",
+            query: { issueKey, accountId, maxResults: 1 },
+            retry: false,
+        });
+        // Jira answers with the account when it is assignable and with an empty
+        // list when it is not. Matching the id back is belt and braces: an answer
+        // about somebody else is not an answer to the question that was asked.
+        return toCandidates(data).some((u) => u.accountId === accountId);
+    }
+}
+/**
+ * Users JAM can work with, from whatever Jira sent.
+ *
+ * An entry with no accountId is dropped: accountId is the identity, and an
+ * entry without one cannot be assigned, verified, or told apart from another.
+ * App and customer accounts are dropped too - they are not people a human
+ * meant to name, and offering one as a candidate invites assigning an issue to
+ * an integration.
+ */
+function toCandidates(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((u) => typeof u?.accountId === "string" &&
+        (u.accountType === undefined || u.accountType === "atlassian"))
+        .map((u) => ({
+        accountId: u.accountId,
+        displayName: typeof u.displayName === "string" ? u.displayName : u.accountId,
+        active: u.active !== false,
+    }));
+}

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

@@ -42,7 +42,26 @@ export class JiraCloudReadAdapter {
         });
         if (!data?.key)
             return { responseBytes: bytes };
-        return { issue: mapIssueWithMeta(data, this.config).issue, responseBytes: bytes };
+        // 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 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,
+        };
     }
     async getIssues(req) {
         const issues = [];

package/dist/adapters/jira-cloud/jira-write.adapter.d.ts

@@ -43,5 +43,14 @@ export declare class JiraCloudWriteAdapter implements JiraWritePort {
         id: string;
     }>;
     getTransitions(key: string): Promise<JiraTransition[]>;
+    /**
+     * `PUT /rest/api/3/issue/{key}/assignee` with an accountId.
+     *
+     * The dedicated assignment endpoint rather than a field update: assignment
+     * has its own permission and its own Jira semantics, and routing it through
+     * the generic field PUT would put it behind the field whitelist, where it
+     * does not belong.
+     */
+    assignIssue(key: string, accountId: string): Promise<void>;
     transitionIssue(key: string, transitionId: string): Promise<void>;
 }

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

@@ -91,6 +91,22 @@ export class JiraCloudWriteAdapter {
             to: t.to?.name ?? t.name ?? "",
         }));
     }
+    /**
+     * `PUT /rest/api/3/issue/{key}/assignee` with an accountId.
+     *
+     * The dedicated assignment endpoint rather than a field update: assignment
+     * has its own permission and its own Jira semantics, and routing it through
+     * the generic field PUT would put it behind the field whitelist, where it
+     * does not belong.
+     */
+    async assignIssue(key, accountId) {
+        await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(key)}/assignee`,
+            method: "PUT",
+            body: { accountId },
+            retry: false,
+        });
+    }
     async transitionIssue(key, transitionId) {
         await this.client.request({
             path: `rest/api/3/issue/${encodeURIComponent(key)}/transitions`,

package/dist/application/apply-create-issue.js

@@ -127,7 +127,7 @@ async function verify(deps, plan, issueKey) {
     if (createdProject !== plan.projectKey) {
         throw verificationFailed(plan, issueKey, { project: plan.projectKey }, { project: createdProject ?? issueKey });
     }
-    const issue = await readIssue(deps, issueKey);
+    const { issue } = await readIssue(deps, issueKey);
     const observed = {};
     for (const field of Object.keys(plan.intendedAfter)) {
         observed[field] = observedValue(issue, field);