@jam-mcp/server 1.0.0

package/dist/mcp/tools/jira-search.tool.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { searchIssues } from "../../application/search-issues.js";
+import { runTool } from "../tool-result.js";
+const DESCRIPTION = `Find Jira issues by JQL and get a lightweight list back.
+
+Use for: discovery, listing, "what is open", "what is assigned to me", recent changes, picking candidate issues.
+
+Returns key, summary, status, assignee, priority, updated, labels and components only. It deliberately does NOT return description, comments, attachments or links - that keeps listing cheap.
+
+Because of that, a jira_search result is NOT complete issue context. Never conclude from it that something is agreed, approved, unblocked, or done. Follow up with jira_context (readiness, blockers, dependencies, priority) or jira_full (agreement, contract, approval, closure).
+
+Repository and external sources are not evaluated.
+
+scope="preview" (default) returns the first page for interactive exploration. scope="complete" walks every page - use it whenever the answer depends on the total count or on seeing every match. Check meta.complete before treating the list as exhaustive.`;
+export function registerJiraSearch(server, deps) {
+    server.registerTool("jira_search", {
+        title: "Search Jira issues (lightweight list)",
+        description: DESCRIPTION,
+        inputSchema: {
+            jql: z
+                .string()
+                .min(1)
+                .describe('JQL query, e.g. \'project = PROJECT AND statusCategory != Done ORDER BY updated DESC\'.'),
+            scope: z
+                .enum(["preview", "complete"])
+                .optional()
+                .describe('"preview" (default) = first page only. "complete" = every page, for exhaustive enumeration or counting.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (args) => runTool("jira_search", deps.telemetry, () => searchIssues(deps, { jql: args.jql, ...(args.scope ? { scope: args.scope } : {}) })));
+}

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

@@ -0,0 +1,19 @@
+import type { ContextLevel } from "../domain/completeness.js";
+import type { ProjectConfig } from "../config/schema.js";
+/**
+ * Which tool a given kind of judgement requires. There is no AI intent
+ * classifier in this release - the rule is enforced through tool descriptions
+ * and project instructions, and this table is the single place it is written down.
+ */
+export declare const DEFAULT_CONTEXT_DECISIONS: readonly ["readiness", "dependency", "blocker", "priority"];
+export declare const DEFAULT_FULL_DECISIONS: readonly ["agreement", "contract", "approval", "closure"];
+export declare function minimumLevelFor(decision: string, config: ProjectConfig): ContextLevel;
+/**
+ * Human-readable guidance embedded in each tool's description so the model
+ * picks the right level without a router.
+ */
+export declare const LEVEL_GUIDANCE: {
+    readonly search: "Listing and discovery only. Results are NOT complete issue context: never conclude agreement, approval, or done-ness from them.";
+    readonly context: "Readiness, blockers, dependencies and priority. Includes parent/subtasks/links but not the comment thread.";
+    readonly full: "Agreement, contract, approval and closure. Includes description and the full comment thread.";
+};

package/dist/policy/completeness-policy.js

@@ -0,0 +1,34 @@
+/**
+ * Which tool a given kind of judgement requires. There is no AI intent
+ * classifier in this release - the rule is enforced through tool descriptions
+ * and project instructions, and this table is the single place it is written down.
+ */
+export const DEFAULT_CONTEXT_DECISIONS = [
+    "readiness",
+    "dependency",
+    "blocker",
+    "priority",
+];
+export const DEFAULT_FULL_DECISIONS = [
+    "agreement",
+    "contract",
+    "approval",
+    "closure",
+];
+export function minimumLevelFor(decision, config) {
+    const d = decision.trim().toLowerCase();
+    if (config.policy.fullRequiredFor.some((x) => x.toLowerCase() === d))
+        return "full";
+    if (config.policy.contextRequiredFor.some((x) => x.toLowerCase() === d))
+        return "context";
+    return "search";
+}
+/**
+ * Human-readable guidance embedded in each tool's description so the model
+ * picks the right level without a router.
+ */
+export const LEVEL_GUIDANCE = {
+    search: "Listing and discovery only. Results are NOT complete issue context: never conclude agreement, approval, or done-ness from them.",
+    context: "Readiness, blockers, dependencies and priority. Includes parent/subtasks/links but not the comment thread.",
+    full: "Agreement, contract, approval and closure. Includes description and the full comment thread.",
+};

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

@@ -0,0 +1,13 @@
+/**
+ * Read-after-write rule.
+ *
+ * JAM is read-only in this release, so nothing enforces this at runtime yet.
+ * The rule is fixed here so the write adapter, when it lands, cannot quietly
+ * confirm a write with a stale JQL search result.
+ *
+ * Normal read      -> Enhanced JQL search (`jira_search`)
+ * Post-write read  -> direct issue GET for the affected key
+ */
+export type ReadMode = "search" | "direct";
+export declare function readModeAfterWrite(): ReadMode;
+export declare function readModeForQuery(): ReadMode;

package/dist/policy/consistency-policy.js

@@ -0,0 +1,6 @@
+export function readModeAfterWrite() {
+    return "direct";
+}
+export function readModeForQuery() {
+    return "search";
+}

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

@@ -0,0 +1,11 @@
+import type { ProjectConfig } from "../config/schema.js";
+import type { ContextLevel } from "../domain/completeness.js";
+/**
+ * The agent never chooses Jira fields. Each context level has a fixed field set
+ * so a discovery call cannot accidentally drag description/comments into the
+ * model's context, and `fields=*` is impossible by construction.
+ */
+/** Never requested at SEARCH level - these are the expensive ones. */
+export declare const HEAVY_FIELDS: readonly ["description", "comment", "attachment", "changelog"];
+export declare function fieldsFor(level: ContextLevel, config: ProjectConfig): string[];
+export declare function isHeavy(field: string): boolean;

package/dist/policy/field-policy.js

@@ -0,0 +1,26 @@
+/**
+ * The agent never chooses Jira fields. Each context level has a fixed field set
+ * so a discovery call cannot accidentally drag description/comments into the
+ * model's context, and `fields=*` is impossible by construction.
+ */
+/** Never requested at SEARCH level - these are the expensive ones. */
+export const HEAVY_FIELDS = ["description", "comment", "attachment", "changelog"];
+export function fieldsFor(level, config) {
+    const lite = dedupe(config.fields.lite.filter((f) => !isHeavy(f)));
+    if (level === "search")
+        return lite;
+    const contextFields = dedupe([
+        ...lite,
+        ...config.fields.context.filter((f) => !isHeavy(f)),
+        ...config.customFields.map((cf) => cf.id),
+    ]);
+    if (level === "context")
+        return contextFields;
+    return dedupe([...contextFields, "description", "comment"]);
+}
+export function isHeavy(field) {
+    return HEAVY_FIELDS.includes(field);
+}
+function dedupe(fields) {
+    return [...new Set(fields.map((f) => f.trim()).filter(Boolean))];
+}

package/dist/policy/output-budget-policy.d.ts

@@ -0,0 +1,23 @@
+import type { FullIssueContext } from "../domain/context.js";
+/**
+ * Output budget enforcement.
+ *
+ * The rule that matters is not "stay small" but "never lie about being small".
+ * Anything dropped here is reported through `overflow` so the caller can put it
+ * in completeness metadata; silent truncation is a release blocker.
+ *
+ * Drop order is the inverse of the design's keep-priority:
+ *   core metadata > description > links/dependencies > comments > changelog
+ */
+/** Rough proxy for tokens. Cheap, dependency-free, tuned against real payloads later. */
+export declare function estimateTokens(value: unknown): number;
+export type BudgetOutcome = {
+    issues: FullIssueContext[];
+    /** Which parts were dropped, e.g. ["comments", "description"]. */
+    overflow: string[];
+    complete: boolean;
+    commentsComplete: boolean;
+    linksComplete: boolean;
+    droppedComments: number;
+};
+export declare function applyOutputBudget(input: FullIssueContext[], budgetTokens: number): BudgetOutcome;

package/dist/policy/output-budget-policy.js

@@ -0,0 +1,96 @@
+/**
+ * Output budget enforcement.
+ *
+ * The rule that matters is not "stay small" but "never lie about being small".
+ * Anything dropped here is reported through `overflow` so the caller can put it
+ * in completeness metadata; silent truncation is a release blocker.
+ *
+ * Drop order is the inverse of the design's keep-priority:
+ *   core metadata > description > links/dependencies > comments > changelog
+ */
+/** Rough proxy for tokens. Cheap, dependency-free, tuned against real payloads later. */
+export function estimateTokens(value) {
+    if (value === undefined)
+        return 0;
+    return Math.ceil(JSON.stringify(value).length / 4);
+}
+export function applyOutputBudget(input, budgetTokens) {
+    const overflow = new Set();
+    let droppedComments = 0;
+    // Work on copies so callers keep their originals intact.
+    const issues = input.map((i) => ({ ...i, comments: [...i.comments] }));
+    const stripped = issues.map((i) => bare(i));
+    let total = estimateTokens(stripped);
+    const historyCost = issues.map((i) => estimateTokens(i.history));
+    const descriptionCost = issues.map((i) => estimateTokens(i.description));
+    const linkCost = issues.map((i) => estimateTokens(i.links) + estimateTokens(i.subtasks));
+    total +=
+        sum(historyCost) +
+            sum(descriptionCost) +
+            sum(linkCost) +
+            sum(issues.map((i) => sum(i.comments.map(estimateTokens))));
+    const fits = () => total <= budgetTokens;
+    // 1. changelog
+    if (!fits()) {
+        issues.forEach((issue, idx) => {
+            if (issue.history?.length) {
+                total -= historyCost[idx] ?? 0;
+                delete issue.history;
+                overflow.add("history");
+            }
+        });
+    }
+    // 2. comments - oldest first, so the newest (decision-bearing) ones survive
+    if (!fits()) {
+        for (const issue of issues) {
+            while (issue.comments.length > 0 && !fits()) {
+                const oldest = issue.comments.shift();
+                total -= estimateTokens(oldest);
+                droppedComments++;
+                overflow.add("comments");
+            }
+            if (fits())
+                break;
+        }
+    }
+    // 3. links and subtasks
+    if (!fits()) {
+        issues.forEach((issue, idx) => {
+            if (issue.links.length || issue.subtasks.length) {
+                total -= linkCost[idx] ?? 0;
+                issue.links = [];
+                issue.subtasks = [];
+                overflow.add("links");
+            }
+        });
+    }
+    // 4. description - last thing to go before core metadata
+    if (!fits()) {
+        issues.forEach((issue, idx) => {
+            if (issue.description) {
+                total -= descriptionCost[idx] ?? 0;
+                delete issue.description;
+                overflow.add("description");
+            }
+        });
+    }
+    // Core metadata is never dropped. If it alone exceeds the budget we still
+    // return it and report the result as incomplete rather than truncating rows.
+    if (!fits())
+        overflow.add("output_budget_exceeded");
+    return {
+        issues,
+        overflow: [...overflow],
+        complete: overflow.size === 0,
+        commentsComplete: !overflow.has("comments"),
+        linksComplete: !overflow.has("links"),
+        droppedComments,
+    };
+}
+function bare(issue) {
+    const { description: _d, comments: _c, history: _h, links: _l, subtasks: _s, ...rest } = issue;
+    return rest;
+}
+function sum(values) {
+    return values.reduce((a, b) => a + b, 0);
+}

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

@@ -0,0 +1,15 @@
+import type { ProjectConfig } from "../config/schema.js";
+export type SearchScope = "preview" | "complete";
+export type PaginationPlan = {
+    pageSize: number;
+    /** Hard stop. Reaching it is reported via completeness metadata, never silently. */
+    maxPages: number;
+};
+/**
+ * Pagination is JAM's responsibility, not the agent's.
+ *
+ * `preview` returns the first page for interactive exploration.
+ * `complete` follows nextPageToken to the end, so a page-sized result is never
+ * mistaken for the full result set.
+ */
+export declare function paginationFor(scope: SearchScope, config: ProjectConfig): PaginationPlan;

package/dist/policy/pagination-policy.js

@@ -0,0 +1,13 @@
+/**
+ * Pagination is JAM's responsibility, not the agent's.
+ *
+ * `preview` returns the first page for interactive exploration.
+ * `complete` follows nextPageToken to the end, so a page-sized result is never
+ * mistaken for the full result set.
+ */
+export function paginationFor(scope, config) {
+    return {
+        pageSize: config.search.pageSize,
+        maxPages: scope === "preview" ? 1 : config.search.maxPages,
+    };
+}

package/dist/ports/cache.port.d.ts

@@ -0,0 +1,5 @@
+export interface CachePort {
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+    invalidate(keyPrefix: string): Promise<void>;
+}

package/dist/ports/cache.port.js

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

package/dist/ports/credentials.port.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Credentials never leave this boundary in any log, telemetry line, or tool
+ * result. Only the adapter that builds the HTTP request may read `apiToken`.
+ */
+export type JiraCredentials = {
+    baseUrl: string;
+    email: string;
+    apiToken: string;
+};
+/** Where the resolved credentials came from - "mixed" when fields disagree. */
+export type CredentialSource = "process" | "secret-store" | "user-env" | "mixed" | "none";
+export type CredentialDescription = {
+    baseUrl?: string;
+    email?: string;
+    hasToken: boolean;
+    source: CredentialSource;
+};
+export interface CredentialPort {
+    /**
+     * Resolve and return credentials, or throw CONFIG_INVALID if a field is
+     * missing everywhere it was looked for. Format validation (e.g. the base URL
+     * scheme) is not this method's job - that lives in the boot health gate.
+     */
+    load(): JiraCredentials;
+    /** Presence check for `jam doctor` / `jam serve` - must not return the secret itself. */
+    describe(): CredentialDescription;
+}

package/dist/ports/credentials.port.js

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

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

@@ -0,0 +1,73 @@
+import type { FullIssueContext, NormalizedComment } from "../domain/context.js";
+/**
+ * One page of a JQL search. Pagination itself is NOT the adapter's decision -
+ * the adapter fetches exactly one page and reports the continuation token;
+ * PaginationPolicy in the application layer decides whether to keep going.
+ */
+export type SearchPageRequest = {
+    jql: string;
+    fields: string[];
+    pageSize: number;
+    pageToken?: string;
+};
+export type SearchPageResult = {
+    /** Partially populated: only the requested fields are set. */
+    issues: FullIssueContext[];
+    nextPageToken?: string;
+    responseBytes: number;
+};
+export type GetIssuesRequest = {
+    keys: string[];
+    fields: string[];
+};
+export type GetIssuesResult = {
+    issues: FullIssueContext[];
+    /** Keys that were requested but not returned (missing or not permitted). */
+    missingKeys: string[];
+    /**
+     * Total comment count per issue key as Jira reports it. The embedded comment
+     * field only carries the first page, so FULL uses this to decide whether more
+     * pages must be fetched before the thread can be called complete.
+     */
+    commentTotals: Record<string, number>;
+    responseBytes: number;
+};
+export type GetCommentsRequest = {
+    key: string;
+    startAt: number;
+    maxResults: number;
+};
+export type GetCommentsResult = {
+    comments: NormalizedComment[];
+    startAt: number;
+    total: number;
+    responseBytes: number;
+};
+export type CurrentUser = {
+    accountId: string;
+    displayName?: string;
+    emailAddress?: string;
+};
+export type ProjectRef = {
+    key: string;
+    name: string;
+};
+export type ListProjectsResult = {
+    projects: ProjectRef[];
+    /** True when more projects exist than were returned - advisory only, not paginated. */
+    truncated: boolean;
+};
+export interface JiraReadPort {
+    searchPage(req: SearchPageRequest): Promise<SearchPageResult>;
+    getIssues(req: GetIssuesRequest): Promise<GetIssuesResult>;
+    getComments(req: GetCommentsRequest): Promise<GetCommentsResult>;
+    /** Used by `jam doctor` to prove authentication works. */
+    getCurrentUser(): Promise<CurrentUser>;
+    /**
+     * Advisory only - used by `jam setup` to show the operator their options
+     * when no project key could be decided safely. Not part of the MCP tool
+     * contract and not held to the completeness/pagination guarantees that
+     * govern tool results.
+     */
+    listProjects(): Promise<ListProjectsResult>;
+}

package/dist/ports/jira-read.port.js

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

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

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+export interface JiraWritePort {
+    updateIssue(key: string, fields: Record<string, unknown>): Promise<void>;
+    addComment(key: string, body: string): Promise<{
+        id: string;
+    }>;
+}

package/dist/ports/jira-write.port.js

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

package/dist/ports/telemetry.port.d.ts

@@ -0,0 +1,13 @@
+export type ToolMetrics = {
+    tool: string;
+    durationMs: number;
+    jiraRequests: number;
+    issues: number;
+    responseBytes: number;
+    pages?: number;
+    complete?: boolean;
+    errorCode?: string;
+};
+export interface TelemetryPort {
+    recordTool(metrics: ToolMetrics): void;
+}

package/dist/ports/telemetry.port.js

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

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@jam-mcp/server",
+  "version": "1.0.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": "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.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/"
+  }
+}