bluntjira 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danil Shagimardanov
+
+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,3 +1,99 @@
-# Temporary Holding Version
+<h1 align="center">bluntjira</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <strong>Jira Server и Data Center в твоём AI-клиенте.</strong><br>
+  Ищи задачи, добавляй комментарии и меняй статусы прямо в чате.
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="Лицензия MIT"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-24%2B-339933?style=for-the-badge&amp;logo=node.js&amp;logoColor=white" alt="Node.js 24 или новее"></a>
+</p>
+
+bluntjira подключает Jira к AI-приложению через MCP. После подключения можно просить помощника найти задачу, прочитать обсуждение, создать новую задачу или перевести её в другой статус. Доступ к проектам и задачам остаётся таким же, как у твоей учётной записи Jira.
+
+## Подключение
+
+Понадобятся [Node.js 24 или новее](https://nodejs.org/) с npm и AI-приложение, которое поддерживает локальные MCP-серверы (stdio).
+
+Поддерживаются Jira Server и Data Center с входом по логину и паролю. Jira Cloud и вход через браузерный SSO не поддерживаются. Если Jira доступна только в корпоративной сети, сначала подключись к ней или включи VPN.
+
+### 1. Войди в Jira
+
+Открой терминал и выполни:
+
+```bash
+npx -y bluntjira@0.2.0 login
+```
+
+Введи адрес Jira, логин и пароль. Используй полный HTTPS-адрес, например `https://jira.example.com` или `https://jira.example.com/jira`. При вводе пароля символы не отображаются.
+
+Логин и пароль сохраняются на компьютере в открытом виде, сервер входит в Jira автоматически и сам обновляет сессию, когда она истекает.
+
+### 2. Добавь сервер в AI-приложение
+
+Открой настройки MCP в своём приложении и добавь:
+
+```json
+{
+  "mcpServers": {
+    "bluntjira": {
+      "command": "npx",
+      "args": ["-y", "bluntjira@0.2.0"]
+    }
+  }
+}
+```
+
+Расположение настроек зависит от приложения. Если оно предлагает отдельные поля вместо JSON, укажи `npx` в поле команды, а `-y` и `bluntjira@0.2.0` в аргументах.
+
+Перезапусти приложение или переподключи сервер в настройках MCP.
+
+### 3. Попробуй в чате
+
+- «Покажи доступные проекты Jira».
+- «Найди мои незакрытые задачи».
+- «Покажи описание и комментарии к PROJ-123».
+- «Создай задачу в проекте PROJ: исправить ошибку входа».
+- «Добавь к PROJ-123 комментарий: исправление готово к проверке».
+- «Какие статусы доступны для PROJ-123?»
+
+Замени `PROJ` и `PROJ-123` на свой проект и задачу. Для создания задачи помощник может запросить её тип и другие обязательные поля.
+
+## Что важно знать
+
+Помощник может изменять реальные задачи от твоего имени. Включи подтверждение действий в настройках AI-приложения, если оно это поддерживает. Если создание задачи или отправка комментария завершились ошибкой, проверь Jira перед повтором: действие могло успеть выполниться.
+
+Логин и пароль хранятся в `~/.bluntjira/settings.json` (права 600) открытым текстом и дают доступ к Jira. Не передавай этот файл другим и не добавляй его в Git.
+
+## Если не работает
+
+| Проблема | Что сделать |
+|---|---|
+| Команда `npx` не найдена | Установи Node.js 24+ с npm и перезапусти терминал и AI-приложение |
+| Не удаётся войти | Проверь адрес, логин, пароль и подключение к корпоративной сети. При CAPTCHA сначала войди в Jira через браузер. Вход только через SSO не поддерживается |
+| Ошибка входа (401) | Пароль изменился: снова выполни `npx -y bluntjira@0.2.0 login`, затем переподключи сервер в AI-приложении |
+| Нет доступа к проекту или задаче | Проверь, доступны ли они твоей учётной записи в самой Jira |
+| После ошибки доступа запросы приостановлены | Проверь вход, права и CAPTCHA. Пауза длится пять минут |
+
+Если проблема остаётся, создай [issue](https://github.com/danillittle/bluntjira/issues). Укажи версию Node.js, AI-приложение и текст ошибки. Не прикладывай пароль или содержимое settings.json.
+
+## Для разработчиков
+
+### Установка из Git
+
+```bash
+git clone https://github.com/danillittle/bluntjira.git
+cd bluntjira
+npm ci
+npm run build
+node dist/index.js login
+```
+
+Для подключения локальной сборки используй команду `node` с аргументом `/absolute/path/to/bluntjira/dist/index.js`, указав свой абсолютный путь.
+
+[Разработка и проверки](https://github.com/danillittle/bluntjira/blob/master/docs/development.md) · [Подготовка релиза](https://github.com/danillittle/bluntjira/blob/master/docs/releasing.md) · [История изменений](https://github.com/danillittle/bluntjira/blob/master/CHANGELOG.md)
+
+## Лицензия
+
+[MIT](LICENSE) © 2026 Danil Shagimardanov.

package/dist/cookie.js

@@ -0,0 +1,6 @@
+import { z } from "zod";
+// The login response and server configuration must accept the same cookie format.
+export const sessionCookieSchema = z.object({
+    name: z.string().regex(/^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/),
+    value: z.string().min(1).refine((value) => [...value].every((char) => char.charCodeAt(0) > 32 && char.charCodeAt(0) < 127 && char !== ";")),
+});

package/dist/index.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { JiraClient, loadJiraCredentials } from "./jira-client.js";
+import { registerTools } from "./tools.js";
+import { authenticateSession, LoginError, runLogin } from "./login.js";
+import { readSettings, SettingsError } from "./settings.js";
+// Source: https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x/docs/server.md#stdio
+async function main() {
+    const settings = await readSettings();
+    const credentials = loadJiraCredentials(settings);
+    const authenticate = () => authenticateSession(credentials.url, credentials.username, credentials.password);
+    const server = new McpServer({ name: "bluntjira", version: "0.2.0" });
+    const jira = new JiraClient({ url: credentials.url }, { reauth: authenticate });
+    registerTools(server, jira);
+    let stopping = false;
+    async function shutdown() {
+        if (stopping)
+            return;
+        stopping = true;
+        process.off("SIGINT", stop);
+        process.off("SIGTERM", stop);
+        process.stdin.off("end", stop);
+        process.stdin.off("close", stop);
+        jira.close();
+        await server.close();
+    }
+    function stop() {
+        void shutdown().catch(() => {
+            process.stderr.write("Unable to close bluntjira cleanly\n");
+            process.exitCode = 1;
+        });
+    }
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    // SDK stdio handles data/errors, but EOF needs an explicit shutdown hook.
+    process.stdin.once("end", stop);
+    process.stdin.once("close", stop);
+    server.server.onclose = stop;
+    try {
+        await server.connect(new StdioServerTransport());
+    }
+    catch (error) {
+        await shutdown();
+        throw error;
+    }
+}
+if (process.argv[2] === "login") {
+    runLogin().catch((error) => {
+        const message = error instanceof LoginError ? error.message : "Unable to complete Jira login";
+        process.stderr.write(`${message}\n`);
+        process.exitCode = 1;
+    });
+}
+else {
+    main().catch((error) => {
+        const message = error instanceof SettingsError || error instanceof LoginError || (error instanceof Error && error.message.startsWith("Invalid Jira settings:"))
+            ? error.message
+            : "Unable to start bluntjira";
+        process.stderr.write(`${message}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/jira-client.js

@@ -0,0 +1,290 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+import { LoginError } from "./login.js";
+const nonEmptyString = z.string().refine((value) => value.trim().length > 0);
+// URL parsing normalizes the path; keep Jira's context path when appending REST paths.
+// Source: https://zod.dev/api#refine
+const jiraUrl = nonEmptyString.refine((value) => {
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:"
+            && url.username === ""
+            && url.password === ""
+            && !value.includes("?")
+            && !value.includes("#");
+    }
+    catch {
+        return false;
+    }
+}).transform((value) => new URL(value).href.replace(/\/+$/, ""));
+const settingsSchema = z.object({
+    JIRA_URL: jiraUrl,
+    JIRA_USERNAME: nonEmptyString,
+    JIRA_PASSWORD: z.string().min(1),
+});
+const retryableStatuses = new Set([429, 502, 503, 504]);
+const authCooldownMs = 5 * 60_000;
+export class JiraRequestError extends Error {
+    kind;
+    status;
+    constructor(message, kind, status) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+        this.name = "JiraRequestError";
+    }
+}
+const jiraErrorSchema = z.object({
+    errorMessages: z.array(z.string()).optional(),
+    errors: z.record(z.string(), z.string()).optional(),
+});
+export class JiraClient {
+    #config;
+    #fetch;
+    #timeoutMs;
+    #cookie = "";
+    #cookieValue = "";
+    // Shared so concurrent expired requests trigger a single login.
+    #loginInFlight;
+    // Jira refused the credentials: stop retrying until restart to avoid CAPTCHA lockouts.
+    #loginRejected = false;
+    #reauth;
+    #activeRequests = new Set();
+    #closed = false;
+    #now;
+    #wait;
+    #authBlockedUntil = 0;
+    #authStatus;
+    constructor(config, options = {}) {
+        this.#config = config;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#timeoutMs = options.timeoutMs ?? 30_000;
+        this.#now = options.now ?? Date.now;
+        this.#wait = options.wait ?? ((ms, signal) => delay(ms, undefined, { signal }));
+        if (config.cookieName && config.cookieValue) {
+            this.#cookie = `${config.cookieName}=${config.cookieValue}`;
+            this.#cookieValue = config.cookieValue;
+        }
+        this.#reauth = options.reauth;
+    }
+    close() {
+        this.#closed = true;
+        for (const controller of this.#activeRequests)
+            controller.abort();
+    }
+    getProjects() {
+        return this.#request("/project");
+    }
+    getIssue(issueKey, fields) {
+        const query = fields === undefined ? "" : `?${new URLSearchParams({ fields: fields.join(",") })}`;
+        return this.#request(`/issue/${encodeURIComponent(issueKey)}${query}`);
+    }
+    searchIssues(input) {
+        return this.#request("/search", { method: "POST", body: input });
+    }
+    createIssue(fields) {
+        return this.#request("/issue", { method: "POST", body: { fields }, write: true });
+    }
+    updateIssue(issueKey, fields) {
+        return this.#request(`/issue/${encodeURIComponent(issueKey)}`, {
+            method: "PUT", body: { fields }, write: true,
+        });
+    }
+    getComments(issueKey, startAt, maxResults) {
+        const query = new URLSearchParams({ startAt: String(startAt), maxResults: String(maxResults) });
+        return this.#request(`/issue/${encodeURIComponent(issueKey)}/comment?${query}`);
+    }
+    addComment(issueKey, body) {
+        return this.#request(`/issue/${encodeURIComponent(issueKey)}/comment`, {
+            method: "POST", body: { body }, write: true,
+        });
+    }
+    getTransitions(issueKey) {
+        return this.#request(`/issue/${encodeURIComponent(issueKey)}/transitions?expand=transitions.fields`);
+    }
+    transitionIssue(issueKey, transitionId, fields) {
+        return this.#request(`/issue/${encodeURIComponent(issueKey)}/transitions`, {
+            method: "POST",
+            body: { transition: { id: transitionId }, ...(fields === undefined ? {} : { fields }) },
+            write: true,
+        });
+    }
+    #safeText(value) {
+        // Redact before truncating: a partial credential must not survive the limit.
+        const secrets = [
+            this.#cookie,
+            this.#cookieValue,
+        ].filter(Boolean).sort((a, b) => b.length - a.length);
+        for (const secret of secrets) {
+            value = value.replaceAll(secret, "[REDACTED]");
+        }
+        // Replace ASCII control characters only; preserve non-ASCII error text.
+        return value.replace(/(?=\p{ASCII})\p{Cc}/gu, " ").slice(0, 4096);
+    }
+    #httpError(response, text) {
+        let message = `Jira HTTP ${response.status}`;
+        try {
+            const parsed = jiraErrorSchema.safeParse(JSON.parse(text));
+            if (parsed.success) {
+                const details = [
+                    ...parsed.data.errorMessages ?? [],
+                    ...Object.entries(parsed.data.errors ?? {}).map(([key, value]) => `${key}: ${value}`),
+                ];
+                if (details.length > 0)
+                    message += `: ${details.join("; ")}`;
+            }
+        }
+        catch {
+            // HTML login pages and malformed JSON are never returned to the client.
+        }
+        const retryAfter = response.headers.get("Retry-After");
+        if (retryableStatuses.has(response.status) && retryAfter)
+            message += `; Retry-After: ${retryAfter}`;
+        if (response.status === 401 || response.status === 403) {
+            message += response.status === 401
+                ? "; Jira session may have expired. Run `bluntjira login` and restart the MCP server."
+                : "; Requests paused for 300 seconds. Check Jira permissions and CAPTCHA.";
+        }
+        return new JiraRequestError(this.#safeText(message), "http", response.status);
+    }
+    #assertAvailable() {
+        if (this.#closed)
+            throw new JiraRequestError("Jira client is closed", "cancelled");
+        const remaining = this.#authBlockedUntil - this.#now();
+        if (remaining > 0) {
+            throw new JiraRequestError(`Jira requests paused for ${Math.ceil(remaining / 1000)} seconds after HTTP ${this.#authStatus}. Check credentials, permissions and CAPTCHA; no HTTP request was sent.`, "cooldown", this.#authStatus);
+        }
+    }
+    async #login(signal) {
+        signal.throwIfAborted();
+        if (this.#loginRejected || !this.#reauth) {
+            throw new JiraRequestError("Jira rejected the stored credentials. Run `bluntjira login` and restart the MCP server.", "http", 401);
+        }
+        const reauth = this.#reauth;
+        this.#loginInFlight ??= reauth().then((session) => {
+            this.#cookie = `${session.cookieName}=${session.cookieValue}`;
+            this.#cookieValue = session.cookieValue;
+        }).catch((error) => {
+            if (error instanceof LoginError && error.rejected)
+                this.#loginRejected = true;
+            throw error;
+        }).finally(() => { this.#loginInFlight = undefined; });
+        // shortcut: an aborted request stops waiting but the shared login runs on (<=30s), upgrade if that matters.
+        const aborted = new Promise((_resolve, reject) => {
+            signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+        });
+        try {
+            await Promise.race([this.#loginInFlight, aborted]);
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw error;
+            // "cooldown" kind: the request was never sent, so it must not be reported as an unknown write outcome.
+            throw new JiraRequestError(`Jira login failed: ${error instanceof LoginError ? error.message : "unknown error"}. Run \`bluntjira login\` if the credentials changed.`, "cooldown", error instanceof LoginError && error.rejected ? 401 : undefined);
+        }
+    }
+    #retryDelay(attempt, response) {
+        const backoff = 1000 * 2 ** attempt + Math.floor(Math.random() * 251);
+        const value = response.headers.get("Retry-After");
+        if (value === null)
+            return backoff;
+        const retryAfter = /^\d+$/.test(value) ? Number(value) * 1000 : Date.parse(value) - this.#now();
+        return Number.isNaN(retryAfter) ? backoff : Math.max(backoff, retryAfter);
+    }
+    async #request(path, options = {}) {
+        this.#assertAvailable();
+        const controller = new AbortController();
+        this.#activeRequests.add(controller);
+        const deadline = this.#now() + this.#timeoutMs;
+        const timeout = setTimeout(() => controller.abort(), this.#timeoutMs);
+        let reauthenticated = false;
+        try {
+            for (let attempt = 0;;) {
+                this.#assertAvailable();
+                controller.signal.throwIfAborted();
+                if (!this.#cookie && this.#reauth)
+                    await this.#login(controller.signal);
+                const response = await this.#fetch(`${this.#config.url}/rest/api/2${path}`, {
+                    method: options.method ?? "GET",
+                    headers: {
+                        Accept: "application/json",
+                        ...(this.#cookie ? { Cookie: this.#cookie } : {}),
+                        ...(options.body === undefined ? {} : { "Content-Type": "application/json" }),
+                    },
+                    ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+                    redirect: "manual",
+                    signal: controller.signal,
+                });
+                // Renew an expired session once per request; 401 means nothing was executed, so retrying is safe even for writes.
+                if (response.status === 401 && this.#reauth && !reauthenticated && !this.#loginRejected) {
+                    reauthenticated = true;
+                    void response.body?.cancel().catch(() => { });
+                    await this.#login(controller.signal);
+                    continue;
+                }
+                // Pause immediately on headers, even if reading the error body later fails.
+                if (response.status === 401 || response.status === 403) {
+                    this.#authStatus = response.status;
+                    this.#authBlockedUntil = this.#now() + authCooldownMs;
+                }
+                if (response.status >= 300 && response.status < 400) {
+                    await response.body?.cancel();
+                    throw new JiraRequestError("Jira redirect refused; check JIRA_URL", "redirect", response.status);
+                }
+                // One timeout covers all attempts, response bodies and backoff waits.
+                const text = await response.text();
+                if (!response.ok) {
+                    const failure = this.#httpError(response, text);
+                    if (options.write || !retryableStatuses.has(response.status) || attempt >= 2)
+                        throw failure;
+                    const waitMs = this.#retryDelay(attempt, response);
+                    attempt++;
+                    // Never retry earlier than Retry-After to fit our time budget.
+                    if (waitMs >= deadline - this.#now())
+                        throw failure;
+                    await this.#wait(waitMs, controller.signal);
+                    continue;
+                }
+                if (text.trim() === "")
+                    return { success: true };
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    throw new JiraRequestError("Jira returned an invalid JSON response", "format");
+                }
+            }
+        }
+        catch (error) {
+            // Never attach a cause: transport errors may contain URLs or credentials.
+            const failure = error instanceof JiraRequestError ? error
+                : this.#closed ? new JiraRequestError("Jira request cancelled", "cancelled")
+                    : controller.signal.aborted ? new JiraRequestError("Jira request timed out", "timeout")
+                        : new JiraRequestError("Unable to reach Jira", "network");
+            // POST is not sufficient to infer writes: JQL search is a read-only POST.
+            if (options.write && (failure.kind === "network" || failure.kind === "timeout"
+                || failure.kind === "format" || failure.kind === "cancelled" || (failure.status ?? 0) >= 500)) {
+                throw new JiraRequestError(`${failure.message}. Write outcome is unknown; check Jira before retrying.`, failure.kind, failure.status);
+            }
+            throw failure;
+        }
+        finally {
+            this.#activeRequests.delete(controller);
+            clearTimeout(timeout);
+        }
+    }
+}
+/** Validate stored Jira settings; never include their values in errors. */
+export function loadJiraCredentials(settings) {
+    const result = settingsSchema.safeParse(settings);
+    if (!result.success) {
+        // Raw Zod issues can include input values. Expose only known setting names.
+        const names = [...new Set(result.error.issues.map((issue) => String(issue.path[0])))];
+        throw new Error(`Invalid Jira settings: ${names.join(", ")}. Run the login command again.`);
+    }
+    return {
+        url: result.data.JIRA_URL,
+        username: result.data.JIRA_USERNAME,
+        password: result.data.JIRA_PASSWORD,
+    };
+}

package/dist/login.js

@@ -0,0 +1,140 @@
+import { chmod, mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { StringDecoder } from "node:string_decoder";
+import { sessionCookieSchema } from "./cookie.js";
+// Only messages constructed by login itself are safe to print in the CLI.
+export class LoginError extends Error {
+    rejected;
+    // True when Jira refused the credentials themselves (not a network or format problem).
+    constructor(message, rejected = false) {
+        super(message);
+        this.rejected = rejected;
+    }
+}
+export function serializeCredentials(credentials) {
+    return `${JSON.stringify({
+        JIRA_URL: credentials.url,
+        JIRA_USERNAME: credentials.username,
+        JIRA_PASSWORD: credentials.password,
+    }, null, 2)}\n`;
+}
+export async function authenticateSession(url, user, password, fetcher = globalThis.fetch) {
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(url);
+    }
+    catch {
+        throw new LoginError("Jira URL must be a valid HTTPS URL");
+    }
+    if (parsedUrl.protocol !== "https:" || parsedUrl.username || parsedUrl.password || parsedUrl.search || parsedUrl.hash) {
+        throw new LoginError("Jira URL must be HTTPS and must not contain credentials, query, or fragment");
+    }
+    const baseUrl = parsedUrl.href.replace(/\/+$/, "");
+    const controller = new AbortController();
+    // One deadline includes both receiving headers and consuming the response body.
+    const timeout = setTimeout(() => controller.abort(), 30_000);
+    try {
+        const response = await fetcher(`${baseUrl}/rest/auth/1/session`, {
+            method: "POST",
+            headers: { Accept: "application/json", "Content-Type": "application/json" },
+            body: JSON.stringify({ username: user, password }),
+            redirect: "manual",
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            void response.body?.cancel().catch(() => { });
+            throw new LoginError(`Jira login failed (HTTP ${response.status})`, response.status === 401 || response.status === 403);
+        }
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            throw new LoginError("Unable to read a valid Jira login response");
+        }
+        if (!payload || typeof payload !== "object" || !("session" in payload)) {
+            throw new LoginError("Jira login response did not include a session cookie");
+        }
+        const session = sessionCookieSchema.safeParse(payload.session);
+        if (!session.success) {
+            throw new LoginError("Jira login response contained an invalid session cookie");
+        }
+        return { url: baseUrl, cookieName: session.data.name, cookieValue: session.data.value };
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new LoginError("Jira login timed out");
+        if (error instanceof LoginError)
+            throw error;
+        // Original transport/parser exceptions may include credentials or response data.
+        throw new LoginError("Unable to reach Jira for login");
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function saveCredentials(credentials, filePath = path.join(homedir(), ".bluntjira", "settings.json")) {
+    const directory = path.dirname(filePath);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await chmod(directory, 0o700);
+    await writeFile(filePath, serializeCredentials(credentials), { mode: 0o600 });
+    await chmod(filePath, 0o600);
+}
+export async function readHidden(prompt, input = stdin, output = stdout) {
+    if (!input.isTTY || typeof input.setRawMode !== "function")
+        throw new LoginError("Login requires an interactive terminal");
+    input.setRawMode(true);
+    return await new Promise((resolve, reject) => {
+        const characters = [];
+        // A UTF-8 character can span data events; iterate decoded code points, not bytes.
+        const decoder = new StringDecoder("utf8");
+        const onData = (chunk) => {
+            for (const character of decoder.write(chunk)) {
+                if (character === "\u0003") {
+                    cleanup();
+                    output.write("\n");
+                    reject(new LoginError("Login cancelled"));
+                    return;
+                }
+                if (character === "\r" || character === "\n") {
+                    cleanup();
+                    output.write("\n");
+                    resolve(characters.join(""));
+                    return;
+                }
+                if (character === "\u007f" || character === "\b")
+                    characters.pop();
+                else if (character >= " ")
+                    characters.push(character);
+            }
+        };
+        const cleanup = () => { input.off("data", onData); input.setRawMode?.(false); input.pause(); };
+        input.on("data", onData);
+        input.resume();
+        // Display the prompt only after echo is disabled and the input handler is ready.
+        output.write(prompt);
+    });
+}
+export async function runLogin() {
+    if (!stdin.isTTY || !stdout.isTTY)
+        throw new LoginError("Login requires an interactive terminal");
+    const terminal = createInterface({ input: stdin, output: stdout });
+    try {
+        const url = (await terminal.question("Jira URL: ")).trim();
+        const user = (await terminal.question("Jira username: ")).trim();
+        terminal.close();
+        const password = await readHidden("Jira password (input hidden): ");
+        if (!url || !user || !password)
+            throw new LoginError("Jira URL, username, and password are required");
+        const session = await authenticateSession(url, user, password);
+        // Login is verified first so a typo never overwrites working settings.
+        await saveCredentials({ url: session.url, username: user, password });
+        stdout.write(`Jira credentials saved to ${path.join(homedir(), ".bluntjira", "settings.json")} (permissions 600). The server logs in automatically.\n`);
+    }
+    finally {
+        terminal.close();
+    }
+}

package/dist/settings.js

@@ -0,0 +1,37 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+// Only controlled messages from settings loading may be printed by the CLI.
+export class SettingsError extends Error {
+}
+export function settingsPath() {
+    return path.join(homedir(), ".bluntjira", "settings.json");
+}
+export async function readSettings(filePath = settingsPath()) {
+    let contents;
+    try {
+        contents = await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+            throw new SettingsError("Jira settings file not found. Run the login command first.");
+        }
+        throw new SettingsError("Unable to read Jira settings file. Check file access and run the login command again.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        throw new SettingsError("Invalid Jira settings JSON. Run the login command again.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new SettingsError("Invalid Jira settings JSON. Run the login command again.");
+    }
+    const settings = parsed;
+    return {
+        ...(typeof settings.JIRA_URL === "string" ? { JIRA_URL: settings.JIRA_URL } : {}),
+        ...(typeof settings.JIRA_USERNAME === "string" ? { JIRA_USERNAME: settings.JIRA_USERNAME } : {}),
+        ...(typeof settings.JIRA_PASSWORD === "string" ? { JIRA_PASSWORD: settings.JIRA_PASSWORD } : {}),
+    };
+}

package/dist/tools.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { JiraRequestError } from "./jira-client.js";
+const nonEmptyString = z.string().refine((value) => value.trim().length > 0);
+// Dot segments are not Jira identifiers and must not normalize into a different REST path.
+const identifier = nonEmptyString.refine((value) => value !== "." && value !== "..");
+const fieldNames = z.array(nonEmptyString).optional();
+const pagination = {
+    startAt: z.number().int().min(0).default(0),
+    maxResults: z.number().int().min(1).max(100).default(50),
+};
+const readAnnotations = { readOnlyHint: true, destructiveHint: false, openWorldHint: true };
+const writeAnnotations = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
+const jsonFields = z.record(z.string(), z.json());
+const createFields = z.object({
+    project: z.object({ key: identifier.optional(), id: identifier.optional() }).catchall(z.json())
+        .refine((value) => value.key !== undefined || value.id !== undefined, "Project key or id is required"),
+    summary: nonEmptyString,
+    issuetype: z.object({ id: identifier.optional(), name: nonEmptyString.optional() }).catchall(z.json())
+        .refine((value) => value.id !== undefined || value.name !== undefined, "Issue type id or name is required"),
+}).catchall(z.json());
+const updateFields = jsonFields
+    .refine((value) => Object.keys(value).length > 0, "At least one field is required")
+    .refine((value) => !Object.hasOwn(value, "status"), "Use transition_issue to change status");
+async function toolResult(operation) {
+    try {
+        const result = await operation();
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }
+    catch (error) {
+        const message = error instanceof JiraRequestError ? error.message : "Jira request failed";
+        return { isError: true, content: [{ type: "text", text: message }] };
+    }
+}
+// Contracts: https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x/docs/server.md
+// Jira REST v2: https://docs.atlassian.com/software/jira/docs/api/REST/9.12.0/
+export function registerTools(server, jira) {
+    server.registerTool("get_projects", {
+        description: "List Jira projects visible to the configured user.",
+        inputSchema: z.strictObject({}),
+        annotations: readAnnotations,
+    }, () => toolResult(() => jira.getProjects()));
+    server.registerTool("get_issue", {
+        description: "Read a Jira issue by key or numeric ID, optionally selecting fields.",
+        inputSchema: z.strictObject({ issueKey: identifier, fields: fieldNames }),
+        annotations: readAnnotations,
+    }, ({ issueKey, fields }) => toolResult(() => jira.getIssue(issueKey, fields)));
+    server.registerTool("search_issues", {
+        description: "Search Jira with JQL. Returns one page and Jira pagination metadata; no automatic page traversal.",
+        inputSchema: z.strictObject({ jql: nonEmptyString, fields: fieldNames, ...pagination }),
+        annotations: readAnnotations,
+    }, (input) => toolResult(() => jira.searchIssues(input)));
+    server.registerTool("create_issue", {
+        description: "Create a Jira issue using fields: project (key or id), summary, issuetype (id or name), plus custom fields required by the project. Writes to Jira; do not blindly retry an unknown outcome.",
+        inputSchema: z.strictObject({ fields: createFields }),
+        annotations: writeAnnotations,
+    }, ({ fields }) => toolResult(() => jira.createIssue(fields)));
+    server.registerTool("update_issue", {
+        description: "Update issue fields, preserving custom fields and null values. Use transition_issue for status changes. Writes to Jira.",
+        inputSchema: z.strictObject({ issueKey: identifier, fields: updateFields }),
+        annotations: writeAnnotations,
+    }, ({ issueKey, fields }) => toolResult(() => jira.updateIssue(issueKey, fields)));
+    server.registerTool("get_comments", {
+        description: "Read one page of issue comments with Jira pagination metadata. Text is returned unchanged.",
+        inputSchema: z.strictObject({ issueKey: identifier, ...pagination }),
+        annotations: readAnnotations,
+    }, ({ issueKey, startAt, maxResults }) => toolResult(() => jira.getComments(issueKey, startAt, maxResults)));
+    server.registerTool("add_comment", {
+        description: "Add a comment as a REST API v2 text string (Jira wiki markup, not ADF). Writes to Jira.",
+        inputSchema: z.strictObject({ issueKey: identifier, body: nonEmptyString }),
+        annotations: writeAnnotations,
+    }, ({ issueKey, body }) => toolResult(() => jira.addComment(issueKey, body)));
+    server.registerTool("get_transitions", {
+        description: "List transitions available to the current user, including required transition field metadata.",
+        inputSchema: z.strictObject({ issueKey: identifier }),
+        annotations: readAnnotations,
+    }, ({ issueKey }) => toolResult(() => jira.getTransitions(issueKey)));
+    server.registerTool("transition_issue", {
+        description: "Change status using a transitionId from get_transitions. Include fields required by the transition screen. Writes to Jira; never directly updates status.",
+        inputSchema: z.strictObject({ issueKey: identifier, transitionId: identifier, fields: jsonFields.optional() }),
+        annotations: writeAnnotations,
+    }, ({ issueKey, transitionId, fields }) => toolResult(() => jira.transitionIssue(issueKey, transitionId, fields)));
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "bluntjira",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Jira REST API v2 MCP server over stdio",
+  "type": "module",
+  "license": "MIT",
+  "author": "Danil Shagimardanov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danillittle/bluntjira.git"
+  },
+  "homepage": "https://github.com/danillittle/bluntjira#readme",
+  "bugs": {
+    "url": "https://github.com/danillittle/bluntjira/issues"
+  },
+  "keywords": ["jira", "mcp", "model-context-protocol", "stdio"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "bluntjira": "dist/index.js"
+  },
+  "files": [
+    "dist/cookie.js",
+    "dist/index.js",
+    "dist/jira-client.js",
+    "dist/login.js",
+    "dist/settings.js",
+    "dist/tools.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "oxlint --max-warnings=0 src tests",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "tsc -p tsconfig.test.json && node --test .test-dist/tests/*.test.js",
+    "start": "node dist/index.js",
+    "dev": "npm run build && node dist/index.js",
+    "check": "npm run lint && npm run typecheck && npm test && npm run build",
+    "prepublishOnly": "npm run check",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "oxlint": "1.88.0",
+    "typescript": "7.0.2"
+  }
+}