@bridge_gpt/mcp-server 0.1.8 → 0.1.10

package/build/index.js

@@ -14,9 +14,16 @@ 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 { execSync } from "child_process";
+import { createRequire } from "module";
 import { PIPELINES as BUNDLED_PIPELINES, INSTRUCTIONS as BUNDLED_INSTRUCTIONS } from "./pipelines.generated.js";
 import { COMMANDS } from "./commands.generated.js";
+import { AGENTS } from "./agents.generated.js";
+import { VERSION } from "./version.generated.js";
+import { checkForUpdate } from "./update-check.js";
+import { reconstructAgentMarkdown, translateAgentToCopilot } from "./agent-utils.js";
 import { resolveRecipe, loadCustomPipelines } from "./pipeline-utils.js";
+import { generateDecisionPageHtml } from "./decision-page-template.js";
 // Mutable pipeline/instruction state — starts with bundled, merged with user at startup
 const PIPELINES = { ...BUNDLED_PIPELINES };
 const INSTRUCTIONS = { ...BUNDLED_INSTRUCTIONS };
@@ -236,171 +243,220 @@ async function ensureGitignored(cwd, filePath) {
     const separator = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
     await writeFile(gitignorePath, content + separator + entry + "\n", "utf-8");
 }
-if (process.argv.includes("--init")) {
-    // Guard: must be run from project root
+/**
+ * Core initialization logic shared by --init and --upgrade.
+ * Runs all scaffolding phases without calling process.exit().
+ */
+async function runInit(cwd) {
+    // ---- Phase 1: IDE Detection ----
+    const ideDetection = {
+        claude: true,
+        vscode: false,
+        cursor: false,
+        windsurf: false,
+    };
     try {
-        await stat(path.join(process.cwd(), "package.json"));
+        await stat(path.join(cwd, ".vscode"));
+        ideDetection.vscode = true;
     }
-    catch {
-        console.error("Error: No package.json found in current directory.\n" +
-            "--init must be run from your project root (the directory containing package.json).");
-        process.exit(1);
+    catch { }
+    try {
+        await stat(path.join(cwd, ".cursor"));
+        ideDetection.cursor = true;
     }
+    catch { }
+    if (!ideDetection.cursor && process.env.CURSOR_TRACE_DIR)
+        ideDetection.cursor = true;
     try {
-        const cwd = process.cwd();
-        // ---- Phase 1: IDE Detection ----
-        const ideDetection = {
-            claude: true,
-            vscode: false,
-            cursor: false,
-            windsurf: false,
-        };
+        await stat(path.join(cwd, ".windsurf"));
+        ideDetection.windsurf = true;
+    }
+    catch { }
+    if (!ideDetection.windsurf) {
         try {
-            await stat(path.join(cwd, ".vscode"));
-            ideDetection.vscode = true;
+            await stat(path.join(cwd, ".windsurfrules"));
+            ideDetection.windsurf = true;
         }
         catch { }
+    }
+    const detectedIDEs = Object.entries(ideDetection)
+        .filter(([, v]) => v)
+        .map(([k]) => k);
+    console.log(`Bridge API --init: detected IDEs: ${detectedIDEs.join(", ")}`);
+    // ---- Phase 2: Windsurf manual instructions ----
+    if (ideDetection.windsurf) {
+        const windsurfSnippet = JSON.stringify({ mcpServers: { "bridge-api": buildBridgeApiEntry(cwd) } }, null, 2);
+        console.log("\n⚠ Windsurf does not support project-local MCP configuration.\n" +
+            "Add the following to ~/.codeium/windsurf/mcp_config.json:\n\n" +
+            windsurfSnippet + "\n");
+    }
+    // ---- Phase 3: Config file handling ----
+    const configTargets = [
+        { path: ".mcp.json", topLevelKey: "mcpServers", shouldCreate: true },
+        { path: ".vscode/mcp.json", topLevelKey: "servers", shouldCreate: ideDetection.vscode },
+        { path: ".cursor/mcp.json", topLevelKey: "mcpServers", shouldCreate: ideDetection.cursor },
+    ];
+    const configActions = [];
+    let anyCreatedOrAdded = false;
+    for (const target of configTargets) {
+        const fullPath = path.join(cwd, target.path);
+        let fileExists = false;
         try {
-            await stat(path.join(cwd, ".cursor"));
-            ideDetection.cursor = true;
+            await stat(fullPath);
+            fileExists = true;
         }
         catch { }
-        if (!ideDetection.cursor && process.env.CURSOR_TRACE_DIR)
-            ideDetection.cursor = true;
-        try {
-            await stat(path.join(cwd, ".windsurf"));
-            ideDetection.windsurf = true;
+        if (!target.shouldCreate && !fileExists) {
+            configActions.push({ path: target.path, action: "skipped — IDE not detected" });
+            continue;
         }
-        catch { }
-        if (!ideDetection.windsurf) {
+        if (fileExists) {
+            // Read and parse existing file
+            const raw = await readFile(fullPath, "utf-8");
+            let parsed;
             try {
-                await stat(path.join(cwd, ".windsurfrules"));
-                ideDetection.windsurf = true;
+                parsed = JSON.parse(raw);
             }
-            catch { }
-        }
-        const detectedIDEs = Object.entries(ideDetection)
-            .filter(([, v]) => v)
-            .map(([k]) => k);
-        console.log(`Bridge API --init: detected IDEs: ${detectedIDEs.join(", ")}`);
-        // ---- Phase 2: Windsurf manual instructions ----
-        if (ideDetection.windsurf) {
-            const windsurfSnippet = JSON.stringify({ mcpServers: { "bridge-api": buildBridgeApiEntry(cwd) } }, null, 2);
-            console.log("\n⚠ Windsurf does not support project-local MCP configuration.\n" +
-                "Add the following to ~/.codeium/windsurf/mcp_config.json:\n\n" +
-                windsurfSnippet + "\n");
-        }
-        // ---- Phase 3: Config file handling ----
-        const configTargets = [
-            { path: ".mcp.json", topLevelKey: "mcpServers", shouldCreate: true },
-            { path: ".vscode/mcp.json", topLevelKey: "servers", shouldCreate: ideDetection.vscode },
-            { path: ".cursor/mcp.json", topLevelKey: "mcpServers", shouldCreate: ideDetection.cursor },
-        ];
-        const configActions = [];
-        let anyCreatedOrAdded = false;
-        for (const target of configTargets) {
-            const fullPath = path.join(cwd, target.path);
-            let fileExists = false;
-            try {
-                await stat(fullPath);
-                fileExists = true;
-            }
-            catch { }
-            if (!target.shouldCreate && !fileExists) {
-                configActions.push({ path: target.path, action: "skipped — IDE not detected" });
+            catch {
+                console.warn(`  ${target.path} skipped — invalid JSON format`);
+                configActions.push({ path: target.path, action: "skipped — invalid JSON" });
                 continue;
             }
-            if (fileExists) {
-                // Read and parse existing file
-                const raw = await readFile(fullPath, "utf-8");
-                let parsed;
-                try {
-                    parsed = JSON.parse(raw);
-                }
-                catch {
-                    console.warn(`  ${target.path} skipped — invalid JSON format`);
-                    configActions.push({ path: target.path, action: "skipped — invalid JSON" });
-                    continue;
-                }
-                const topLevel = parsed[target.topLevelKey];
-                if (topLevel && topLevel["bridge-api"]) {
-                    // Entry exists — update BAPI_PROJECT_ROOT only
-                    if (!topLevel["bridge-api"].env)
-                        topLevel["bridge-api"].env = {};
-                    topLevel["bridge-api"].env.BAPI_PROJECT_ROOT = cwd;
-                    await writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
-                    configActions.push({ path: target.path, action: "updated BAPI_PROJECT_ROOT" });
-                }
-                else {
-                    // Entry missing — add it, preserving existing content
-                    if (!parsed[target.topLevelKey])
-                        parsed[target.topLevelKey] = {};
-                    parsed[target.topLevelKey]["bridge-api"] = buildBridgeApiEntry(cwd);
-                    await writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
-                    configActions.push({ path: target.path, action: "added entry" });
-                    anyCreatedOrAdded = true;
-                }
+            const topLevel = parsed[target.topLevelKey];
+            if (topLevel && topLevel["bridge-api"]) {
+                // Entry exists — update BAPI_PROJECT_ROOT only
+                if (!topLevel["bridge-api"].env)
+                    topLevel["bridge-api"].env = {};
+                topLevel["bridge-api"].env.BAPI_PROJECT_ROOT = cwd;
+                await writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+                configActions.push({ path: target.path, action: "updated BAPI_PROJECT_ROOT" });
             }
             else {
-                // Create new file
-                await mkdir(path.dirname(fullPath), { recursive: true });
-                const content = { [target.topLevelKey]: { "bridge-api": buildBridgeApiEntry(cwd) } };
-                await writeFile(fullPath, JSON.stringify(content, null, 2) + "\n", "utf-8");
-                await ensureGitignored(cwd, target.path);
-                configActions.push({ path: target.path, action: "created" });
+                // Entry missing — add it, preserving existing content
+                if (!parsed[target.topLevelKey])
+                    parsed[target.topLevelKey] = {};
+                parsed[target.topLevelKey]["bridge-api"] = buildBridgeApiEntry(cwd);
+                await writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+                configActions.push({ path: target.path, action: "added entry" });
                 anyCreatedOrAdded = true;
             }
         }
-        console.log("\nMCP config files:");
-        for (const entry of configActions) {
-            console.log(`  ${entry.path}: ${entry.action}`);
+        else {
+            // Create new file
+            await mkdir(path.dirname(fullPath), { recursive: true });
+            const content = { [target.topLevelKey]: { "bridge-api": buildBridgeApiEntry(cwd) } };
+            await writeFile(fullPath, JSON.stringify(content, null, 2) + "\n", "utf-8");
+            await ensureGitignored(cwd, target.path);
+            configActions.push({ path: target.path, action: "created" });
+            anyCreatedOrAdded = true;
         }
-        // ---- Phase 4: Scaffold slash command directories ----
-        const commandDirs = [path.join(cwd, ".claude", "commands")];
-        if (ideDetection.cursor) {
-            commandDirs.push(path.join(cwd, ".cursor", "commands"));
+    }
+    console.log("\nMCP config files:");
+    for (const entry of configActions) {
+        console.log(`  ${entry.path}: ${entry.action}`);
+    }
+    // ---- Phase 4: Scaffold slash command directories ----
+    const commandDirs = [path.join(cwd, ".claude", "commands")];
+    if (ideDetection.cursor) {
+        commandDirs.push(path.join(cwd, ".cursor", "commands"));
+    }
+    const writtenFiles = new Set();
+    const skippedFiles = new Set();
+    const overwrittenFiles = new Set();
+    for (const dir of commandDirs) {
+        await mkdir(dir, { recursive: true });
+        for (const [filename, content] of Object.entries(COMMANDS)) {
+            const target = path.join(dir, filename);
+            try {
+                const existing = await readFile(target, "utf-8");
+                if (existing === content) {
+                    skippedFiles.add(filename);
+                    continue;
+                }
+                overwrittenFiles.add(filename);
+            }
+            catch { /* file doesn't exist */ }
+            await writeFile(target, content, "utf-8");
+            writtenFiles.add(filename);
+        }
+    }
+    // A file written in any directory takes priority over skipped
+    for (const f of writtenFiles)
+        skippedFiles.delete(f);
+    const total = Object.keys(COMMANDS).length;
+    const dirNames = commandDirs.map((d) => path.relative(cwd, d)).join(" and ");
+    console.log(`\nSlash commands: scaffolded ${total} commands into ${commandDirs.length} director${commandDirs.length === 1 ? "y" : "ies"}`);
+    if (writtenFiles.size > 0)
+        console.log(`  Written: ${writtenFiles.size}`);
+    if (overwrittenFiles.size > 0)
+        console.log(`  Overwritten (content changed): ${overwrittenFiles.size}`);
+    if (skippedFiles.size > 0)
+        console.log(`  Skipped (unchanged): ${skippedFiles.size}`);
+    console.log(`  ${dirNames}`);
+    // ---- Phase 5: Scaffold agent directories ----
+    const agentWritten = new Set();
+    const agentSkipped = new Set();
+    const agentOverwritten = new Set();
+    // Always scaffold to .claude/agents/
+    const claudeAgentsDir = path.join(cwd, ".claude", "agents");
+    await mkdir(claudeAgentsDir, { recursive: true });
+    for (const [key, agent] of Object.entries(AGENTS)) {
+        const filename = `${key}.md`;
+        const content = reconstructAgentMarkdown(agent.frontmatter, agent.body);
+        const target = path.join(claudeAgentsDir, filename);
+        try {
+            const existing = await readFile(target, "utf-8");
+            if (existing === content) {
+                agentSkipped.add(filename);
+                continue;
+            }
+            agentOverwritten.add(filename);
         }
-        const writtenFiles = new Set();
-        const skippedFiles = new Set();
-        const overwrittenFiles = new Set();
-        for (const dir of commandDirs) {
-            await mkdir(dir, { recursive: true });
-            for (const [filename, content] of Object.entries(COMMANDS)) {
-                const target = path.join(dir, filename);
-                try {
-                    const existing = await readFile(target, "utf-8");
-                    if (existing === content) {
-                        skippedFiles.add(filename);
-                        continue;
-                    }
-                    overwrittenFiles.add(filename);
+        catch { /* file doesn't exist */ }
+        await writeFile(target, content, "utf-8");
+        agentWritten.add(filename);
+    }
+    // Scaffold to .github/agents/ for VS Code / Copilot
+    if (ideDetection.vscode) {
+        const copilotAgentsDir = path.join(cwd, ".github", "agents");
+        await mkdir(copilotAgentsDir, { recursive: true });
+        for (const [key, agent] of Object.entries(AGENTS)) {
+            const filename = `${key}.agent.md`;
+            const content = translateAgentToCopilot(agent.frontmatter, agent.body);
+            const target = path.join(copilotAgentsDir, filename);
+            try {
+                const existing = await readFile(target, "utf-8");
+                if (existing === content) {
+                    agentSkipped.add(filename);
+                    continue;
                 }
-                catch { /* file doesn't exist */ }
-                await writeFile(target, content, "utf-8");
-                writtenFiles.add(filename);
+                agentOverwritten.add(filename);
             }
+            catch { /* file doesn't exist */ }
+            await writeFile(target, content, "utf-8");
+            agentWritten.add(filename);
         }
-        // A file written in any directory takes priority over skipped
-        for (const f of writtenFiles)
-            skippedFiles.delete(f);
-        const total = Object.keys(COMMANDS).length;
-        const dirNames = commandDirs.map((d) => path.relative(cwd, d)).join(" and ");
-        console.log(`\nSlash commands: scaffolded ${total} commands into ${commandDirs.length} director${commandDirs.length === 1 ? "y" : "ies"}`);
-        if (writtenFiles.size > 0)
-            console.log(`  Written: ${writtenFiles.size}`);
-        if (overwrittenFiles.size > 0)
-            console.log(`  Overwritten (content changed): ${overwrittenFiles.size}`);
-        if (skippedFiles.size > 0)
-            console.log(`  Skipped (unchanged): ${skippedFiles.size}`);
-        console.log(`  ${dirNames}`);
-        // ---- Phase 5: Scaffold custom pipeline directories ----
-        const pipelinesDir = path.resolve(cwd, process.env.BAPI_PIPELINES_DIR ?? ".bridge/pipelines");
-        const instrDir = path.join(path.dirname(pipelinesDir), "instructions");
-        await mkdir(pipelinesDir, { recursive: true });
-        await mkdir(instrDir, { recursive: true });
-        const readmePath = path.join(pipelinesDir, "README.md");
-        const examplePath = path.join(pipelinesDir, "example-pipeline.json");
-        const readmeContent = `# Custom Pipelines
+    }
+    // TODO: Add Cursor agent scaffolding when Cursor publishes a formal agent spec
+    // A file written in any directory takes priority over skipped
+    for (const f of agentWritten)
+        agentSkipped.delete(f);
+    const agentTotal = Object.keys(AGENTS).length;
+    console.log(`\nAgents: scaffolded ${agentTotal} agent${agentTotal === 1 ? "" : "s"}`);
+    if (agentWritten.size > 0)
+        console.log(`  Written: ${agentWritten.size}`);
+    if (agentOverwritten.size > 0)
+        console.log(`  Overwritten (content changed): ${agentOverwritten.size}`);
+    if (agentSkipped.size > 0)
+        console.log(`  Skipped (unchanged): ${agentSkipped.size}`);
+    // ---- Phase 6: Scaffold custom pipeline directories ----
+    const pipelinesDir = path.resolve(cwd, process.env.BAPI_PIPELINES_DIR ?? ".bridge/pipelines");
+    const instrDir = path.join(path.dirname(pipelinesDir), "instructions");
+    await mkdir(pipelinesDir, { recursive: true });
+    await mkdir(instrDir, { recursive: true });
+    const readmePath = path.join(pipelinesDir, "README.md");
+    const examplePath = path.join(pipelinesDir, "example-pipeline.json");
+    const readmeContent = `# Custom Pipelines
 
 Place custom pipeline JSON files in this directory. They will be loaded at
 server startup and available alongside the bundled pipelines.
@@ -462,65 +518,80 @@ automatically provided by the server.
 - \`"halt"\` (default) — stop the pipeline immediately on failure
 - \`"warn_and_continue"\` — log a warning and proceed to the next step
 `;
-        const exampleContent = JSON.stringify({
-            name: "Example Pipeline",
-            description: "A sample pipeline demonstrating all step types and features.",
-            variables: ["ticket_key"],
-            steps: [
-                {
-                    type: "mcp_call",
-                    tool: "get_ticket",
-                    params: { ticket_number: "{ticket_key}" },
-                    description: "Fetch the ticket details from Jira",
-                    on_error: "halt",
-                },
-                {
-                    type: "agent_task",
-                    instruction: "Read the ticket details above and summarize the key requirements in 3 bullet points.",
-                    description: "Summarize ticket requirements",
-                    on_error: "halt",
-                },
-                {
-                    type: "agent_task",
-                    instruction: "Search the codebase for files related to the ticket and list the top 5 most relevant files.",
-                    description: "Find relevant source files",
-                    on_error: "warn_and_continue",
-                },
-                {
-                    type: "mcp_call",
-                    tool: "add_comment",
-                    params: {
-                        ticket_number: "{ticket_key}",
-                        comment_text: "Pipeline analysis complete. See agent output for details.",
-                    },
-                    description: "Post a summary comment to the ticket",
-                    on_error: "warn_and_continue",
-                    requires_approval: true,
+    const exampleContent = JSON.stringify({
+        name: "Example Pipeline",
+        description: "A sample pipeline demonstrating all step types and features.",
+        variables: ["ticket_key"],
+        steps: [
+            {
+                type: "mcp_call",
+                tool: "get_ticket",
+                params: { ticket_number: "{ticket_key}" },
+                description: "Fetch the ticket details from Jira",
+                on_error: "halt",
+            },
+            {
+                type: "agent_task",
+                instruction: "Read the ticket details above and summarize the key requirements in 3 bullet points.",
+                description: "Summarize ticket requirements",
+                on_error: "halt",
+            },
+            {
+                type: "agent_task",
+                instruction: "Search the codebase for files related to the ticket and list the top 5 most relevant files.",
+                description: "Find relevant source files",
+                on_error: "warn_and_continue",
+            },
+            {
+                type: "mcp_call",
+                tool: "add_comment",
+                params: {
+                    ticket_number: "{ticket_key}",
+                    comment_text: "Pipeline analysis complete. See agent output for details.",
                 },
-            ],
-        }, null, 2) + "\n";
-        try {
-            await stat(readmePath);
-            console.log(`  ${path.relative(cwd, readmePath)} (skipped — already exists)`);
-        }
-        catch {
-            await writeFile(readmePath, readmeContent, "utf-8");
-            console.log(`  ${path.relative(cwd, readmePath)} (written)`);
-        }
-        try {
-            await stat(examplePath);
-            console.log(`  ${path.relative(cwd, examplePath)} (skipped — already exists)`);
-        }
-        catch {
-            await writeFile(examplePath, exampleContent, "utf-8");
-            console.log(`  ${path.relative(cwd, examplePath)} (written)`);
-        }
-        console.log(`  ${path.relative(cwd, instrDir)}/ (ensured)`);
-        // ---- Phase 6: Final summary ----
-        if (anyCreatedOrAdded) {
-            console.log("\nUpdate BAPI_API_KEY and BAPI_REPO_NAME in your config files — " +
-                "get these values from the Bridge API setup UI at https://bridgegpt-api.com");
-        }
+                description: "Post a summary comment to the ticket",
+                on_error: "warn_and_continue",
+                requires_approval: true,
+            },
+        ],
+    }, null, 2) + "\n";
+    try {
+        await stat(readmePath);
+        console.log(`  ${path.relative(cwd, readmePath)} (skipped — already exists)`);
+    }
+    catch {
+        await writeFile(readmePath, readmeContent, "utf-8");
+        console.log(`  ${path.relative(cwd, readmePath)} (written)`);
+    }
+    try {
+        await stat(examplePath);
+        console.log(`  ${path.relative(cwd, examplePath)} (skipped — already exists)`);
+    }
+    catch {
+        await writeFile(examplePath, exampleContent, "utf-8");
+        console.log(`  ${path.relative(cwd, examplePath)} (written)`);
+    }
+    console.log(`  ${path.relative(cwd, instrDir)}/ (ensured)`);
+    // ---- Phase 7: Final summary ----
+    if (anyCreatedOrAdded) {
+        console.log("\nUpdate BAPI_API_KEY and BAPI_REPO_NAME in your config files — " +
+            "get these values from the Bridge API setup UI at https://bridgegpt-api.com");
+    }
+}
+// ---------------------------------------------------------------------------
+// CLI: --init
+// ---------------------------------------------------------------------------
+if (process.argv.includes("--init")) {
+    try {
+        await stat(path.join(process.cwd(), "package.json"));
+    }
+    catch {
+        console.error("Error: No package.json found in current directory.\n" +
+            "--init must be run from your project root (the directory containing package.json).");
+        process.exit(1);
+    }
+    try {
+        await runInit(process.cwd());
         process.exit(0);
     }
     catch (err) {
@@ -530,6 +601,43 @@ automatically provided by the server.
     }
 }
 // ---------------------------------------------------------------------------
+// CLI: --upgrade
+// ---------------------------------------------------------------------------
+if (process.argv.includes("--upgrade")) {
+    try {
+        await stat(path.join(process.cwd(), "package.json"));
+    }
+    catch {
+        console.error("Error: No package.json found in current directory.\n" +
+            "--upgrade must be run from your project root (the directory containing package.json).");
+        process.exit(1);
+    }
+    try {
+        const cwd = process.cwd();
+        const oldVersion = VERSION;
+        console.log("Upgrading @bridge_gpt/mcp-server to latest...\n");
+        execSync("npm i @bridge_gpt/mcp-server@latest", { stdio: "inherit" });
+        // Read the newly installed version from node_modules
+        const require = createRequire(cwd + "/");
+        const newPkgPath = require.resolve("@bridge_gpt/mcp-server/package.json");
+        const newPkg = JSON.parse(await readFile(newPkgPath, "utf-8"));
+        const newVersion = newPkg.version;
+        console.log(`\n@bridge_gpt/mcp-server: ${oldVersion} -> ${newVersion}`);
+        if (oldVersion === newVersion) {
+            console.log("Already up-to-date.");
+        }
+        console.log("\nRefreshing scaffolded artifacts...\n");
+        await runInit(cwd);
+        console.log("\nUpgrade complete.");
+        process.exit(0);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Bridge API --upgrade failed: ${msg}`);
+        process.exit(1);
+    }
+}
+// ---------------------------------------------------------------------------
 // Server
 // ---------------------------------------------------------------------------
 const server = new McpServer({
@@ -553,8 +661,8 @@ server.registerTool("ping", {
     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. " +
+    description: "Retrieve project-specific coding standards, architecture guidelines, testing standards, code review standards, and project context (platform, version, project description) for the configured repository. " +
+        "Returns structured markdown with sections for project context, 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: {},
@@ -963,6 +1071,119 @@ server.registerTool("upload_attachment", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
+server.registerTool("list_attachments", {
+    description: "List attachments on a Jira ticket. " +
+        "Returns metadata (ID, filename, MIME type, size, created date) for each attachment. " +
+        "By default, AI-generated attachments are excluded. " +
+        "Use this to discover available attachments before downloading.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        include_ai_generated: z
+            .boolean()
+            .optional()
+            .describe("Include AI-generated attachments in the list (default: false)"),
+    },
+}, async ({ ticket_number, include_ai_generated }) => {
+    const params = { repo_name: REPO_NAME };
+    if (include_ai_generated) {
+        params.include_ai_generated = "true";
+    }
+    const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/attachments`, params);
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+const MAX_INLINE_TEXT_LENGTH = 50_000;
+server.registerTool("download_attachment", {
+    description: "Download an attachment from a Jira ticket and save it to disk. " +
+        "Specify either attachment_id or filename (not both). " +
+        "For text files, the content is returned inline (truncated at ~50KB) and also saved to disk. " +
+        "For binary files, the file is saved to disk and the path is returned. " +
+        "Default save location: {BAPI_DOCS_DIR}/attachments/{ticket_number}/{filename}.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        attachment_id: z
+            .string()
+            .optional()
+            .describe("Jira attachment ID. Mutually exclusive with filename."),
+        filename: z
+            .string()
+            .optional()
+            .describe("Attachment filename. If multiple exist, returns the most recent. Mutually exclusive with attachment_id."),
+        file_path: z
+            .string()
+            .optional()
+            .describe("Override the default save location. If omitted, saves to {BAPI_DOCS_DIR}/attachments/{ticket_number}/{filename}."),
+    },
+}, async ({ ticket_number, attachment_id, filename, file_path }) => {
+    if (!attachment_id && !filename) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        error: "VALIDATION_ERROR",
+                        message: "Provide either attachment_id or filename (at least one is required).",
+                    }),
+                }],
+        };
+    }
+    const params = { repo_name: REPO_NAME };
+    if (attachment_id)
+        params.attachment_id = attachment_id;
+    if (filename)
+        params.filename = filename;
+    const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/attachments/download`, params);
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    if (!resp.ok) {
+        const text = await handleResponse(resp);
+        return { content: [{ type: "text", text }] };
+    }
+    const body = await resp.json();
+    const serverFilename = body.filename;
+    const content = body.content;
+    const isText = body.is_text;
+    const mimeType = body.mime_type;
+    const size = body.size;
+    const safeFileName = path.basename(serverFilename);
+    const safeTicket = path.basename(ticket_number);
+    const savePath = file_path
+        ? file_path
+        : path.join(BAPI_DOCS_DIR, "attachments", safeTicket, safeFileName);
+    const resolvedSave = path.resolve(savePath);
+    const resolvedRoot = path.resolve(PROJECT_ROOT);
+    if (!resolvedSave.startsWith(resolvedRoot + path.sep) && resolvedSave !== resolvedRoot) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        error: "VALIDATION_ERROR",
+                        message: `Save path "${savePath}" is outside the project root. Refusing to write.`,
+                    }),
+                }],
+        };
+    }
+    await mkdir(path.dirname(resolvedSave), { recursive: true });
+    if (isText) {
+        await writeFile(resolvedSave, content, "utf-8");
+    }
+    else {
+        await writeFile(resolvedSave, Buffer.from(content, "base64"));
+    }
+    let resultText = `File saved to: ${resolvedSave}\nFilename: ${safeFileName}\nMIME type: ${mimeType}\nSize: ${size} bytes`;
+    if (isText) {
+        if (content.length > MAX_INLINE_TEXT_LENGTH) {
+            resultText += `\n\n${content.slice(0, MAX_INLINE_TEXT_LENGTH)}\n\n[Content truncated. Full content saved to ${resolvedSave}]`;
+        }
+        else {
+            resultText += `\n\n${content}`;
+        }
+    }
+    return { content: [{ type: "text", text: resultText }] };
+});
 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. " +
@@ -1457,11 +1678,13 @@ 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. " +
+        'Pass target_status as "auto" to trigger server-side status resolution via LLM — the server determines the correct ' +
+        "post-PR status automatically. If auto-resolve finds no match, returns status: skipped (not an error). " +
         "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)"),
+        target_status: z.string().optional().describe('Target status name to transition to (case-insensitive match). Pass "auto" to resolve the target status server-side via LLM agent.'),
         transition_id: z.string().optional().describe("Specific transition ID to execute (takes precedence over target_status)"),
     },
 }, async ({ ticket_number, target_status, transition_id }) => {
@@ -1511,6 +1734,7 @@ const VALID_CONFIG_FIELDS = [
     "unit_testing_instructions", "e2e_testing_instructions",
     "frontend_correctness_standards", "backend_correctness_standards",
     "template_correctness_standards", "style_correctness_standards",
+    "design_principles",
     "post_pr_target_status", "ci_check_config",
 ].join(", ");
 server.registerTool("list_config_fields", {
@@ -1955,6 +2179,117 @@ server.registerTool("get_pipeline_recipe", {
     }
 });
 // ---------------------------------------------------------------------------
+// generate_decision_page
+// ---------------------------------------------------------------------------
+server.registerTool("generate_decision_page", {
+    description: "Generate a local HTML decision page for capturing user decisions on ticket review findings. " +
+        "Renders recommendation-driven review decisions with custom options from resolution guide " +
+        "decision trees, plus confirmed improvements. The user opens the HTML file " +
+        "in a browser, makes selections, and copies the resulting JSON output back to the agent.",
+    inputSchema: {
+        ticket_key: z.string().describe("Jira ticket key, e.g. BAPI-123"),
+        actionable_items: z
+            .array(z.object({
+            id: z.string().min(1),
+            question: z.string().min(1),
+            context: z.string().min(1),
+            source: z.string().min(1).describe("Source reference from the evaluation, e.g. 'Clarifying Q3 (initial round)'"),
+            recommendation_index: z.number().int().min(0).describe("0-based index of the recommended option in the options array"),
+            options: z.array(z.string().min(1)).min(1).describe("Option labels from resolution guide decision tree branches. Values are auto-generated."),
+        }))
+            .optional()
+            .default([])
+            .describe("Actionable review decisions with option labels from resolution guide decision trees. 'None of these' auto-appended."),
+        clear_improvements: z
+            .array(z.object({
+            id: z.string().min(1),
+            title: z.string().min(1),
+            action: z.string().min(1),
+            confidence: z.string().min(1),
+            source: z.string().min(1).describe("Source reference from the evaluation"),
+        }))
+            .optional()
+            .default([])
+            .describe("Confirmed improvements displayed as informational list, not submitted."),
+    },
+}, async (input) => {
+    const validationError = (message) => ({
+        content: [{
+                type: "text",
+                text: JSON.stringify({ error: "VALIDATION_ERROR", status: 400, message }),
+            }],
+    });
+    // Validate ticket_key format (reject instead of silently sanitizing)
+    if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(input.ticket_key)) {
+        return validationError(`Invalid ticket_key "${input.ticket_key}": must start with a letter and contain only letters, digits, hyphens, or underscores.`);
+    }
+    // No-decisions fast path: return structured response without writing a file
+    if (input.actionable_items.length === 0) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        status: "no_decisions_needed",
+                        ticket_key: input.ticket_key,
+                        clear_improvements_count: input.clear_improvements.length,
+                    }),
+                }],
+        };
+    }
+    // Validate actionable_items
+    const seenIds = new Set();
+    for (const item of input.actionable_items) {
+        if (seenIds.has(item.id)) {
+            return validationError(`Duplicate actionable_items id: "${item.id}"`);
+        }
+        seenIds.add(item.id);
+        if (item.recommendation_index >= item.options.length) {
+            return validationError(`Item "${item.id}": recommendation_index ${item.recommendation_index} is out of bounds (${item.options.length} options).`);
+        }
+        const noneLabel = item.options.find((label) => label.toLowerCase() === "none of these");
+        if (noneLabel) {
+            return validationError(`Item "${item.id}": option label "${noneLabel}" is reserved and auto-appended by the tool.`);
+        }
+    }
+    // Read design assets and base64-encode for embedding
+    const assetsDir = path.join(PROJECT_ROOT, "design-assets");
+    const fontsDir = path.join(PROJECT_ROOT, "public", "fonts");
+    let faviconBase64 = "";
+    let logoBase64 = "";
+    try {
+        const faviconBuf = await readFile(path.join(assetsDir, "favicon", "favicon-32x32.png"));
+        faviconBase64 = faviconBuf.toString("base64");
+    }
+    catch { /* favicon optional */ }
+    try {
+        const logoBuf = await readFile(path.join(assetsDir, "just-logo-rough-draft.png"));
+        logoBase64 = logoBuf.toString("base64");
+    }
+    catch { /* logo optional */ }
+    // Compute relative path from output dir to fonts dir
+    const docsPath = getDocsPath("review");
+    const fontsRelPath = path.relative(docsPath, fontsDir);
+    const html = generateDecisionPageHtml(input, {
+        faviconBase64,
+        logoBase64,
+        fontsRelPath,
+    });
+    const filePath = path.join(docsPath, `${input.ticket_key}-decisions.html`);
+    await mkdir(docsPath, { recursive: true });
+    await writeFile(filePath, html, "utf-8");
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    status: "decision_page_generated",
+                    file_path: filePath,
+                    actionable_items_count: input.actionable_items.length,
+                    clear_improvements_count: input.clear_improvements.length,
+                }),
+            }],
+    };
+});
+// ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
 // Load custom user pipelines before accepting connections
@@ -1971,3 +2306,15 @@ userPipelineKeys = customResult.userPipelineKeys;
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error("Bridge API MCP server running on stdio");
+// Fire-and-forget update check — delay to let MCP client attach listeners
+(async () => {
+    await new Promise((r) => setTimeout(r, 2000));
+    const result = await checkForUpdate();
+    if (result?.updateAvailable) {
+        server.server.sendLoggingMessage({
+            level: "notice",
+            logger: "bridge-api",
+            data: `Update available: @bridge_gpt/mcp-server ${result.currentVersion} -> ${result.latestVersion}. Run: npx -y @bridge_gpt/mcp-server --upgrade`,
+        });
+    }
+})().catch(() => { });