@bridge_gpt/mcp-server 0.1.0

package/build/index.js

@@ -0,0 +1,1630 @@
+#!/usr/bin/env node
+/**
+ * Bridge API MCP Server
+ *
+ * Exposes Bridge API Jira endpoints as MCP tools for Claude Code agents.
+ * Reads configuration from environment variables:
+ *   BAPI_BASE_URL  - Base URL of the Bridge API (e.g. http://localhost:8000)
+ *   BAPI_REPO_NAME - Default repository name injected into every request
+ *   BAPI_API_KEY   - API key for X-API-Key authentication
+ *   BAPI_DOCS_DIR  - Base directory for local file output (default: docs/tmp)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { writeFile, mkdir, readFile, stat } from "fs/promises";
+import path from "path";
+import { PIPELINES, INSTRUCTIONS } from "./pipelines.generated.js";
+import { resolveRecipe } from "./pipeline-utils.js";
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+const BASE_URL = process.env.BAPI_BASE_URL ?? "http://localhost:8000";
+const REPO_NAME = process.env.BAPI_REPO_NAME ?? "";
+const API_KEY = process.env.BAPI_API_KEY ?? "";
+const BAPI_DOCS_DIR = process.env.BAPI_DOCS_DIR ?? "docs/tmp";
+const GET_HEADERS = { "X-API-Key": API_KEY };
+const POST_HEADERS = {
+    "X-API-Key": API_KEY,
+    "Content-Type": "application/json",
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function buildUrl(path) {
+    return `${BASE_URL.replace(/\/+$/, "")}/jira${path}`;
+}
+function buildGetUrl(path, params) {
+    const url = new URL(buildUrl(path));
+    for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, value);
+    }
+    return url.toString();
+}
+function getDocsPath(subdir) {
+    return path.join(BAPI_DOCS_DIR, subdir);
+}
+function slugify(text, maxLength = 60) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .slice(0, maxLength)
+        .replace(/-$/, "");
+}
+const ERROR_CODES = {
+    400: "BAD_REQUEST",
+    401: "UNAUTHORIZED",
+    403: "FORBIDDEN",
+    404: "NOT_FOUND",
+    409: "CONFLICT",
+    422: "VALIDATION_ERROR",
+    429: "RATE_LIMITED",
+    500: "INTERNAL_ERROR",
+    502: "BAD_GATEWAY",
+    503: "SERVICE_UNAVAILABLE",
+    504: "GATEWAY_TIMEOUT",
+};
+async function handleResponse(resp) {
+    if (resp.ok) {
+        const contentType = resp.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json")) {
+            const body = await resp.json();
+            return JSON.stringify(body, null, 2);
+        }
+        return await resp.text();
+    }
+    const rawText = await resp.text();
+    const errorCode = ERROR_CODES[resp.status] ?? "UNKNOWN_ERROR";
+    let message = rawText;
+    try {
+        const parsed = JSON.parse(rawText);
+        if (parsed.detail) {
+            message = typeof parsed.detail === "string" ? parsed.detail : JSON.stringify(parsed.detail);
+        }
+    }
+    catch {
+        // Response body is not JSON; use raw text as message
+    }
+    return JSON.stringify({ error: errorCode, status: resp.status, message });
+}
+// ---------------------------------------------------------------------------
+// Shared Helpers
+// ---------------------------------------------------------------------------
+async function createTicketRequest(params) {
+    const payload = {
+        repo_name: REPO_NAME,
+        summary: params.summary,
+        description: params.description,
+        issue_type: params.issue_type,
+    };
+    if (params.priority)
+        payload.priority = params.priority;
+    if (params.labels)
+        payload.labels = params.labels;
+    if (params.assignee)
+        payload.assignee = params.assignee;
+    const resp = await fetch(buildUrl("/create-ticket"), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(payload),
+    });
+    return handleResponse(resp);
+}
+async function saveLocally(dir, filename, content) {
+    const filePath = path.join(dir, filename);
+    try {
+        await mkdir(dir, { recursive: true });
+        await writeFile(filePath, content, "utf-8");
+        return `\n\n---\nSaved to ${filePath}`;
+    }
+    catch (writeErr) {
+        return `\n\n---\nNote: Failed to save file to ${filePath}: ${writeErr}`;
+    }
+}
+async function resolveTextOrFile(textValue, filePath, textLabel) {
+    if (!filePath && !textValue) {
+        return {
+            ok: false,
+            errorResponse: {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ error: "BAD_REQUEST", status: 400, message: `Either ${textLabel} or file_path must be provided.` }),
+                    }],
+            },
+        };
+    }
+    let resolvedText = textValue || "";
+    let note = "";
+    if (filePath) {
+        try {
+            const fileStat = await stat(filePath);
+            if (fileStat.size > 1_048_576) {
+                return {
+                    ok: false,
+                    errorResponse: {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({ error: "BAD_REQUEST", status: 400, message: `File at ${filePath} exceeds 1MB size limit. Please provide the ${textLabel} directly or use a smaller file.` }),
+                            }],
+                    },
+                };
+            }
+            resolvedText = await readFile(filePath, "utf-8");
+            if (textValue) {
+                note = `\n\nNote: Both file_path and ${textLabel} were provided. file_path content was used.`;
+            }
+        }
+        catch (err) {
+            return {
+                ok: false,
+                errorResponse: {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ error: "BAD_REQUEST", status: 400, message: `Error reading file at ${filePath}: ${err instanceof Error ? err.message : String(err)}` }),
+                        }],
+                },
+            };
+        }
+    }
+    return { ok: true, text: resolvedText, note };
+}
+async function pollForResult(getUrl, timeoutMs, label) {
+    const startTime = Date.now();
+    let pollIntervalMs = 15_000;
+    while (true) {
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        const elapsed = Math.round((Date.now() - startTime) / 1000);
+        if (Date.now() - startTime >= timeoutMs) {
+            return {
+                ok: false,
+                text: `${label} timed out after ${Math.round(timeoutMs / 1000)} seconds. The task may still be processing on the server.`,
+            };
+        }
+        console.error(`${label} in progress... (elapsed: ${elapsed}s)`);
+        const resp = await fetch(getUrl, { headers: GET_HEADERS });
+        if (resp.status === 404) {
+            await resp.text();
+        }
+        else {
+            const isOk = resp.ok;
+            const text = await handleResponse(resp);
+            return { ok: isOk, text };
+        }
+        if (Date.now() - startTime > 60_000) {
+            pollIntervalMs = 30_000;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: "bridge-api",
+    version: "1.0.0",
+});
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+server.registerTool("ping", {
+    description: "Test connectivity to Bridge API. Validates that the API key is accepted and the configured repository is accessible. " +
+        "Returns JSON with {status: 'ok', repo_name: '<configured repo>'}. " +
+        "Use this as a quick health check before other operations, or to verify your Bridge API configuration is working. " +
+        "A 403 response means the API key is invalid or the repo is not authorized. " +
+        "If the server is unreachable, check that BAPI_BASE_URL points to a running Bridge API instance.",
+    inputSchema: {},
+}, async () => {
+    const url = buildGetUrl("/ping", { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("get_project_standards", {
+    description: "Retrieve project-specific coding standards, architecture guidelines, testing standards, and code review standards for the configured repository. " +
+        "Returns structured markdown with sections for architecture instructions, code review correctness standards, testing stack information, and build analysis. " +
+        "Only sections with configured values are included. Returns 404 if no standards are configured. " +
+        "Consult these standards before writing or reviewing code to ensure compliance with project conventions.",
+    inputSchema: {},
+}, async () => {
+    const url = buildGetUrl("/project-standards", { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("get_tickets", {
+    description: "Search for and list Jira tickets from the configured project. " +
+        "Filters by query text, status name, or date. Returns up to 'limit' tickets ordered by most recently updated. " +
+        "All data is fetched live from Jira. Use get_ticket to retrieve full details for a specific ticket.",
+    inputSchema: {
+        query: z
+            .string()
+            .optional()
+            .describe("Free-text search string. Filters tickets via JQL text ~ '...' " +
+            "(searches summary, description, comments). " +
+            "Examples: \"authentication error\", \"login page crash\", \"payment timeout\""),
+        status: z
+            .string()
+            .optional()
+            .describe("Filter by Jira status name (e.g. 'To Do', 'In Progress', 'Done')"),
+        limit: z
+            .number()
+            .optional()
+            .default(20)
+            .describe("Maximum number of tickets to return (1-100, default 20)"),
+        offset: z
+            .number()
+            .optional()
+            .default(0)
+            .describe("Number of results to skip for pagination (default 0)"),
+        updated_since: z
+            .string()
+            .optional()
+            .describe("ISO date string (YYYY-MM-DD). Only return tickets updated on or after this date"),
+    },
+}, async ({ query, status, limit, offset, updated_since }) => {
+    const params = { repo_name: REPO_NAME };
+    if (query)
+        params.query = query;
+    if (status)
+        params.status = status;
+    if (limit !== undefined)
+        params.limit = String(limit);
+    if (offset !== undefined && offset > 0)
+        params.offset = String(offset);
+    if (updated_since)
+        params.updated_since = updated_since;
+    const url = buildGetUrl("/tickets", params);
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("get_ticket", {
+    description: "Retrieve full details for a single Jira ticket by its key. " +
+        "Returns summary, status, type, assignee, reporter, description, and timestamps. " +
+        "All data is fetched live from Jira. Use get_tickets to search/list multiple tickets.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+    },
+}, async ({ ticket_number }) => {
+    const url = buildGetUrl(`/tickets/${encodeURIComponent(ticket_number)}`, { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("create_ticket", {
+    description: "Create a new Jira ticket in the configured project. Requires either description or file_path (or both — file_path takes precedence). " +
+        "Returns JSON with {ticket_key: 'PROJ-123', url: 'https://...'}. " +
+        "The ticket is created immediately in Jira — confirm details with the user before calling. " +
+        "The description field supports Jira markdown formatting.",
+    inputSchema: {
+        summary: z.string().describe("Ticket title — keep under 100 characters"),
+        description: z
+            .string()
+            .optional()
+            .describe("Required unless file_path is provided. Detailed description in markdown. " +
+            "Recommended structure: Summary (2-4 sentences), Requirements (bullet list with code file references), " +
+            "Acceptance Criteria (testable 'Done when...' statements)"),
+        file_path: z
+            .string()
+            .optional()
+            .describe("Path to a local markdown file whose contents will be used as the ticket description. " +
+            "If both file_path and description are provided, file_path takes precedence. " +
+            "The file must be UTF-8 encoded and under 1MB."),
+        issue_type: z
+            .string()
+            .describe("One of: 'Bug' (defect), 'Story' (user-facing feature), 'Task' (technical/infrastructure work)"),
+        priority: z
+            .string()
+            .optional()
+            .describe("One of: 'Highest', 'High', 'Medium', 'Low', 'Lowest'. Omit to use Jira project default"),
+        labels: z
+            .array(z.string())
+            .optional()
+            .describe("List of Jira labels to apply (e.g. ['frontend', 'tech-debt'])"),
+        assignee: z
+            .string()
+            .optional()
+            .describe("Jira username or account ID of the assignee. Omit to leave unassigned"),
+    },
+}, async ({ summary, description, file_path, issue_type, priority, labels, assignee }) => {
+    const resolved = await resolveTextOrFile(description, file_path, "description");
+    if (!resolved.ok)
+        return resolved.errorResponse;
+    const text = await createTicketRequest({ summary, description: resolved.text, issue_type, priority, labels, assignee });
+    return { content: [{ type: "text", text: text + resolved.note }] };
+});
+server.registerTool("get_plan", {
+    description: "Retrieve the AI-generated implementation plan for a Jira ticket. " +
+        "Returns the full plan as markdown text — present it verbatim without summarizing. " +
+        "The plan includes step-by-step implementation guidance with code file references. " +
+        "Returns 404 if no plan has been generated yet (the ticket may not have been processed by Bridge API). " +
+        "Tip: call get_clarifying_questions for the same ticket to get the full context for implementation.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Whether to save the plan to a local file in the BAPI_DOCS_DIR/plans/ directory. " +
+            "Defaults to true. Set to false to skip saving."),
+    },
+}, async ({ ticket_number, save_locally }) => {
+    const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/plan`, { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const ok = resp.ok;
+    let text = await handleResponse(resp);
+    if (ok && save_locally) {
+        const note = await saveLocally(getDocsPath("plans"), `${ticket_number}-plan.md`, text);
+        text += note;
+    }
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("get_architecture", {
+    description: "Retrieve the AI-generated architecture plan for a Jira ticket. " +
+        "Returns the full architecture plan as markdown text — present it verbatim without summarizing. " +
+        "The plan includes high-level architectural decisions, component design, and integration guidance. " +
+        "Returns 404 if no architecture plan has been generated yet. " +
+        "Tip: use request_architecture to trigger architecture plan generation first.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Whether to save the architecture plan to a local file in the BAPI_DOCS_DIR/architecture/ directory. " +
+            "Defaults to true. Set to false to skip saving."),
+    },
+}, async ({ ticket_number, save_locally }) => {
+    const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/architecture-plan`, { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const ok = resp.ok;
+    let text = await handleResponse(resp);
+    if (ok && save_locally) {
+        const note = await saveLocally(getDocsPath("architecture"), `${ticket_number}-architecture-plan.md`, text);
+        text += note;
+    }
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("get_clarifying_questions", {
+    description: "Retrieve AI-generated clarifying questions (for feature/task tickets) or debugging guidance (for bug tickets) for a Jira ticket. " +
+        "Returns markdown text with questions that should be resolved before implementation begins. " +
+        "Returns 404 if no questions have been generated yet. " +
+        "Tip: call get_plan for the same ticket to get the implementation plan alongside these questions.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Whether to save the clarifying questions to a local file in the BAPI_DOCS_DIR/clarifying-questions/ directory. " +
+            "Defaults to true. Set to false to skip saving."),
+    },
+}, async ({ ticket_number, save_locally }) => {
+    const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/clarifying-questions`, { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const ok = resp.ok;
+    let text = await handleResponse(resp);
+    if (ok && save_locally) {
+        const note = await saveLocally(getDocsPath("clarifying-questions"), `${ticket_number}-clarifying-questions.md`, text);
+        text += note;
+    }
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("parse_repository", {
+    description: "Queue a background job to parse and index the repository for Bridge API's AI agents. " +
+        "This should be run after major codebase changes so that plans and questions reflect the latest code. " +
+        "Returns 202 with {message: 'Repository parsing queued'} on success, " +
+        "or {message: 'Repository parsing already in progress'} if a job is already running. " +
+        "The job runs asynchronously — there is no completion callback. " +
+        "For large repositories this may take several minutes. Confirm with the user before triggering.",
+    inputSchema: {
+        directory_path: z
+            .string()
+            .optional()
+            .describe("Subdirectory to scope the parse to (e.g. 'src/python'). " +
+            "Omit to parse the entire repository"),
+    },
+}, async ({ directory_path }) => {
+    const payload = { repo_name: REPO_NAME };
+    if (directory_path)
+        payload.directory_path = directory_path;
+    const resp = await fetch(buildUrl("/parse-repository"), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(payload),
+    });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("regenerate_directory_map", {
+    description: "Regenerate the repository directory map and return the result. " +
+        "Unlike parse_repository (which is async), this tool is synchronous — it blocks until " +
+        "the directory map is generated and returns the full map text directly. " +
+        "Use this when you need the directory map immediately (e.g. for architecture analysis). " +
+        "May take 30-120 seconds for large repositories.",
+    inputSchema: {},
+}, async () => {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 120_000);
+    try {
+        const resp = await fetch(buildUrl("/regenerate-directory-map"), {
+            method: "POST",
+            headers: POST_HEADERS,
+            body: JSON.stringify({ repo_name: REPO_NAME }),
+            signal: controller.signal,
+        });
+        const text = await handleResponse(resp);
+        return { content: [{ type: "text", text }] };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+});
+server.registerTool("get_parse_status", {
+    description: "Check whether a repository parse job is currently running. " +
+        "Returns {status: 'in_progress', started_at: '<ISO timestamp>'} if a parse is active, " +
+        "or {status: 'idle'} if no parse is running. " +
+        "Use this after calling parse_repository to monitor whether the job has finished. " +
+        "The repo_name is automatically injected from the configured environment.",
+    inputSchema: {},
+}, async () => {
+    const url = buildGetUrl("/parse-status", { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("add_comment", {
+    description: "Post a comment on a Jira ticket. The comment appears immediately in Jira. " +
+        "Supports markdown formatting. " +
+        "For long comments (over ~2000 characters), set attach_as_file to true — " +
+        "this attaches the comment as a .md file instead of posting inline, which avoids Jira's comment length limitations.\n\n" +
+        "Tip: To generate plans, clarifying questions, or ticket critiques, use the dedicated " +
+        "request_plan_generation, request_clarifying_questions, or request_ticket_critique tools.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
+        comment: z
+            .string()
+            .optional()
+            .describe("Comment text in markdown format. Can include code blocks, lists, headings, etc. Optional if file_path is provided."),
+        file_path: z
+            .string()
+            .optional()
+            .describe("Path to a local markdown file whose contents will be used as the comment. " +
+            "If both file_path and comment are provided, file_path takes precedence. " +
+            "The file must be UTF-8 encoded and under 1MB."),
+        attach_as_file: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Set to true to attach the comment as a .md file instead of posting inline. " +
+            "Recommended for comments over 2000 characters"),
+        file_name: z
+            .string()
+            .optional()
+            .describe("Custom filename for the attached .md file (only used when attach_as_file is true). " +
+            "Defaults to {ticket_number}-comment.md if not provided. " +
+            "Example: 'PROJ-123-clarifying-questions.md'"),
+    },
+}, async ({ ticket_number, comment, file_path, attach_as_file, file_name }) => {
+    const resolved = await resolveTextOrFile(comment, file_path, "comment");
+    if (!resolved.ok)
+        return resolved.errorResponse;
+    const payload = {
+        repo_name: REPO_NAME,
+        comment: resolved.text,
+        attach_as_file,
+    };
+    if (file_name) {
+        payload.file_name = file_name;
+    }
+    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/comment`), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(payload),
+    });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text: text + resolved.note }] };
+});
+server.registerTool("update_ticket_description", {
+    description: "Update the description of an existing Jira ticket. This is a direct, synchronous update that overwrites the existing description with the provided text. " +
+        "The description should be in markdown format — it will be automatically converted to Jira wiki markup. " +
+        "This does NOT create a new ticket. Use create_ticket for that. " +
+        "Returns a success message with the ticket number, or an error if the update fails.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        description: z
+            .string()
+            .optional()
+            .describe("New description text in markdown format. Optional if file_path is provided. This will completely replace the existing description."),
+        file_path: z
+            .string()
+            .optional()
+            .describe("Path to a local markdown file whose contents will be used as the new description. " +
+            "If both file_path and description are provided, file_path takes precedence. " +
+            "The file must be UTF-8 encoded and under 1MB."),
+    },
+}, async ({ ticket_number, description, file_path }) => {
+    const resolved = await resolveTextOrFile(description, file_path, "description");
+    if (!resolved.ok)
+        return resolved.errorResponse;
+    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/description`), {
+        method: "PUT",
+        headers: POST_HEADERS,
+        body: JSON.stringify({ repo_name: REPO_NAME, description: resolved.text }),
+    });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text: text + resolved.note }] };
+});
+server.registerTool("upload_attachment", {
+    description: "Upload a local file as an attachment to a Jira ticket. " +
+        "Supports text/UTF-8 files only (markdown, plain text, etc.). " +
+        "Optionally syncs the content to Bridge API's tickets_links table so retrieval endpoints " +
+        "(get_clarifying_questions, get_ticket_critique, get_plan) return the updated content without re-generation. " +
+        "Use link_type to specify which retrieval endpoint should serve this content. " +
+        "Known link_type values: clarifying-questions.md, debugging-guidance.md, ticket-quality-critique.md, architecture-plan.md.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
+        file_path: z
+            .string()
+            .optional()
+            .describe("Path to a local file to upload as an attachment. " +
+            "The file must be UTF-8 encoded and under 1MB. " +
+            "If both file_path and content are provided, file_path takes precedence."),
+        content: z
+            .string()
+            .max(1_048_576)
+            .optional()
+            .describe("Inline text content to upload (max 1MB). Optional if file_path is provided."),
+        file_name: z
+            .string()
+            .optional()
+            .describe("Filename for the attachment in Jira. " +
+            "Defaults to the basename of file_path if provided, or {ticket_number}-attachment.md otherwise."),
+        link_type: z
+            .string()
+            .optional()
+            .describe("When provided, also syncs the content to Bridge API's tickets_links table. " +
+            "Known values: clarifying-questions.md, debugging-guidance.md, ticket-quality-critique.md, architecture-plan.md. " +
+            "Unknown values are accepted with a warning."),
+        replace_existing: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("When true (default), deletes any existing Jira attachment with the same filename before uploading. " +
+            "Set to false to allow duplicate filenames."),
+    },
+}, async ({ ticket_number, file_path, content, file_name, link_type, replace_existing }) => {
+    const resolved = await resolveTextOrFile(content, file_path, "content");
+    if (!resolved.ok)
+        return resolved.errorResponse;
+    const derivedFileName = file_name
+        || (file_path ? path.basename(file_path) : `${ticket_number}-attachment.md`);
+    const payload = {
+        repo_name: REPO_NAME,
+        content: resolved.text,
+        file_name: derivedFileName,
+        replace_existing,
+    };
+    if (link_type) {
+        payload.link_type = link_type;
+    }
+    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/attachment`), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(payload),
+    });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text: text + resolved.note }] };
+});
+server.registerTool("request_plan_generation", {
+    description: "Request AI-generated implementation plan for a Jira ticket. " +
+        "This triggers an asynchronous background job — results are NOT immediate. " +
+        "Processing typically takes 1-5 minutes depending on ticket complexity and number of attachments. " +
+        "After submitting, use get_plan with the same ticket_number to check if results are available. " +
+        "Returns 202 if the request was accepted, 404 if the ticket does not exist in Jira, " +
+        "or 403 if the API key is unauthorized. " +
+        "Set wait_for_result to true to block until the result is ready (typically 1-5 minutes) instead of returning immediately.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate a plan for"),
+        wait_for_result: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When true, the tool blocks and polls until the plan is ready (typically 1-5 minutes), " +
+            "then returns the full plan content directly. When false (default), returns immediately " +
+            "with a confirmation message — use get_plan later to retrieve results."),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("When wait_for_result is true, whether to save the plan to a local file in the " +
+            "BAPI_DOCS_DIR/plans/ directory. Defaults to true. Ignored when wait_for_result is false."),
+        second_opinion: z.string().optional(),
+        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
+            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
+            "second_opinion takes precedence."),
+    },
+}, async ({ ticket_number, wait_for_result, save_locally, second_opinion, provider }) => {
+    const body = { repo_name: REPO_NAME };
+    const trimmedSecondOpinion = second_opinion?.trim();
+    if (trimmedSecondOpinion) {
+        body.provider_override = trimmedSecondOpinion;
+    }
+    const trimmedProvider = provider?.trim();
+    if (trimmedProvider && !trimmedSecondOpinion) {
+        body.provider = trimmedProvider;
+    }
+    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/generate-plan`), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+        const errorText = await handleResponse(resp);
+        return {
+            content: [{ type: "text", text: `Failed to request plan generation: ${errorText}` }],
+        };
+    }
+    if (wait_for_result) {
+        const getUrl = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/plan`, { repo_name: REPO_NAME });
+        const result = await pollForResult(getUrl, 900_000, `Plan generation for ${ticket_number}`);
+        if (!result.ok) {
+            return { content: [{ type: "text", text: result.text }] };
+        }
+        let text = result.text;
+        if (save_locally) {
+            const note = await saveLocally(getDocsPath("plans"), `${ticket_number}-plan.md`, text);
+            text += note;
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    const confirmationText = `Plan generation requested for ${ticket_number}. ` +
+        `Processing typically takes 1-5 minutes. ` +
+        `Use get_plan with ticket_number "${ticket_number}" to retrieve the plan once processing completes.`;
+    return { content: [{ type: "text", text: confirmationText }] };
+});
+server.registerTool("request_architecture", {
+    description: "Request AI-generated architecture plan for a Jira ticket. " +
+        "This triggers an asynchronous background job — results are NOT immediate. " +
+        "Processing typically takes 2-4 minutes depending on ticket complexity. " +
+        "After submitting, use get_architecture with the same ticket_number to check if results are available. " +
+        "Returns 202 if the request was accepted, 404 if the ticket does not exist in Jira, " +
+        "or 403 if the API key is unauthorized. " +
+        "Set wait_for_result to true to block until the result is ready (typically 2-4 minutes) instead of returning immediately.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate an architecture plan for"),
+        wait_for_result: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When true, the tool blocks and polls until the architecture plan is ready (typically 2-4 minutes), " +
+            "then returns the full plan content directly. When false (default), returns immediately " +
+            "with a confirmation message — use get_architecture later to retrieve results."),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("When wait_for_result is true, whether to save the architecture plan to a local file in the " +
+            "BAPI_DOCS_DIR/architecture/ directory. Defaults to true. Only takes effect when wait_for_result is true."),
+        second_opinion: z.string().optional(),
+        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
+            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
+            "second_opinion takes precedence."),
+    },
+}, async ({ ticket_number, wait_for_result, save_locally, second_opinion, provider }) => {
+    const body = { repo_name: REPO_NAME };
+    const trimmedSecondOpinion = second_opinion?.trim();
+    if (trimmedSecondOpinion) {
+        body.provider_override = trimmedSecondOpinion;
+    }
+    const trimmedProvider = provider?.trim();
+    if (trimmedProvider && !trimmedSecondOpinion) {
+        body.provider = trimmedProvider;
+    }
+    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/generate-architecture`), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+        const errorText = await handleResponse(resp);
+        return {
+            content: [{ type: "text", text: `Failed to request architecture generation: ${errorText}` }],
+        };
+    }
+    if (wait_for_result) {
+        const getUrl = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/architecture-plan`, { repo_name: REPO_NAME });
+        const result = await pollForResult(getUrl, 900_000, `Architecture generation for ${ticket_number}`);
+        if (!result.ok) {
+            return { content: [{ type: "text", text: result.text }] };
+        }
+        let text = result.text;
+        if (save_locally) {
+            const note = await saveLocally(getDocsPath("architecture"), `${ticket_number}-architecture-plan.md`, text);
+            text += note;
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    const confirmationText = `Architecture generation requested for ${ticket_number}. ` +
+        `Processing typically takes 2-4 minutes. ` +
+        `Use get_architecture with ticket_number "${ticket_number}" to retrieve the architecture plan once processing completes.`;
+    return { content: [{ type: "text", text: confirmationText }] };
+});
+server.registerTool("request_clarifying_questions", {
+    description: "Request AI-generated clarifying questions or debugging guidance for a Jira ticket. " +
+        "This triggers an asynchronous background job — results are NOT immediate. " +
+        "Processing typically takes 1-5 minutes. " +
+        "After submitting, use get_clarifying_questions with the same ticket_number to check if results are available. " +
+        "For bug tickets, the result may be debugging guidance instead of clarifying questions. " +
+        "Returns 202 if the request was accepted, 404 if the ticket does not exist in Jira, " +
+        "or 403 if the API key is unauthorized. " +
+        "Set wait_for_result to true to block until the result is ready (typically 1-5 minutes) instead of returning immediately.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate clarifying questions for"),
+        wait_for_result: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When true, the tool blocks and polls until the clarifying questions are ready (typically 1-5 minutes), " +
+            "then returns the full content directly. When false (default), returns immediately " +
+            "with a confirmation message — use get_clarifying_questions later to retrieve results."),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("When wait_for_result is true, whether to save the clarifying questions to a local file in the " +
+            "BAPI_DOCS_DIR/clarifying-questions/ directory. Defaults to true. Ignored when wait_for_result is false."),
+        second_opinion: z.string().optional(),
+        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
+            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
+            "second_opinion takes precedence."),
+    },
+}, async ({ ticket_number, wait_for_result, save_locally, second_opinion, provider }) => {
+    const body = { repo_name: REPO_NAME };
+    const trimmedSecondOpinion = second_opinion?.trim();
+    if (trimmedSecondOpinion) {
+        body.provider_override = trimmedSecondOpinion;
+    }
+    const trimmedProvider = provider?.trim();
+    if (trimmedProvider && !trimmedSecondOpinion) {
+        body.provider = trimmedProvider;
+    }
+    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/generate-clarifying-questions`), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+        const errorText = await handleResponse(resp);
+        return {
+            content: [{ type: "text", text: `Failed to request clarifying questions: ${errorText}` }],
+        };
+    }
+    if (wait_for_result) {
+        const getUrl = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/clarifying-questions`, { repo_name: REPO_NAME });
+        const result = await pollForResult(getUrl, 900_000, `Clarifying questions for ${ticket_number}`);
+        if (!result.ok) {
+            return { content: [{ type: "text", text: result.text }] };
+        }
+        let text = result.text;
+        if (save_locally) {
+            const note = await saveLocally(getDocsPath("clarifying-questions"), `${ticket_number}-clarifying-questions.md`, text);
+            text += note;
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    const confirmationText = `Clarifying questions requested for ${ticket_number}. ` +
+        `Processing typically takes 1-5 minutes. ` +
+        `Use get_clarifying_questions with ticket_number "${ticket_number}" to retrieve the results once processing completes.`;
+    return { content: [{ type: "text", text: confirmationText }] };
+});
+// ---------------------------------------------------------------------------
+// Ticket Quality Critique
+// ---------------------------------------------------------------------------
+server.registerTool("get_ticket_critique", {
+    description: "Retrieve AI-generated ticket quality critique for a Jira ticket. " +
+        "Returns markdown text with a structured critique covering Standards Conformance Analysis, " +
+        "Standards Deviations, and Suggested Improvements. " +
+        "Returns 404 if no critique has been generated yet. " +
+        "Tip: use request_ticket_critique to trigger critique generation first.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Whether to save the critique to a local file in the BAPI_DOCS_DIR/ticket-critiques/ directory. " +
+            "Defaults to true. Set to false to skip saving."),
+    },
+}, async ({ ticket_number, save_locally }) => {
+    const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/ticket-critique`, { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const ok = resp.ok;
+    let text = await handleResponse(resp);
+    if (ok && save_locally) {
+        const note = await saveLocally(getDocsPath("ticket-critiques"), `${ticket_number}-ticket-quality-critique.md`, text);
+        text += note;
+    }
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("request_ticket_critique", {
+    description: "Request AI-generated ticket critique for a Jira ticket. " +
+        "This triggers an asynchronous background job — results are NOT immediate. " +
+        "Processing typically takes 1-5 minutes. " +
+        "After submitting, use get_ticket_critique with the same ticket_number to check if results are available. " +
+        "Returns 202 if the request was accepted, 404 if the ticket does not exist in Jira, " +
+        "or 403 if the API key is unauthorized. " +
+        "Set wait_for_result to true to block until the result is ready (typically 1-5 minutes) instead of returning immediately.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate a ticket critique for"),
+        wait_for_result: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When true, the tool blocks and polls until the ticket critique is ready (typically 1-5 minutes), " +
+            "then returns the full content directly. When false (default), returns immediately " +
+            "with a confirmation message — use get_ticket_critique later to retrieve results."),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("When wait_for_result is true, whether to save the ticket critique to a local file in the " +
+            "BAPI_DOCS_DIR/ticket-critiques/ directory. Defaults to true. Ignored when wait_for_result is false."),
+        second_opinion: z.string().optional(),
+        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
+            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
+            "second_opinion takes precedence."),
+    },
+}, async ({ ticket_number, wait_for_result, save_locally, second_opinion, provider }) => {
+    const body = { repo_name: REPO_NAME };
+    const trimmedSecondOpinion = second_opinion?.trim();
+    if (trimmedSecondOpinion) {
+        body.provider_override = trimmedSecondOpinion;
+    }
+    const trimmedProvider = provider?.trim();
+    if (trimmedProvider && !trimmedSecondOpinion) {
+        body.provider = trimmedProvider;
+    }
+    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/generate-ticket-critique`), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+        const errorText = await handleResponse(resp);
+        return {
+            content: [{ type: "text", text: `Failed to request ticket critique: ${errorText}` }],
+        };
+    }
+    if (wait_for_result) {
+        const getUrl = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/ticket-critique`, { repo_name: REPO_NAME });
+        const result = await pollForResult(getUrl, 900_000, `Ticket critique for ${ticket_number}`);
+        if (!result.ok) {
+            return { content: [{ type: "text", text: result.text }] };
+        }
+        let text = result.text;
+        if (save_locally) {
+            const note = await saveLocally(getDocsPath("ticket-critiques"), `${ticket_number}-ticket-quality-critique.md`, text);
+            text += note;
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    const confirmationText = `Ticket critique requested for ${ticket_number}. ` +
+        `Processing typically takes 1-5 minutes. ` +
+        `Use get_critique with ticket_number "${ticket_number}" to retrieve the results once processing completes.`;
+    return { content: [{ type: "text", text: confirmationText }] };
+});
+// ---------------------------------------------------------------------------
+// Reimplement Context
+// ---------------------------------------------------------------------------
+server.registerTool("request_reimplement_context", {
+    description: "Request processing of new attachments and context assembly for a previously-implemented Jira ticket. " +
+        "Use this for follow-up requests on tickets that have already been through the plan+implement cycle. " +
+        "This triggers an asynchronous background job to process new attachments/images. " +
+        "After submitting, use get_reimplement_context with the same ticket_number to retrieve the assembled context. " +
+        "Set wait_for_result to true to block until the context is ready instead of returning immediately.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        wait_for_result: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When true, POST then poll the GET endpoint until the context is ready. " +
+            "When false (default), return immediately with a confirmation — use get_reimplement_context later."),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("When wait_for_result is true, save the context markdown to " +
+            "BAPI_DOCS_DIR/reimplementations/{ticket_number}-context.md. Defaults to true."),
+        second_opinion: z.string().optional(),
+        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
+            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
+            "second_opinion takes precedence."),
+    },
+}, async ({ ticket_number, wait_for_result, save_locally, second_opinion, provider }) => {
+    const body = { repo_name: REPO_NAME };
+    const trimmedSecondOpinion = second_opinion?.trim();
+    if (trimmedSecondOpinion) {
+        body.provider_override = trimmedSecondOpinion;
+    }
+    const trimmedProvider = provider?.trim();
+    if (trimmedProvider && !trimmedSecondOpinion) {
+        body.provider = trimmedProvider;
+    }
+    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/request-reimplement-context`), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+        const errorText = await handleResponse(resp);
+        return {
+            content: [{ type: "text", text: `Failed to request reimplement context: ${errorText}` }],
+        };
+    }
+    if (wait_for_result) {
+        const getUrl = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/reimplement-context`, { repo_name: REPO_NAME });
+        const result = await pollForResult(getUrl, 900_000, `Reimplement context for ${ticket_number}`);
+        if (!result.ok) {
+            return { content: [{ type: "text", text: result.text }] };
+        }
+        let text = result.text;
+        if (save_locally) {
+            const note = await saveLocally(getDocsPath("reimplementations"), `${ticket_number}-context.md`, text);
+            text += note;
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    const confirmationText = `Reimplement context processing requested for ${ticket_number}. ` +
+        `Processing typically takes 1-2 minutes. ` +
+        `Use get_reimplement_context with ticket_number "${ticket_number}" to retrieve the results once processing completes.`;
+    return { content: [{ type: "text", text: confirmationText }] };
+});
+server.registerTool("get_reimplement_context", {
+    description: "Retrieve the assembled reimplement context for a Jira ticket. " +
+        "Returns a markdown document with new/changed information diffed against stored state, " +
+        "the original ticket description, and the existing implementation plan. " +
+        "Returns 404 if processing is not yet complete. " +
+        "Tip: use request_reimplement_context to trigger processing first.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Save the context to BAPI_DOCS_DIR/reimplementations/{ticket_number}-context.md. Defaults to true."),
+    },
+}, async ({ ticket_number, save_locally }) => {
+    const resp = await fetch(buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/reimplement-context`, { repo_name: REPO_NAME }), { headers: GET_HEADERS });
+    if (resp.status === 404) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        error: "NOT_FOUND",
+                        message: `Reimplement context for ${ticket_number} is not yet available. ` +
+                            `Processing may still be in progress. Try again in a moment, ` +
+                            `or call request_reimplement_context to trigger processing.`,
+                    }),
+                }],
+        };
+    }
+    const text = await handleResponse(resp);
+    if (save_locally) {
+        const note = await saveLocally(getDocsPath("reimplementations"), `${ticket_number}-context.md`, text);
+        return { content: [{ type: "text", text: text + note }] };
+    }
+    return { content: [{ type: "text", text }] };
+});
+// ---------------------------------------------------------------------------
+// Ticket Lifecycle Tracking
+// ---------------------------------------------------------------------------
+server.registerTool("track_ticket", {
+    description: "Insert a ticket into Bridge API's database for lifecycle tracking. This registers the ticket so that workflow state timestamps (critique, clarify, plan, implement) can be tracked. " +
+        "If the ticket is already tracked, this is a safe no-op — it upserts the description and repo_name without error. " +
+        "Call this after creating a ticket with create_ticket to enable state tracking. " +
+        "The repo_name is automatically injected from the configured environment.",
+    inputSchema: {
+        ticket_number: z.string().describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        description: z.string().optional().describe("Ticket description text. Optional — used to store a local copy of the description for reference."),
+    },
+}, async ({ ticket_number, description }) => {
+    const payload = { repo_name: REPO_NAME };
+    if (description !== undefined)
+        payload.description = description;
+    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/track`), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(payload),
+    });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("update_ticket_state", {
+    description: "Update workflow state timestamps on a tracked ticket. Each specified field is set to the current UTC timestamp on the server. " +
+        "Valid field names: 'critique_called', 'critique_answered', 'clarify_called', 'clarify_answered', 'plan_generated', 'implemented', 'reimplement_called'. " +
+        "The ticket must already be tracked (via track_ticket) or a 404 error is returned. " +
+        "Returns 400 if any field name is invalid. " +
+        "The repo_name is automatically injected from the configured environment.",
+    inputSchema: {
+        ticket_number: z.string().describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        fields: z.array(z.string()).describe("List of state field names to set to the current UTC timestamp. Valid values: 'critique_called', 'critique_answered', 'clarify_called', 'clarify_answered', 'plan_generated', 'implemented', 'reimplement_called'"),
+    },
+}, async ({ ticket_number, fields }) => {
+    const payload = { repo_name: REPO_NAME, fields };
+    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/state`), {
+        method: "PUT",
+        headers: POST_HEADERS,
+        body: JSON.stringify(payload),
+    });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("get_ticket_state", {
+    description: "Retrieve workflow state timestamps and artifact existence flags for a tracked ticket. " +
+        "Returns timestamps for each state field (critique_called, critique_answered, clarify_called, clarify_answered, plan_generated, implemented, reimplement_called) " +
+        "and boolean flags indicating whether artifacts exist (has_clarifying_questions, has_critique, has_plan). " +
+        "The ticket must be tracked via track_ticket first, or a 404 is returned. " +
+        "The repo_name is automatically injected from the configured environment.",
+    inputSchema: {
+        ticket_number: z.string().describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+    },
+}, async ({ ticket_number }) => {
+    const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/state`, { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+// ---------------------------------------------------------------------------
+// Jira Transitions
+// ---------------------------------------------------------------------------
+server.registerTool("get_jira_transitions", {
+    description: "List available Jira workflow transitions for a ticket. Returns each transition's id, name, and target status. " +
+        "Use this to discover what status changes are possible for a given ticket. " +
+        "The repo_name is automatically injected from the configured environment.",
+    inputSchema: {
+        ticket_number: z.string().describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+    },
+}, async ({ ticket_number }) => {
+    const url = buildGetUrl(`/tickets/${encodeURIComponent(ticket_number)}/jira-transitions`, { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("update_jira_status", {
+    description: "Transition a Jira ticket to a specified target status by executing a workflow transition. " +
+        "Provide either target_status (matched case-insensitively against available transitions) or transition_id (used directly). " +
+        "If transition_id is provided, it takes precedence over target_status. " +
+        "Returns the from/to status on success, or an error listing available transitions if no match is found. " +
+        "The repo_name is automatically injected from the configured environment.",
+    inputSchema: {
+        ticket_number: z.string().describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        target_status: z.string().optional().describe("Target status name to transition to (case-insensitive match)"),
+        transition_id: z.string().optional().describe("Specific transition ID to execute (takes precedence over target_status)"),
+    },
+}, async ({ ticket_number, target_status, transition_id }) => {
+    const payload = { repo_name: REPO_NAME };
+    if (target_status !== undefined)
+        payload.target_status = target_status;
+    if (transition_id !== undefined)
+        payload.transition_id = transition_id;
+    const resp = await fetch(buildUrl(`/tickets/${encodeURIComponent(ticket_number)}/jira-status`), {
+        method: "PUT",
+        headers: POST_HEADERS,
+        body: JSON.stringify(payload),
+    });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("resolve_target_status", {
+    description: "Resolve the post-PR target Jira status for the configured repository using an LLM agent. " +
+        "The agent selects the workflow status that best represents 'code committed via PR but not yet tested.' " +
+        "Results are cached per-project — subsequent calls return the cached value unless force_rerun is true. " +
+        "Requires a ticket_number to fetch available transitions from Jira. " +
+        "The repo_name is automatically injected from the configured environment.",
+    inputSchema: {
+        ticket_number: z.string().describe("Jira ticket key to fetch available transitions from (e.g. PROJ-123)"),
+        force_rerun: z.boolean().optional().describe("Set to true to bypass the cache and re-resolve the target status via LLM"),
+    },
+}, async ({ ticket_number, force_rerun }) => {
+    const payload = {
+        repo_name: REPO_NAME,
+        ticket_number,
+    };
+    if (force_rerun !== undefined)
+        payload.force_rerun = force_rerun;
+    const resp = await fetch(buildUrl("/resolve-target-status"), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(payload),
+    });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+// ---------------------------------------------------------------------------
+// Config Fields
+// ---------------------------------------------------------------------------
+const VALID_CONFIG_FIELDS = [
+    "review_instructions", "documentation_instructions", "architecture_instructions",
+    "unit_testing_instructions", "e2e_testing_instructions",
+    "frontend_correctness_standards", "backend_correctness_standards",
+    "template_correctness_standards", "style_correctness_standards",
+    "post_pr_target_status", "ci_check_config",
+].join(", ");
+server.registerTool("list_config_fields", {
+    description: "List all configurable fields available for reading and updating via the Bridge API. " +
+        "Returns each field's name and a description of its purpose. No database values are returned — " +
+        "use get_config_field to read a specific field's current value. " +
+        "Use this tool to discover what configuration options are available before reading or updating them.",
+    inputSchema: {},
+}, async () => {
+    const url = buildGetUrl("/config-fields", { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("get_my_role", {
+    description: "Check the role and auth source for the current API key. " +
+        "Returns JSON with {role: \"admin\" | \"member\" | null, source: \"user_access\" | \"legacy\"}. " +
+        "Use this to check if the current key has admin permissions before attempting configuration updates " +
+        "via update_config_field. Non-admin user_access keys will be blocked from config updates.",
+    inputSchema: {},
+}, async () => {
+    const url = buildGetUrl("/my-role", { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("get_config_field", {
+    description: "Read the current value and metadata for a specific configuration field. " +
+        "Returns the field's current database value (or null if not set), along with a description of its purpose and examples of helpful content. " +
+        "Use this before update_config_field to understand the current state and build upon it rather than overwriting blindly.",
+    inputSchema: {
+        field_name: z.string().describe(`The configuration field to read. Valid options: ${VALID_CONFIG_FIELDS}`),
+    },
+}, async ({ field_name }) => {
+    const url = buildGetUrl(`/config-field/${encodeURIComponent(field_name)}`, { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("update_config_field", {
+    description: "Update a specific configuration field in the Bridge database. " +
+        "These fields control LLM behavior during code review, planning, and documentation. " +
+        "Always call get_config_field first to read the current value and build upon it. " +
+        "Returns 400 if the field name is invalid, 404 if the repository has no configuration row yet.",
+    inputSchema: {
+        field_name: z.string().describe(`The configuration field to update. Valid options: ${VALID_CONFIG_FIELDS}`),
+        value: z.string().optional().describe("The new value for the configuration field. Provide either value or file_path, not both. " +
+            "Omit both value and file_path to set the field to NULL (clearing it)."),
+        file_path: z.string().optional().describe("Path to a local file whose contents will be used as the new value. " +
+            "Useful for large configuration values like detailed review instructions. " +
+            "The file must be UTF-8 encoded and under 1MB."),
+    },
+}, async ({ field_name, value, file_path }) => {
+    // Allow omitting both value and file_path to set NULL
+    let finalValue = null;
+    let note = "";
+    if (value || file_path) {
+        const resolved = await resolveTextOrFile(value, file_path, "value");
+        if (!resolved.ok)
+            return resolved.errorResponse;
+        finalValue = resolved.text;
+        note = resolved.note;
+    }
+    const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
+        method: "PUT",
+        headers: POST_HEADERS,
+        body: JSON.stringify({ repo_name: REPO_NAME, value: finalValue }),
+    });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text: text + note }] };
+});
+// ---------------------------------------------------------------------------
+// Deep Research
+// ---------------------------------------------------------------------------
+server.registerTool("request_deep_research", {
+    description: "Submit a deep research request on a technical topic using AI-powered web search. " +
+        "Returns a task_id for tracking the research progress. " +
+        "\n\n" +
+        "WHEN TO USE: Use this tool when you need to investigate unfamiliar technologies, " +
+        "gather implementation guidance across multiple sources, research best practices for a complex topic, " +
+        "or when the depth of information needed exceeds what a single web search can provide. " +
+        "Example: 'What are the best practices for implementing WebSocket connection pooling in Python asyncio, " +
+        "including error handling, reconnection strategies, and load balancing across multiple servers?' " +
+        "\n\n" +
+        "WHEN NOT TO USE: Do NOT use this for quick factual lookups, single-question searches, " +
+        "or anything a standard web search could answer in seconds. " +
+        "Bad example: 'websocket python' — use a web search instead. " +
+        "\n\n" +
+        "BEHAVIOR: By default, returns immediately with a task_id. Use get_deep_research to retrieve the result " +
+        "once processing completes (typically 2-10 minutes). " +
+        "Set wait_for_result to true to block until the report is ready (up to 15 minutes). " +
+        "On failure, do not retry automatically — the underlying issue (provider outage, rate limit) " +
+        "is unlikely to resolve immediately. Fall back to standard web searches to gather the information incrementally.",
+    inputSchema: {
+        query: z.string().describe("The research query. Be specific and detailed about what you need to learn. " +
+            "Good: 'What are the tradeoffs between Redis, Memcached, and DynamoDB DAX for caching in a Python FastAPI " +
+            "application serving 10k RPM, including connection pooling, serialization overhead, and failure modes?' " +
+            "Bad: 'caching options' (too vague — use a web search instead)"),
+        context: z.string().optional().describe("Optional context to focus the research scope. Describe your current task, tech stack, and constraints. " +
+            "Example: 'I am building a FastAPI application that uses PostgreSQL and needs to implement real-time " +
+            "notifications. Focus on Python-specific solutions compatible with async frameworks.'"),
+        ticket_number: z.string().optional().describe("Optional Jira ticket key (e.g. PROJ-123) to associate this research with a specific ticket. " +
+            "Helps trace research results back to the ticket that prompted the investigation."),
+        wait_for_result: z.boolean().optional().default(false).describe("When true, blocks and polls until the research is ready (up to 15 minutes), " +
+            "then returns the full report directly. When false (default), returns immediately " +
+            "with a task_id — use get_deep_research later to retrieve results."),
+        save_locally: z.boolean().optional().default(true).describe("Whether to save the research report to the BAPI_DOCS_DIR/deep-research/ directory. " +
+            "Defaults to true. When wait_for_result is false, saving happens when you call get_deep_research instead."),
+    },
+}, async ({ query, context, ticket_number, wait_for_result, save_locally }) => {
+    // 1. Submit the deep research request
+    const submitPayload = { repo_name: REPO_NAME, query };
+    if (context)
+        submitPayload.context = context;
+    if (ticket_number)
+        submitPayload.ticket_number = ticket_number;
+    const submitResp = await fetch(buildUrl("/deep-research"), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(submitPayload),
+    });
+    if (!submitResp.ok) {
+        const errorText = await handleResponse(submitResp);
+        return { content: [{ type: "text", text: errorText }] };
+    }
+    const submitBody = (await submitResp.json());
+    const taskId = submitBody.task_id;
+    if (!wait_for_result) {
+        const confirmationText = `Deep research submitted (task_id: ${taskId}). ` +
+            `Processing typically takes 2-10 minutes. ` +
+            `Use get_deep_research with task_id ${taskId} to retrieve the result once processing completes.`;
+        return { content: [{ type: "text", text: confirmationText }] };
+    }
+    // 2. Poll until completion or timeout
+    const startTime = Date.now();
+    const MAX_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
+    let pollIntervalMs = 15_000; // start at 15 seconds
+    let lastStatus = "queued";
+    while (Date.now() - startTime < MAX_TIMEOUT_MS) {
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        const elapsed = Math.round((Date.now() - startTime) / 1000);
+        console.error(`Deep research in progress... (elapsed: ${elapsed}s, status: ${lastStatus})`);
+        const statusUrl = buildGetUrl(`/deep-research/${taskId}/status`, { repo_name: REPO_NAME });
+        const statusResp = await fetch(statusUrl, { headers: GET_HEADERS });
+        if (!statusResp.ok) {
+            const errorText = await handleResponse(statusResp);
+            return { content: [{ type: "text", text: JSON.stringify({ error: "INTERNAL_ERROR", status: 500, message: `Error polling deep research status: ${errorText}` }) }] };
+        }
+        const statusBody = (await statusResp.json());
+        lastStatus = statusBody.status;
+        if (lastStatus === "completed") {
+            break;
+        }
+        if (lastStatus === "failed") {
+            const errorMsg = statusBody.error_message || "Unknown error";
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ error: "INTERNAL_ERROR", status: 500, message: `Deep research failed: ${errorMsg}. Consider using standard web searches to gather the information incrementally.` }),
+                    }],
+            };
+        }
+        // Increase poll interval after first minute
+        if (Date.now() - startTime > 60_000) {
+            pollIntervalMs = 30_000;
+        }
+    }
+    if (lastStatus !== "completed") {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ error: "GATEWAY_TIMEOUT", status: 504, message: `Deep research timed out after 15 minutes (task_id: ${taskId}). The task may still be processing on the server. Use get_deep_research with this task_id to check later, or use standard web searches to gather the information incrementally.` }),
+                }],
+        };
+    }
+    // 3. Retrieve the result
+    const resultUrl = buildGetUrl(`/deep-research/${taskId}/result`, { repo_name: REPO_NAME });
+    const resultResp = await fetch(resultUrl, { headers: GET_HEADERS });
+    if (!resultResp.ok) {
+        const errorText = await handleResponse(resultResp);
+        return { content: [{ type: "text", text: JSON.stringify({ error: "INTERNAL_ERROR", status: 500, message: `Error retrieving deep research result: ${errorText}` }) }] };
+    }
+    let resultText = await resultResp.text();
+    // 4. Optionally save to file
+    if (save_locally) {
+        const slug = slugify(query);
+        const note = await saveLocally(getDocsPath("deep-research"), `${slug}-${taskId}.md`, resultText);
+        resultText += note;
+    }
+    return { content: [{ type: "text", text: resultText }] };
+});
+server.registerTool("get_deep_research", {
+    description: "Retrieve the result of a previously submitted deep research request. " +
+        "Returns the full markdown research report if the task is completed, " +
+        "or a structured status response if still processing or failed. " +
+        "Use this after calling request_deep_research with wait_for_result=false.",
+    inputSchema: {
+        task_id: z.number().describe("The task ID returned by request_deep_research."),
+        query_slug: z.string().optional().describe("Optional slug derived from the original query, used for the saved filename. " +
+            "If omitted, the file is saved as 'research-{task_id}.md'."),
+        save_locally: z.boolean().optional().default(true).describe("Whether to save the research report to the BAPI_DOCS_DIR/deep-research/ directory. Defaults to true."),
+    },
+}, async ({ task_id, query_slug, save_locally }) => {
+    // 1. Check status
+    const statusUrl = buildGetUrl(`/deep-research/${task_id}/status`, { repo_name: REPO_NAME });
+    const statusResp = await fetch(statusUrl, { headers: GET_HEADERS });
+    if (!statusResp.ok) {
+        const errorText = await handleResponse(statusResp);
+        return { content: [{ type: "text", text: errorText }] };
+    }
+    const statusBody = (await statusResp.json());
+    if (statusBody.status === "failed") {
+        const errorMsg = statusBody.error_message || "Unknown error";
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ error: "INTERNAL_ERROR", status: 500, message: `Deep research failed: ${errorMsg}. Consider using standard web searches to gather the information incrementally.` }),
+                }],
+        };
+    }
+    if (statusBody.status !== "completed") {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ status: statusBody.status, task_id, message: `Deep research is still ${statusBody.status}. Try again in a minute.` }),
+                }],
+        };
+    }
+    // 2. Retrieve the result
+    const resultUrl = buildGetUrl(`/deep-research/${task_id}/result`, { repo_name: REPO_NAME });
+    const resultResp = await fetch(resultUrl, { headers: GET_HEADERS });
+    if (!resultResp.ok) {
+        const errorText = await handleResponse(resultResp);
+        return { content: [{ type: "text", text: errorText }] };
+    }
+    let resultText = await resultResp.text();
+    // 3. Optionally save to file
+    if (save_locally) {
+        const slug = query_slug || "research";
+        const note = await saveLocally(getDocsPath("deep-research"), `${slug}-${task_id}.md`, resultText);
+        resultText += note;
+    }
+    return { content: [{ type: "text", text: resultText }] };
+});
+// ---------------------------------------------------------------------------
+// VCS & CI Tools
+// ---------------------------------------------------------------------------
+server.registerTool("create_pull_request", {
+    description: "Create a pull request on the configured VCS provider (GitHub or Bitbucket). " +
+        "Returns a structured response with {available, reason, action, detail}. " +
+        "If a PR already exists for the head branch, returns it with created=false. " +
+        "Capability issues (missing VCS config, API errors) return available=false, not errors. " +
+        "The repo_name is automatically injected from the configured environment.",
+    inputSchema: {
+        head_branch: z.string().describe("The source branch name for the pull request"),
+        base_branch: z.string().describe("The target/destination branch name for the pull request"),
+        title: z.string().describe("The title of the pull request"),
+        body: z.string().optional().describe("The description/body of the pull request"),
+    },
+}, async ({ head_branch, base_branch, title, body }) => {
+    const payload = {
+        repo_name: REPO_NAME,
+        head_branch,
+        base_branch,
+        title,
+    };
+    if (body !== undefined)
+        payload.body = body;
+    const resp = await fetch(buildUrl("/vcs/pull-requests"), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(payload),
+    });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+const resolveCiChecksTool = server.registerTool("resolve_ci_checks", {
+    description: "Discover and classify CI checks for the configured repository. " +
+        "Queries GitHub Check Runs + Commit Statuses APIs (or Bitbucket Build Statuses), " +
+        "then uses Branch Protection API or LLM to determine which checks are required for merging. " +
+        "Results are cached per-project — subsequent calls return cached config unless force_rerun is true. " +
+        "Returns {available, reason, action, detail} envelope. " +
+        "The repo_name is automatically injected from the configured environment.",
+    inputSchema: {
+        commit_ref: z.string().describe("Git commit SHA to discover checks for"),
+        force_rerun: z.boolean().optional().describe("Set to true to bypass cache and re-resolve CI checks"),
+    },
+}, async ({ commit_ref, force_rerun }) => {
+    const payload = {
+        repo_name: REPO_NAME,
+        commit_ref,
+    };
+    if (force_rerun !== undefined)
+        payload.force_rerun = force_rerun;
+    const resp = await fetch(buildUrl("/resolve-ci-checks"), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(payload),
+    });
+    const text = await handleResponse(resp);
+    // Re-enable poll_ci_checks after successful resolution
+    try {
+        const result = JSON.parse(text);
+        if (result.available === true) {
+            pollCiChecksTool.enable();
+        }
+    }
+    catch {
+        // Not JSON — leave poll tool state unchanged
+    }
+    return { content: [{ type: "text", text }] };
+});
+const pollCiChecksTool = server.registerTool("poll_ci_checks", {
+    description: "Poll the current status of CI checks for a specific commit. " +
+        "Requires that resolve_ci_checks has been called first to populate the check configuration. " +
+        "Returns per-check status, all_complete, all_passed, and unknown_checks fields. " +
+        "For failed checks with detail_level 'full', includes annotations and/or log tails. " +
+        "Returns {available, reason, action, detail} envelope. " +
+        "The repo_name is automatically injected from the configured environment.",
+    inputSchema: {
+        commit_ref: z.string().describe("Git commit SHA to poll CI checks for"),
+    },
+}, async ({ commit_ref }) => {
+    const url = buildGetUrl("/poll-ci-checks", {
+        repo_name: REPO_NAME,
+        commit_ref,
+    });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+// ---------------------------------------------------------------------------
+// Conditional CI tool visibility
+// ---------------------------------------------------------------------------
+async function checkCiConfigAndDisablePoll() {
+    try {
+        const url = buildGetUrl("/config-field/ci_check_config", { repo_name: REPO_NAME });
+        const resp = await fetch(url, { headers: GET_HEADERS });
+        if (resp.ok) {
+            const body = await resp.json();
+            const value = body.value;
+            if (value === null || value === undefined) {
+                pollCiChecksTool.disable();
+                console.error("poll_ci_checks disabled: ci_check_config is null");
+            }
+        }
+        else {
+            // Config field not found or error — disable poll tool
+            pollCiChecksTool.disable();
+            console.error("poll_ci_checks disabled: could not read ci_check_config");
+        }
+    }
+    catch (err) {
+        // Network error or server not reachable — disable poll tool
+        pollCiChecksTool.disable();
+        console.error(`poll_ci_checks disabled: ${err}`);
+    }
+}
+// Check config before connecting
+await checkCiConfigAndDisablePoll();
+// ---------------------------------------------------------------------------
+// Pipeline Recipe Tools
+// ---------------------------------------------------------------------------
+server.registerTool("get_docs_dir", {
+    description: "Return the locally configured docs directory path (BAPI_DOCS_DIR, default docs/tmp). " +
+        "No parameters. Use this instead of reading the BAPI_DOCS_DIR environment variable directly, " +
+        "which requires shell access and may be blocked on some AI coding platforms.",
+    inputSchema: {},
+}, async () => {
+    return { content: [{ type: "text", text: BAPI_DOCS_DIR }] };
+});
+server.registerTool("list_pipelines", {
+    description: "List all available pipeline recipes with their names, descriptions, and required variables. " +
+        "No parameters. Use this to discover available pipelines before calling get_pipeline_recipe.",
+    inputSchema: {},
+}, async () => {
+    const list = Object.entries(PIPELINES).map(([key, pipeline]) => ({
+        name: key,
+        description: pipeline.description ?? "",
+        variables: (pipeline.variables ?? []).filter((v) => v !== "docs_dir"),
+    }));
+    return {
+        content: [{ type: "text", text: JSON.stringify(list, null, 2) }],
+    };
+});
+server.registerTool("get_pipeline_recipe", {
+    description: "Retrieve a fully resolved pipeline recipe by name. Substitutes variables, resolves instruction " +
+        "file references to inline content, and returns an ordered array of executable steps. " +
+        "Each step is either an mcp_call (with tool name and params) or an agent_task (with instruction text). " +
+        "Use list_pipelines to discover available pipeline names first. " +
+        "Note: the 'docs_dir' variable is automatically set from BAPI_DOCS_DIR — callers should omit it.",
+    inputSchema: {
+        pipeline: z
+            .string()
+            .describe("Pipeline name (e.g. 'review-ticket', 'implement-ticket')"),
+        variables: z
+            .record(z.string())
+            .optional()
+            .describe("Key-value pairs for variable substitution (e.g. { ticket_key: 'BAPI-123' })"),
+        skip_steps: z
+            .array(z.string())
+            .optional()
+            .describe("Step tool names or descriptions to omit from the recipe"),
+    },
+}, async ({ pipeline: pipelineName, variables, skip_steps }) => {
+    const pipelineDef = PIPELINES[pipelineName];
+    if (!pipelineDef) {
+        const available = Object.keys(PIPELINES).join(", ");
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        error: ERROR_CODES[404] ?? "NOT_FOUND",
+                        status: 404,
+                        message: `Pipeline "${pipelineName}" not found. Available pipelines: ${available || "(none)"}`,
+                    }),
+                }],
+        };
+    }
+    try {
+        const mergedVariables = { docs_dir: BAPI_DOCS_DIR, provider: "", second_opinion: "", ...(variables ?? {}) };
+        const recipe = resolveRecipe(pipelineDef, INSTRUCTIONS, mergedVariables, skip_steps);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(recipe, null, 2),
+                }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const isServerError = message.includes("not found in bundled instructions");
+        const status = isServerError ? 500 : 400;
+        const code = isServerError ? "PIPELINE_DATA_ERROR" : (ERROR_CODES[400] ?? "BAD_REQUEST");
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ error: code, status, message }),
+                }],
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("Bridge API MCP server running on stdio");