@jam-mcp/server 1.1.0 → 1.2.0

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-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,15 @@ 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;
+    responseBytes: number;
+};
 export type GetIssuesResult = {
     issues: FullIssueContext[];
     /** Keys that were requested but not returned (missing or not permitted). */
@@ -59,6 +68,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;

package/package.json

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