@jam-mcp/server 1.1.0 → 1.3.0

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

@@ -0,0 +1,86 @@
+import { type CreateFieldMetadata, type CreateIssueInput, type CreateIssueType, type CreateSchemaRequirements } from "../domain/write.js";
+/**
+ * What JAM will agree to create, decided from what Jira says it accepts.
+ *
+ * Creation is the one write with no issue to look at first, so every check
+ * here is against the project's create schema instead. The rule throughout is
+ * the one the rest of the write plane follows: resolve against what Jira just
+ * reported, never against what the caller asserted or what a name suggests. An
+ * issue type id is not derived from a type name, a priority is not sent
+ * because it looked plausible, and a required field JAM cannot express is
+ * refused here rather than posted and rejected as a 400.
+ */
+/**
+ * Jira field ids for the fields JAM can put on a create.
+ *
+ * The bridge between the public contract (CREATABLE_FIELDS, which an agent
+ * sees) and Jira's own ids (which the required-field gate compares against).
+ * Both directions matter: one decides what may be asked for, the other decides
+ * what counts as "JAM supplies this".
+ */
+export declare const CREATE_FIELD_IDS: {
+    readonly issueType: "issuetype";
+    readonly summary: "summary";
+    readonly description: "description";
+    readonly priority: "priority";
+    readonly labels: "labels";
+    readonly components: "components";
+};
+/**
+ * Match a requested issue type against the ones Jira offers for this project.
+ *
+ * Case-insensitive, because "task" and "Task" are the same intent and an agent
+ * has no way to learn Jira's casing before asking. Nothing else is inferred:
+ * the id comes from Jira's own list, and a type that is not on it is refused
+ * with the list attached, so the next move is to pick one rather than to
+ * rephrase the same one.
+ *
+ * Subtask types are refused separately. They need a parent, which is not in
+ * this version's contract, so "not available" would be the wrong answer - the
+ * type exists, and JAM cannot use it yet.
+ */
+export declare function resolveIssueType(requested: string, available: CreateIssueType[]): CreateIssueType;
+/**
+ * Refuse a create whose project requires something JAM cannot put on it.
+ *
+ * The alternative - post it and let Jira answer 400 - is worse twice over: the
+ * agent gets a vendor error instead of a JAM decision, and creation is the one
+ * write where "did it happen?" is expensive to answer after the fact. So the
+ * answer is worked out before anything is sent.
+ *
+ * A field Jira says it will default is not JAM's to supply. That is Jira
+ * stating a fact about its own configuration, not JAM guessing one.
+ *
+ * Returns the required field ids, which the plan records so apply can tell a
+ * newly-required field from one that was always there.
+ */
+export declare function assertRequiredFieldsSupported(fields: CreateFieldMetadata[], input: CreateIssueInput): string[];
+/**
+ * Turn a requested value into one Jira currently offers for that field.
+ *
+ * An unconstrained field passes the value through: there is no list to check
+ * it against, and inventing one would refuse valid input. Absent and empty are
+ * different - absent means Jira did not constrain the field, empty means it
+ * constrains it and offers nothing.
+ *
+ * The shape is resolveTransition's, deliberately: human intent, then
+ * Jira-provided candidates, then a concrete Jira value. Nothing in between
+ * guesses.
+ */
+export declare function resolveAllowedValue(field: CreateFieldMetadata | undefined, requested: string, label: string): {
+    requested: string;
+    resolved: string;
+};
+/**
+ * Are this plan's premises still true?
+ *
+ * Semantic, not a document comparison. Comparing a hash of the metadata would
+ * make an unrelated optional field appearing on the create screen invalidate
+ * every outstanding plan - which is wrong, and on an active project constant.
+ * What matters is narrower: the issue type still exists, no new required field
+ * has appeared that JAM cannot fill, and every value resolved from an allowed
+ * list is still on it.
+ *
+ * Everything else about the schema may change freely between plan and apply.
+ */
+export declare function assertSchemaUnchanged(requirements: CreateSchemaRequirements, issueTypes: CreateIssueType[], fields: CreateFieldMetadata[], input: CreateIssueInput): void;

package/dist/policy/create-policy.js

@@ -0,0 +1,182 @@
+import { JamError } from "../domain/errors.js";
+import { CREATABLE_FIELDS, } from "../domain/write.js";
+/**
+ * What JAM will agree to create, decided from what Jira says it accepts.
+ *
+ * Creation is the one write with no issue to look at first, so every check
+ * here is against the project's create schema instead. The rule throughout is
+ * the one the rest of the write plane follows: resolve against what Jira just
+ * reported, never against what the caller asserted or what a name suggests. An
+ * issue type id is not derived from a type name, a priority is not sent
+ * because it looked plausible, and a required field JAM cannot express is
+ * refused here rather than posted and rejected as a 400.
+ */
+/**
+ * Jira field ids for the fields JAM can put on a create.
+ *
+ * The bridge between the public contract (CREATABLE_FIELDS, which an agent
+ * sees) and Jira's own ids (which the required-field gate compares against).
+ * Both directions matter: one decides what may be asked for, the other decides
+ * what counts as "JAM supplies this".
+ */
+export const CREATE_FIELD_IDS = {
+    issueType: "issuetype",
+    summary: "summary",
+    description: "description",
+    priority: "priority",
+    labels: "labels",
+    components: "components",
+};
+/** Always sent by JAM, so a project requiring them is still servable. */
+const ALWAYS_SUPPLIED = [CREATE_FIELD_IDS.issueType, CREATE_FIELD_IDS.summary, "project"];
+/**
+ * Fields JAM can supply when asked, and so can satisfy a required flag - but
+ * only if the caller actually asked for them. Required-and-absent is refused.
+ */
+const SUPPLIABLE_ON_REQUEST = {
+    [CREATE_FIELD_IDS.description]: "description",
+    [CREATE_FIELD_IDS.priority]: "priority",
+    [CREATE_FIELD_IDS.labels]: "labels",
+    [CREATE_FIELD_IDS.components]: "components",
+};
+/**
+ * Match a requested issue type against the ones Jira offers for this project.
+ *
+ * Case-insensitive, because "task" and "Task" are the same intent and an agent
+ * has no way to learn Jira's casing before asking. Nothing else is inferred:
+ * the id comes from Jira's own list, and a type that is not on it is refused
+ * with the list attached, so the next move is to pick one rather than to
+ * rephrase the same one.
+ *
+ * Subtask types are refused separately. They need a parent, which is not in
+ * this version's contract, so "not available" would be the wrong answer - the
+ * type exists, and JAM cannot use it yet.
+ */
+export function resolveIssueType(requested, available) {
+    const wanted = requested.trim().toLowerCase();
+    const match = available.find((t) => t.name.toLowerCase() === wanted);
+    if (!match) {
+        const creatable = available.filter((t) => !t.subtask).map((t) => t.name);
+        throw new JamError("JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE", creatable.length === 0
+            ? `Jira offers no issue types this account can create in this project, so "${requested}" cannot be created.`
+            : `"${requested}" is not an issue type this account can create in this project. Available: ${creatable.join(", ")}.`, {
+            requested,
+            available: available.map((t) => ({ id: t.id, name: t.name, subtask: t.subtask })),
+        });
+    }
+    if (match.subtask) {
+        throw new JamError("JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE", `"${match.name}" is a subtask type, which needs a parent issue. JAM does not set a parent, so it cannot create one.`, { requested, issueType: match.name, reason: "SUBTASK_UNSUPPORTED" });
+    }
+    return match;
+}
+/**
+ * Refuse a create whose project requires something JAM cannot put on it.
+ *
+ * The alternative - post it and let Jira answer 400 - is worse twice over: the
+ * agent gets a vendor error instead of a JAM decision, and creation is the one
+ * write where "did it happen?" is expensive to answer after the fact. So the
+ * answer is worked out before anything is sent.
+ *
+ * A field Jira says it will default is not JAM's to supply. That is Jira
+ * stating a fact about its own configuration, not JAM guessing one.
+ *
+ * Returns the required field ids, which the plan records so apply can tell a
+ * newly-required field from one that was always there.
+ */
+export function assertRequiredFieldsSupported(fields, input) {
+    const required = fields.filter((f) => f.required);
+    const unsupported = [];
+    for (const field of required) {
+        if (ALWAYS_SUPPLIED.includes(field.id))
+            continue;
+        if (field.hasDefaultValue)
+            continue;
+        const inputKey = SUPPLIABLE_ON_REQUEST[field.id];
+        if (!inputKey) {
+            unsupported.push({ id: field.id, name: field.name, reason: "NOT_IN_JAM_CREATE_CONTRACT" });
+            continue;
+        }
+        if (input[inputKey] === undefined) {
+            unsupported.push({ id: field.id, name: field.name, reason: "REQUIRED_BUT_NOT_PROVIDED" });
+        }
+    }
+    if (unsupported.length > 0) {
+        const named = unsupported.map((f) => `${f.name} (${f.id})`).join(", ");
+        const it = unsupported.length === 1 ? "it" : "them";
+        throw new JamError("JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED", `This project requires ${named} when creating this issue type, and JAM cannot supply ${it}. Create this issue in Jira instead - JAM will not send a create it already knows Jira will reject.`, { unsupported, supported: [...CREATABLE_FIELDS] });
+    }
+    return required.map((f) => f.id);
+}
+/**
+ * Turn a requested value into one Jira currently offers for that field.
+ *
+ * An unconstrained field passes the value through: there is no list to check
+ * it against, and inventing one would refuse valid input. Absent and empty are
+ * different - absent means Jira did not constrain the field, empty means it
+ * constrains it and offers nothing.
+ *
+ * The shape is resolveTransition's, deliberately: human intent, then
+ * Jira-provided candidates, then a concrete Jira value. Nothing in between
+ * guesses.
+ */
+export function resolveAllowedValue(field, requested, label) {
+    if (!field?.allowedValues)
+        return { requested, resolved: requested };
+    const wanted = requested.trim().toLowerCase();
+    const match = field.allowedValues.find((v) => v.name?.toLowerCase() === wanted);
+    if (!match?.name) {
+        const allowed = field.allowedValues.map((v) => v.name).filter(Boolean);
+        throw new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", allowed.length === 0
+            ? `Jira offers no ${label} values for this project and issue type, so "${requested}" cannot be set.`
+            : `"${requested}" is not an allowed ${label} for this project and issue type. Allowed: ${allowed.join(", ")}.`, { field: field.id, requested, allowed });
+    }
+    return { requested, resolved: match.name };
+}
+/**
+ * Are this plan's premises still true?
+ *
+ * Semantic, not a document comparison. Comparing a hash of the metadata would
+ * make an unrelated optional field appearing on the create screen invalidate
+ * every outstanding plan - which is wrong, and on an active project constant.
+ * What matters is narrower: the issue type still exists, no new required field
+ * has appeared that JAM cannot fill, and every value resolved from an allowed
+ * list is still on it.
+ *
+ * Everything else about the schema may change freely between plan and apply.
+ */
+export function assertSchemaUnchanged(requirements, issueTypes, fields, input) {
+    const stillOffered = issueTypes.find((t) => t.id === requirements.issueTypeId);
+    if (!stillOffered) {
+        throw schemaChanged(`Issue type ${requirements.issueTypeName} is no longer available to this account in this project.`, { issueTypeId: requirements.issueTypeId, issueType: requirements.issueTypeName });
+    }
+    // A required field JAM cannot fill is a refusal whether it was there at plan
+    // time or arrived since - but arriving since is a changed schema rather than
+    // a bad request, so it is reported as one.
+    try {
+        assertRequiredFieldsSupported(fields, input);
+    }
+    catch (err) {
+        if (err instanceof JamError && err.code === "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED") {
+            throw schemaChanged("The create screen for this issue type now requires a field JAM cannot supply.", { cause: err.details });
+        }
+        throw err;
+    }
+    const byId = new Map(fields.map((f) => [f.id, f]));
+    for (const resolved of requirements.resolvedValues) {
+        const allowed = byId.get(resolved.fieldId)?.allowedValues;
+        // A field that stopped being constrained is not a problem: the value JAM
+        // resolved is still a value, and Jira is no longer restricting it.
+        if (!allowed)
+            continue;
+        if (!allowed.some((v) => v.name === resolved.resolved)) {
+            throw schemaChanged(`"${resolved.resolved}" is no longer an allowed value for ${resolved.fieldId} in this project.`, {
+                field: resolved.fieldId,
+                planned: resolved.resolved,
+                allowed: allowed.map((v) => v.name).filter(Boolean),
+            });
+        }
+    }
+}
+function schemaChanged(what, details) {
+    return new JamError("JAM_WRITE_SCHEMA_CHANGED", `${what} This plan was built on the create schema as it was, so it no longer describes a create JAM can make. Nothing was created - plan again against the current schema.`, details);
+}

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

@@ -1,4 +1,4 @@
-import { type FieldUpdateInput, type JiraTransition, type WriteOperation } from "../domain/write.js";
+import { type ExistingIssueOperation, type FieldUpdateInput, type JiraTransition, type WriteOperation } from "../domain/write.js";
 /**
  * What a write is allowed to be, decided before anything reaches Jira.
  *
@@ -32,6 +32,15 @@ export declare function projectKeyOf(issueKey: string): string | undefined;
  */
 export declare function assertWriteScope(issueKey: string, configuredProject: string): string;
 export declare function assertOperationAllowed(operation: string): WriteOperation;
+/**
+ * Narrow an already-allowed operation to one that acts on an existing issue.
+ *
+ * Reached only after routing has sent `issue.create` elsewhere, so this is a
+ * type-level guarantee rather than a second policy decision - but it is a
+ * guarantee worth having, because everything downstream reads an issue key
+ * that creation does not have.
+ */
+export declare function assertExistingIssueOperation(operation: string): ExistingIssueOperation;
 /**
  * Reject anything outside the field whitelist before planning goes further.
  *

package/dist/policy/write-policy.js

@@ -1,5 +1,5 @@
 import { JamError } from "../domain/errors.js";
-import { isWritableField, isWriteOperation, WRITABLE_FIELDS, WRITE_OPERATIONS, } from "../domain/write.js";
+import { EXISTING_ISSUE_OPERATIONS, isExistingIssueOperation, isWritableField, isWriteOperation, WRITABLE_FIELDS, WRITE_OPERATIONS, } from "../domain/write.js";
 /**
  * What a write is allowed to be, decided before anything reaches Jira.
  *
@@ -54,6 +54,20 @@ export function assertOperationAllowed(operation) {
     }
     return operation;
 }
+/**
+ * Narrow an already-allowed operation to one that acts on an existing issue.
+ *
+ * Reached only after routing has sent `issue.create` elsewhere, so this is a
+ * type-level guarantee rather than a second policy decision - but it is a
+ * guarantee worth having, because everything downstream reads an issue key
+ * that creation does not have.
+ */
+export function assertExistingIssueOperation(operation) {
+    if (!isExistingIssueOperation(operation)) {
+        throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", `"${operation}" does not change an existing issue. Operations that do: ${EXISTING_ISSUE_OPERATIONS.join(", ")}.`, { operation, supported: [...EXISTING_ISSUE_OPERATIONS] });
+    }
+    return operation;
+}
 /**
  * Reject anything outside the field whitelist before planning goes further.
  *

package/dist/ports/jira-assignee-resolution.port.d.ts

@@ -0,0 +1,51 @@
+import type { AssigneeCandidate } from "../domain/write.js";
+/**
+ * Who Jira thinks a name refers to, and whether they can hold this issue.
+ *
+ * A third read-shaped port, for the same reason `JiraCreateMetadataPort` is
+ * one: nothing here mutates, so it does not belong behind the write port's
+ * no-retry contract, and it answers a question about a directory rather than
+ * about an issue, so the read port's completeness semantics would mean nothing
+ * for it.
+ *
+ * The two calls are deliberately separate questions. Searching answers "who
+ * did the caller mean", and it is allowed to be fuzzy - Jira matches on
+ * substrings, and a partial match is a suggestion to show a human. Checking
+ * assignability answers "may this exact person hold this exact issue", and it
+ * is not fuzzy at all: it takes an accountId that resolution has already
+ * settled on. Collapsing them would let a substring match decide a mutation.
+ *
+ * Neither call retries. Their answers decide a mutation, and a retried answer
+ * is a possibly-stale one - the same argument that keeps `getTransitions` and
+ * the create metadata calls on the non-retrying side.
+ */
+export interface JiraAssigneeResolutionPort {
+    /**
+     * Users matching a query, as Jira's own directory reports them.
+     *
+     * Fuzzy by nature. What comes back is candidates, never a decision - see
+     * `resolveAssignee` for what JAM will and will not do with them.
+     */
+    searchUsers(query: string): Promise<AssigneeCandidate[]>;
+    /**
+     * One user, looked up by identity rather than found by searching.
+     *
+     * JAM's contract says `assignee` may be an accountId, and a contract about
+     * identity has to be met by an identity lookup. Jira's user search does
+     * currently return a user when the query happens to be their accountId, but
+     * that is a property of a substring search, not a promise - relying on it
+     * means the accountId half of the contract holds by coincidence.
+     *
+     * Absent means Jira has no such account, or this token cannot see it. Both
+     * are "you cannot assign this", which is the caller's answer either way.
+     */
+    getUserByAccountId(accountId: string): Promise<AssigneeCandidate | undefined>;
+    /**
+     * Whether this exact account may be assigned this exact issue, right now.
+     *
+     * Asked by accountId, so it is an identity question rather than a name one.
+     * Asked again immediately before the write, because a permission that held
+     * when the plan was made is not the same as one that still holds.
+     */
+    isAssignable(issueKey: string, accountId: string): Promise<boolean>;
+}

package/dist/ports/jira-assignee-resolution.port.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/jira-create-metadata.port.d.ts

@@ -0,0 +1,25 @@
+import type { CreateFieldMetadata, CreateIssueType } from "../domain/write.js";
+/**
+ * What Jira will accept when creating an issue in one project, right now.
+ *
+ * Separate from `JiraWritePort` on purpose. Everything behind that port
+ * changes something; nothing behind this one does. Folding schema discovery
+ * into the write port would put a read on the far side of a boundary whose
+ * whole documented rule is "these calls mutate, and none of them retry" - and
+ * the rule is worth more than the one fewer interface.
+ *
+ * Kept out of `JiraReadPort` too, for the opposite reason: that port answers
+ * questions about issues, with completeness semantics attached to every
+ * result. This answers a question about a project's configuration, and
+ * `meta.complete` would mean nothing here.
+ *
+ * These calls do not retry. Their answers decide a mutation, and a retried
+ * answer is a possibly-stale one - the same argument that keeps
+ * `getTransitions` on the non-retrying side.
+ */
+export interface JiraCreateMetadataPort {
+    /** Issue types this account may create in this project. */
+    getIssueTypes(projectKey: string): Promise<CreateIssueType[]>;
+    /** The create screen's fields for one issue type in one project. */
+    getCreateFields(projectKey: string, issueTypeId: string): Promise<CreateFieldMetadata[]>;
+}

package/dist/ports/jira-create-metadata.port.js

@@ -0,0 +1 @@
+export {};

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

@@ -20,6 +20,26 @@ export type GetIssuesRequest = {
     keys: string[];
     fields: string[];
 };
+export type GetIssueRequest = {
+    key: string;
+    fields: string[];
+};
+export type GetIssueResult = {
+    /** Absent when Jira has no such issue, or this account cannot see it. */
+    issue?: FullIssueContext;
+    /**
+     * Who the issue is assigned to, by identity rather than by name.
+     *
+     * Here rather than on the issue because only the write plane needs it. Two
+     * people can share a display name, so `assignee` cannot settle whether an
+     * assignment landed on the right person - and the read tools have no use for
+     * an accountId, so their payload does not grow one.
+     *
+     * Absent when the issue is unassigned, or when the field was not requested.
+     */
+    assigneeAccountId?: string;
+    responseBytes: number;
+};
 export type GetIssuesResult = {
     issues: FullIssueContext[];
     /** Keys that were requested but not returned (missing or not permitted). */
@@ -59,6 +79,20 @@ export type ListProjectsResult = {
 };
 export interface JiraReadPort {
     searchPage(req: SearchPageRequest): Promise<SearchPageResult>;
+    /**
+     * One issue, read directly by key.
+     *
+     * Separate from `getIssues` because ConsistencyPolicy requires a direct
+     * issue GET for anything that decides or confirms a write, and `getIssues`
+     * is not one: it is a bulk endpoint that takes a list, and a bulk read is
+     * free to answer from a different path than a single-issue GET. The
+     * distinction only matters in one place - the write plane - which is exactly
+     * where being wrong about it is most expensive.
+     *
+     * Reads and writes both use it: the pre-write conflict check, the post-write
+     * confirmation, and the post-create confirmation.
+     */
+    getIssue(req: GetIssueRequest): Promise<GetIssueResult>;
     getIssues(req: GetIssuesRequest): Promise<GetIssuesResult>;
     getComments(req: GetCommentsRequest): Promise<GetCommentsResult>;
     /** Used by `jam doctor` to prove authentication works. */

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

@@ -16,6 +16,15 @@ import type { JiraTransition } from "../domain/write.js";
  * surface is not: only whitelisted operations reach it (see domain/write.ts).
  */
 export interface JiraWritePort {
+    /**
+     * Create one issue. The only call here that brings an issue into existence,
+     * and the one where a retry is most expensive: a duplicate update is a
+     * no-op, a duplicate create is a second issue on someone's board.
+     */
+    createIssue(fields: Record<string, unknown>): Promise<{
+        id: string;
+        key: string;
+    }>;
     updateIssue(key: string, fields: Record<string, unknown>): Promise<void>;
     addComment(key: string, body: string): Promise<{
         id: string;
@@ -23,4 +32,12 @@ export interface JiraWritePort {
     /** Transitions Jira offers for this issue right now, for this account. */
     getTransitions(key: string): Promise<JiraTransition[]>;
     transitionIssue(key: string, transitionId: string): Promise<void>;
+    /**
+     * Assign an issue to one account.
+     *
+     * By accountId, never by name: Jira Cloud identifies users by account, and a
+     * display name is a label two people can share. Which account it is was
+     * settled during planning.
+     */
+    assignIssue(key: string, accountId: string): Promise<void>;
 }

package/package.json

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