@jam-mcp/server 1.0.0

package/dist/adapters/jira-cloud/adf-to-text.js

@@ -0,0 +1,151 @@
+/**
+ * Atlassian Document Format -> plain text.
+ *
+ * ADF raw JSON is mostly structural tokens the agent has to pay for and then
+ * ignore. Normalizing to text is the single biggest payload win in JAM, so
+ * nothing downstream of the adapter ever sees an ADF node.
+ *
+ * Unknown node types are surfaced as `[unsupported: <type>]` rather than
+ * dropped - a silently missing paragraph is exactly the failure mode the
+ * completeness rules exist to prevent.
+ */
+const KNOWN_LEAF = new Set(["hardBreak", "rule", "emoji", "date", "status", "inlineCard", "mention", "text"]);
+export function adfToText(doc) {
+    if (doc == null)
+        return "";
+    if (typeof doc === "string")
+        return doc.trim();
+    if (typeof doc !== "object")
+        return String(doc);
+    const node = doc;
+    const out = renderNode(node, 0).replace(/\n{3,}/g, "\n\n").trim();
+    return out;
+}
+function renderChildren(node, depth, sep = "") {
+    if (!node.content?.length)
+        return "";
+    return node.content.map((c) => renderNode(c, depth)).join(sep);
+}
+function renderNode(node, depth) {
+    switch (node.type) {
+        case undefined:
+        case "doc":
+            return renderChildren(node, depth, "\n\n");
+        case "text":
+            return applyMarks(node.text ?? "", node.marks);
+        case "paragraph":
+            return renderChildren(node, depth);
+        case "heading": {
+            const level = Number(node.attrs?.["level"] ?? 1);
+            return `${"#".repeat(Math.min(6, Math.max(1, level)))} ${renderChildren(node, depth)}`;
+        }
+        case "bulletList":
+        case "orderedList": {
+            const ordered = node.type === "orderedList";
+            const items = node.content ?? [];
+            return items
+                .map((item, i) => {
+                const marker = ordered ? `${i + 1}.` : "-";
+                const body = renderNode(item, depth + 1).trim();
+                const indent = "  ".repeat(depth);
+                // keep nested lines aligned under their marker
+                return `${indent}${marker} ${body.split("\n").join(`\n${indent}  `)}`;
+            })
+                .join("\n");
+        }
+        case "listItem":
+            return renderChildren(node, depth, "\n");
+        case "taskList":
+            return renderChildren(node, depth, "\n");
+        case "taskItem": {
+            const done = node.attrs?.["state"] === "DONE";
+            return `- [${done ? "x" : " "}] ${renderChildren(node, depth)}`;
+        }
+        case "codeBlock": {
+            const lang = typeof node.attrs?.["language"] === "string" ? node.attrs["language"] : "";
+            return `\`\`\`${lang}\n${renderChildren(node, depth, "")}\n\`\`\``;
+        }
+        case "blockquote":
+            return renderChildren(node, depth, "\n")
+                .split("\n")
+                .map((l) => `> ${l}`)
+                .join("\n");
+        case "panel":
+            return renderChildren(node, depth, "\n\n");
+        case "rule":
+            return "---";
+        case "hardBreak":
+            return "\n";
+        case "mention": {
+            // Jira usually stores the "@" in attrs.text already - do not double it.
+            const raw = String(node.attrs?.["text"] ?? node.attrs?.["displayName"] ?? "unknown");
+            return raw.startsWith("@") ? raw : `@${raw}`;
+        }
+        case "emoji":
+            return String(node.attrs?.["text"] ?? node.attrs?.["shortName"] ?? "");
+        case "date":
+            return String(node.attrs?.["timestamp"] ?? "");
+        case "status":
+            return `[${node.attrs?.["text"] ?? ""}]`;
+        case "inlineCard":
+        case "blockCard":
+        case "embedCard":
+            return String(node.attrs?.["url"] ?? "[card]");
+        case "mediaSingle":
+        case "mediaGroup":
+        case "media":
+            return "[attachment]";
+        case "table":
+            return (node.content ?? []).map((row) => renderNode(row, depth)).join("\n");
+        case "tableRow":
+            return `| ${(node.content ?? [])
+                .map((cell) => renderNode(cell, depth).replace(/\n+/g, " ").trim())
+                .join(" | ")} |`;
+        case "tableHeader":
+        case "tableCell":
+            return renderChildren(node, depth, " ");
+        case "expand":
+        case "nestedExpand": {
+            const title = node.attrs?.["title"];
+            const body = renderChildren(node, depth, "\n\n");
+            return title ? `${title}\n${body}` : body;
+        }
+        default: {
+            const inner = renderChildren(node, depth, "\n");
+            const label = `[unsupported: ${node.type}]`;
+            if (!inner && !KNOWN_LEAF.has(node.type ?? ""))
+                return label;
+            return inner || label;
+        }
+    }
+}
+function applyMarks(text, marks) {
+    if (!marks?.length)
+        return text;
+    let out = text;
+    for (const mark of marks) {
+        switch (mark.type) {
+            case "code":
+                out = `\`${out}\``;
+                break;
+            case "strong":
+                out = `**${out}**`;
+                break;
+            case "em":
+                out = `*${out}*`;
+                break;
+            case "strike":
+                out = `~~${out}~~`;
+                break;
+            case "link": {
+                const href = mark.attrs?.["href"];
+                if (typeof href === "string" && href && href !== out)
+                    out = `[${out}](${href})`;
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return out;
+}

package/dist/adapters/jira-cloud/jira-client.d.ts

@@ -0,0 +1,32 @@
+import { JamError } from "../../domain/errors.js";
+import type { CredentialPort } from "../../ports/credentials.port.js";
+export type JiraRequest = {
+    path: string;
+    method?: "GET" | "POST";
+    query?: Record<string, string | number | undefined>;
+    body?: unknown;
+};
+export type JiraResponse<T> = {
+    data: T;
+    /** Size of the raw response body, for telemetry and budget accounting. */
+    bytes: number;
+};
+/**
+ * Thin HTTP boundary around Jira Cloud REST v3.
+ *
+ * Two hard rules live here:
+ *  1. The Authorization header is built at request time and never stored,
+ *     logged, or attached to a thrown error.
+ *  2. Every non-2xx response becomes a JamError with a normalized code, so no
+ *     vendor error shape escapes the adapter.
+ */
+export declare class JiraClient {
+    private readonly credentials;
+    private readonly fetchImpl;
+    private cached?;
+    constructor(credentials: CredentialPort, fetchImpl?: typeof fetch);
+    get baseUrl(): string;
+    private creds;
+    request<T>(req: JiraRequest): Promise<JiraResponse<T>>;
+}
+export declare function mapStatus(status: number, body: string, path: string): JamError;

package/dist/adapters/jira-cloud/jira-client.js

@@ -0,0 +1,137 @@
+import { JamError } from "../../domain/errors.js";
+const MAX_RETRIES = 2;
+const MAX_RETRY_DELAY_MS = 5_000;
+/**
+ * Thin HTTP boundary around Jira Cloud REST v3.
+ *
+ * Two hard rules live here:
+ *  1. The Authorization header is built at request time and never stored,
+ *     logged, or attached to a thrown error.
+ *  2. Every non-2xx response becomes a JamError with a normalized code, so no
+ *     vendor error shape escapes the adapter.
+ */
+export class JiraClient {
+    credentials;
+    fetchImpl;
+    cached;
+    constructor(credentials, fetchImpl = fetch) {
+        this.credentials = credentials;
+        this.fetchImpl = fetchImpl;
+    }
+    get baseUrl() {
+        return this.creds().baseUrl;
+    }
+    creds() {
+        this.cached ??= this.credentials.load();
+        return this.cached;
+    }
+    async request(req) {
+        const creds = this.creds();
+        const url = new URL(req.path, `${creds.baseUrl}/`);
+        for (const [k, v] of Object.entries(req.query ?? {})) {
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        }
+        const auth = Buffer.from(`${creds.email}:${creds.apiToken}`).toString("base64");
+        let lastError;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            let res;
+            try {
+                res = await this.fetchImpl(url, {
+                    method: req.method ?? "GET",
+                    headers: {
+                        Authorization: `Basic ${auth}`,
+                        Accept: "application/json",
+                        ...(req.body ? { "Content-Type": "application/json" } : {}),
+                    },
+                    ...(req.body ? { body: JSON.stringify(req.body) } : {}),
+                });
+            }
+            catch (err) {
+                // Network-level failure: the message may contain the host but never the token.
+                throw new JamError("JIRA_UNAVAILABLE", `Could not reach Jira at ${creds.baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            const text = await res.text();
+            const bytes = Buffer.byteLength(text, "utf8");
+            if (res.ok) {
+                if (!text)
+                    return { data: undefined, bytes };
+                try {
+                    return { data: JSON.parse(text), bytes };
+                }
+                catch {
+                    throw new JamError("JIRA_UNAVAILABLE", "Jira returned a non-JSON response.");
+                }
+            }
+            const error = mapStatus(res.status, text, url.pathname);
+            // ponytail: fixed 2 retries on transient statuses; add backoff tuning if
+            // `complete` searches start tripping Jira's rate limiter in practice.
+            const transient = res.status === 429 || res.status >= 500;
+            if (transient && attempt < MAX_RETRIES) {
+                lastError = error;
+                await sleep(retryDelayMs(res.headers.get("retry-after"), attempt));
+                continue;
+            }
+            throw error;
+        }
+        throw lastError ?? new JamError("JIRA_UNAVAILABLE", "Jira request failed.");
+    }
+}
+function retryDelayMs(retryAfter, attempt) {
+    const parsed = retryAfter ? Number(retryAfter) * 1000 : NaN;
+    const fallback = 500 * 2 ** attempt;
+    const delay = Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+    return Math.min(delay, MAX_RETRY_DELAY_MS);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Extract Jira's own message without echoing the whole payload back to the agent.
+ */
+function jiraMessage(body) {
+    try {
+        const parsed = JSON.parse(body);
+        const fromList = parsed.errorMessages?.filter(Boolean).join(" ");
+        if (fromList)
+            return fromList;
+        const fromMap = parsed.errors
+            ? Object.entries(parsed.errors)
+                .map(([k, v]) => `${k}: ${v}`)
+                .join(" ")
+            : "";
+        if (fromMap)
+            return fromMap;
+        if (parsed.message)
+            return parsed.message;
+    }
+    catch {
+        // fall through - a non-JSON error body is not worth forwarding verbatim
+    }
+    return undefined;
+}
+export function mapStatus(status, body, path) {
+    const detail = jiraMessage(body);
+    const suffix = detail ? ` ${detail}` : "";
+    switch (status) {
+        case 400:
+            return new JamError("JQL_INVALID", `Jira rejected the request as malformed.${suffix}`, { status });
+        case 401:
+            return new JamError("JIRA_AUTH_FAILED", "Jira rejected the credentials. Check JIRA_EMAIL and JIRA_API_TOKEN.", { status });
+        case 403:
+            return new JamError("JIRA_PERMISSION_DENIED", `The current Jira account is not permitted to do this.${suffix}`, { status });
+        case 404:
+            return new JamError("ISSUE_NOT_FOUND", `Jira has no such resource, or it is not visible to this account (${path}).${suffix}`, { status });
+        case 429:
+            return new JamError("RATE_LIMITED", "Jira rate limit reached.", { status });
+        default:
+            if (status >= 500) {
+                return new JamError("JIRA_UNAVAILABLE", `Jira returned ${status}.${suffix}`, {
+                    status,
+                });
+            }
+            return new JamError("JIRA_UNAVAILABLE", `Jira returned ${status}.${suffix}`, {
+                status,
+            });
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { ProjectConfig } from "../../config/schema.js";
+import type { CredentialPort } from "../../ports/credentials.port.js";
+import type { CurrentUser, GetCommentsRequest, GetCommentsResult, GetIssuesRequest, GetIssuesResult, JiraReadPort, ListProjectsResult, SearchPageRequest, SearchPageResult } from "../../ports/jira-read.port.js";
+export declare class JiraCloudReadAdapter implements JiraReadPort {
+    private readonly config;
+    private readonly client;
+    constructor(credentials: CredentialPort, config: ProjectConfig, fetchImpl?: typeof fetch);
+    searchPage(req: SearchPageRequest): Promise<SearchPageResult>;
+    getIssues(req: GetIssuesRequest): Promise<GetIssuesResult>;
+    getComments(req: GetCommentsRequest): Promise<GetCommentsResult>;
+    listProjects(): Promise<ListProjectsResult>;
+    getCurrentUser(): Promise<CurrentUser>;
+}

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

@@ -0,0 +1,97 @@
+import { JiraClient } from "./jira-client.js";
+import { mapComment, mapIssueWithMeta } from "./mapper.js";
+/** Jira Cloud caps a bulkfetch request at 100 keys. */
+const BULK_CHUNK = 100;
+export class JiraCloudReadAdapter {
+    config;
+    client;
+    constructor(credentials, config, fetchImpl) {
+        this.config = config;
+        this.client = new JiraClient(credentials, fetchImpl);
+    }
+    async searchPage(req) {
+        const { data, bytes } = await this.client.request({
+            path: "rest/api/3/search/jql",
+            query: {
+                jql: req.jql,
+                fields: req.fields.join(","),
+                maxResults: req.pageSize,
+                nextPageToken: req.pageToken,
+            },
+        });
+        const result = {
+            issues: (data.issues ?? []).map((raw) => mapIssueWithMeta(raw, this.config).issue),
+            responseBytes: bytes,
+        };
+        if (data.nextPageToken)
+            result.nextPageToken = data.nextPageToken;
+        return result;
+    }
+    async getIssues(req) {
+        const issues = [];
+        const commentTotals = {};
+        let responseBytes = 0;
+        const returned = new Set();
+        for (const chunk of chunks(req.keys, BULK_CHUNK)) {
+            const { data, bytes } = await this.client.request({
+                path: "rest/api/3/issue/bulkfetch",
+                method: "POST",
+                body: {
+                    issueIdsOrKeys: chunk,
+                    fields: req.fields,
+                    fieldsByKeys: true,
+                },
+            });
+            responseBytes += bytes;
+            for (const raw of data.issues ?? []) {
+                const { issue, commentTotal } = mapIssueWithMeta(raw, this.config);
+                issues.push(issue);
+                commentTotals[issue.key] = commentTotal;
+                returned.add(issue.key.toUpperCase());
+            }
+        }
+        // bulkfetch reports unreadable keys in `issueErrors`, but a key can also be
+        // silently absent. Diffing requested against returned catches both.
+        const missingKeys = req.keys.filter((k) => !returned.has(k.toUpperCase()));
+        return { issues, missingKeys, commentTotals, responseBytes };
+    }
+    async getComments(req) {
+        const { data, bytes } = await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(req.key)}/comment`,
+            query: {
+                startAt: req.startAt,
+                maxResults: req.maxResults,
+                orderBy: "created",
+            },
+        });
+        return {
+            comments: (data.comments ?? []).map(mapComment),
+            startAt: data.startAt ?? req.startAt,
+            total: data.total ?? 0,
+            responseBytes: bytes,
+        };
+    }
+    async listProjects() {
+        const { data } = await this.client.request({ path: "rest/api/3/project/search", query: { maxResults: 50 } });
+        return {
+            projects: (data.values ?? [])
+                .filter((p) => Boolean(p.key && p.name))
+                .map((p) => ({ key: p.key, name: p.name })),
+            truncated: data.isLast === false,
+        };
+    }
+    async getCurrentUser() {
+        const { data } = await this.client.request({ path: "rest/api/3/myself" });
+        const user = { accountId: data.accountId ?? "" };
+        if (data.displayName)
+            user.displayName = data.displayName;
+        if (data.emailAddress)
+            user.emailAddress = data.emailAddress;
+        return user;
+    }
+}
+function* chunks(items, size) {
+    for (let i = 0; i < items.length; i += size) {
+        yield items.slice(i, i + size);
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { JiraWritePort } from "../../ports/jira-write.port.js";
+/**
+ * Deliberate stub. The first release is read-only; the existing Atlassian MCP
+ * remains the write path. The port exists so adding writes later is an adapter
+ * swap rather than an application-layer change.
+ */
+export declare class UnsupportedJiraWriteAdapter implements JiraWritePort {
+    updateIssue(): Promise<void>;
+    addComment(): Promise<{
+        id: string;
+    }>;
+}

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

@@ -0,0 +1,17 @@
+import { JamError } from "../../domain/errors.js";
+/**
+ * Deliberate stub. The first release is read-only; the existing Atlassian MCP
+ * remains the write path. The port exists so adding writes later is an adapter
+ * swap rather than an application-layer change.
+ */
+export class UnsupportedJiraWriteAdapter {
+    async updateIssue() {
+        throw notSupported();
+    }
+    async addComment() {
+        throw notSupported();
+    }
+}
+function notSupported() {
+    return new JamError("CONFIG_INVALID", "JAM is read-only in this release. Use the Atlassian MCP for Jira writes.");
+}

package/dist/adapters/jira-cloud/mapper.d.ts

@@ -0,0 +1,34 @@
+import type { FullIssueContext, NormalizedComment } from "../../domain/context.js";
+import type { ProjectConfig } from "../../config/schema.js";
+/**
+ * Raw Jira DTOs stop here. Everything above the adapter sees domain types only,
+ * so swapping REST for Rovo later cannot ripple into the application layer.
+ */
+type RawUser = {
+    displayName?: string;
+    emailAddress?: string;
+    accountId?: string;
+};
+export type RawIssue = {
+    key?: string;
+    id?: string;
+    fields?: Record<string, unknown>;
+};
+export type RawComment = {
+    id?: string;
+    author?: RawUser;
+    created?: string;
+    updated?: string;
+    body?: unknown;
+};
+export type MappedIssue = {
+    issue: FullIssueContext;
+    /** Total comments Jira reports for this issue, not just the embedded page. */
+    commentTotal: number;
+};
+export declare function mapIssue(raw: RawIssue, config: ProjectConfig): FullIssueContext;
+export declare function mapIssueWithMeta(raw: RawIssue, config: ProjectConfig): MappedIssue;
+export declare function mapComment(raw: RawComment): NormalizedComment;
+/** Collapse Jira's option/user/ADF wrappers into something worth a token. */
+export declare function normalizeFieldValue(value: unknown): unknown;
+export {};

package/dist/adapters/jira-cloud/mapper.js

@@ -0,0 +1,143 @@
+import { adfToText } from "./adf-to-text.js";
+export function mapIssue(raw, config) {
+    return mapIssueWithMeta(raw, config).issue;
+}
+export function mapIssueWithMeta(raw, config) {
+    const f = (raw.fields ?? {});
+    const issue = {
+        key: raw.key ?? "",
+        summary: str(f["summary"]) ?? "",
+        status: named(f["status"]) ?? "",
+        updated: str(f["updated"]) ?? "",
+        labels: Array.isArray(f["labels"]) ? f["labels"].map(String) : [],
+        components: Array.isArray(f["components"])
+            ? f["components"].map((c) => c.name ?? "").filter(Boolean)
+            : [],
+        subtasks: Array.isArray(f["subtasks"])
+            ? f["subtasks"].map(issueRef)
+            : [],
+        links: Array.isArray(f["issuelinks"])
+            ? f["issuelinks"].flatMap(mapLink)
+            : [],
+        customFields: mapCustomFields(f, config),
+        comments: [],
+    };
+    const assignee = user(f["assignee"]);
+    if (assignee)
+        issue.assignee = assignee;
+    const priority = named(f["priority"]);
+    if (priority)
+        issue.priority = priority;
+    const issueType = named(f["issuetype"]);
+    if (issueType)
+        issue.issueType = issueType;
+    if (f["parent"])
+        issue.parent = issueRef(f["parent"]);
+    if (f["description"] != null) {
+        const description = adfToText(f["description"]);
+        if (description)
+            issue.description = description;
+    }
+    // Issue GET / bulkfetch embed only the first page of comments; the adapter
+    // pages the rest through the dedicated comment endpoint when FULL is asked for.
+    const embedded = f["comment"];
+    if (embedded?.comments) {
+        issue.comments = embedded.comments.map(mapComment);
+    }
+    const commentTotal = embedded?.total ?? issue.comments.length;
+    return { issue, commentTotal };
+}
+export function mapComment(raw) {
+    const comment = {
+        id: raw.id ?? "",
+        created: raw.created ?? "",
+        body: adfToText(raw.body),
+    };
+    const author = raw.author?.displayName ?? raw.author?.emailAddress;
+    if (author)
+        comment.author = author;
+    if (raw.updated && raw.updated !== raw.created)
+        comment.updated = raw.updated;
+    return comment;
+}
+function mapLink(raw) {
+    const type = raw.type ?? {};
+    const out = [];
+    const add = (direction, target) => {
+        if (!target?.key)
+            return;
+        const label = (direction === "outward" ? type.outward : type.inward) ?? type.name ?? "relates to";
+        out.push({
+            type: label,
+            direction,
+            issue: issueRef(target),
+            blocksThisIssue: isBlocking(label, direction, type.name),
+        });
+    };
+    add("outward", raw.outwardIssue);
+    add("inward", raw.inwardIssue);
+    return out;
+}
+/**
+ * True when the linked issue stands between this issue and being startable.
+ * Jira phrases this from the current issue's side, e.g. "is blocked by".
+ */
+function isBlocking(label, direction, typeName) {
+    if (/blocked by|depends on|is caused by/i.test(label))
+        return true;
+    return direction === "inward" && /^blocks$/i.test(typeName ?? "");
+}
+function mapCustomFields(fields, config) {
+    const out = {};
+    for (const cf of config.customFields) {
+        const value = fields[cf.id];
+        if (value == null)
+            continue;
+        const normalized = normalizeFieldValue(value);
+        if (normalized == null || normalized === "")
+            continue;
+        out[cf.name] = normalized;
+    }
+    return out;
+}
+/** Collapse Jira's option/user/ADF wrappers into something worth a token. */
+export function normalizeFieldValue(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value !== "object")
+        return value;
+    if (Array.isArray(value)) {
+        const items = value.map(normalizeFieldValue).filter((v) => v != null && v !== "");
+        return items.length ? items : undefined;
+    }
+    const obj = value;
+    if (obj["type"] === "doc")
+        return adfToText(obj);
+    if (typeof obj["value"] === "string")
+        return obj["value"];
+    if (typeof obj["displayName"] === "string")
+        return obj["displayName"];
+    if (typeof obj["name"] === "string")
+        return obj["name"];
+    return obj;
+}
+function issueRef(raw) {
+    const ref = { key: raw.key ?? "" };
+    const summary = raw.fields?.summary;
+    if (summary)
+        ref.summary = summary;
+    const status = raw.fields?.status?.name;
+    if (status)
+        ref.status = status;
+    return ref;
+}
+function str(v) {
+    return typeof v === "string" ? v : undefined;
+}
+function named(v) {
+    return v?.name;
+}
+function user(v) {
+    const u = v;
+    return u?.displayName ?? u?.emailAddress ?? undefined;
+}

package/dist/adapters/telemetry/console-telemetry.d.ts

@@ -0,0 +1,13 @@
+import type { TelemetryPort, ToolMetrics } from "../../ports/telemetry.port.js";
+/**
+ * One key=value line per tool call on stderr. stdout is reserved for the MCP
+ * stdio protocol, so nothing here may ever write to stdout.
+ *
+ * Only the fields below are emitted - never credentials, headers, JQL bind
+ * values, or issue content.
+ */
+export declare class ConsoleTelemetry implements TelemetryPort {
+    private readonly enabled;
+    constructor(enabled?: boolean);
+    recordTool(m: ToolMetrics): void;
+}