@arcbridge/mcp-server 0.2.1 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @arcbridge/mcp-server
 
-MCP server for ArcBridge — exposes 33 architecture tools to AI coding agents via the [Model Context Protocol](https://modelcontextprotocol.io).
+MCP server for ArcBridge — exposes 34 architecture tools to AI coding agents via the [Model Context Protocol](https://modelcontextprotocol.io).
 
 ## Install
 
@@ -10,7 +10,7 @@ npm install -g @arcbridge/mcp-server
 
 ## Setup
 
-Add to your project's `.mcp.json`:
+**Claude Code** — add to your project's `.mcp.json`:
 
 ```json
 {
@@ -23,7 +23,15 @@ Add to your project's `.mcp.json`:
 }
 ```
 
-Restart your AI agent (Claude Code, etc.) and approve the MCP server when prompted.
+**Codex CLI** — add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.arcbridge]
+command = "npx"
+args = ["-y", "@arcbridge/mcp-server"]
+```
+
+Restart your AI agent and approve the MCP server when prompted.
 
 ## Tools
 
@@ -81,6 +89,7 @@ Restart your AI agent (Claude Code, etc.) and approve the MCP server when prompt
 | `arcbridge_get_open_questions` | Unresolved architectural questions and risks |
 | `arcbridge_propose_arc42_update` | Generate arc42 update proposals from code changes |
 | `arcbridge_get_practice_review` | 5-dimension review: architecture, security, testing, docs, complexity |
+| `arcbridge_update_arc42_section` | Read or update any arc42 markdown section (frontmatter preserved) |
 
 ### Roles & Sync
 

package/dist/index.js

@@ -31,7 +31,9 @@ import {
   generateDatabase,
   generateSyncFiles,
   indexProject,
-  loadConfig
+  loadConfig,
+  QualityCategorySchema,
+  QUALITY_PRIORITIES_DESCRIPTION
 } from "@arcbridge/core";
 import { getAdapter } from "@arcbridge/adapters";
 function registerInitProject(server, ctx) {
@@ -44,7 +46,7 @@ function registerInitProject(server, ctx) {
         "Project template: nextjs-app-router (Next.js with App Router, SSR/SSG), react-vite (React SPA with Vite, client-only), api-service (Node.js API with Express/Fastify/Hono), dotnet-webapi (ASP.NET Core Web API, C#), unity-game (Unity game project, C#, code-heavy)"
       ),
       features: z.array(z.enum(["auth", "database", "api"])).default([]).describe("Features to scaffold"),
-      quality_priorities: z.array(z.string()).default(["security", "performance", "accessibility", "maintainability"]).describe("Quality priorities in order"),
+      quality_priorities: z.array(QualityCategorySchema).default(["security", "performance", "accessibility", "maintainability"]).describe(QUALITY_PRIORITIES_DESCRIPTION),
       platforms: z.array(z.string()).default(["claude"]).describe("Target platforms for agent config generation"),
       target_dir: z.string().describe("Absolute path to the target project directory"),
       spec: z.string().optional().describe(
@@ -568,14 +570,14 @@ function registerGetBuildingBlock(server, ctx) {
 
 // src/tools/get-quality-scenarios.ts
 import { z as z5 } from "zod";
-import { QualityCategorySchema, QualityPrioritySchema, QualityScenarioStatusSchema } from "@arcbridge/core";
+import { QualityCategorySchema as QualityCategorySchema2, QualityPrioritySchema, QualityScenarioStatusSchema } from "@arcbridge/core";
 function registerGetQualityScenarios(server, ctx) {
   server.tool(
     "arcbridge_get_quality_scenarios",
     "Get quality scenarios, optionally filtered by category. Shows scenario details, linked code/tests, and current status.",
     {
       target_dir: z5.string().describe("Absolute path to the project directory"),
-      category: QualityCategorySchema.optional().describe("Filter by category"),
+      category: QualityCategorySchema2.optional().describe("Filter by category"),
       status: QualityScenarioStatusSchema.optional().describe("Filter by status"),
       priority: QualityPrioritySchema.optional().describe("Filter by priority (must/should/could)")
     },
@@ -756,7 +758,7 @@ import { refreshFromDocs as refreshFromDocs3 } from "@arcbridge/core";
 function registerGetCurrentTasks(server, ctx) {
   server.tool(
     "arcbridge_get_current_tasks",
-    "Get tasks for the current in-progress phase, with their building blocks, quality scenarios, and acceptance criteria.",
+    "Get tasks for the current phase (in-progress, or first planned if none is in-progress), with their building blocks, quality scenarios, and acceptance criteria.",
     {
       target_dir: z7.string().describe("Absolute path to the project directory"),
       status: z7.enum(["todo", "in-progress", "done", "blocked"]).optional().describe("Filter tasks by status")
@@ -765,15 +767,20 @@ function registerGetCurrentTasks(server, ctx) {
       const db = ensureDb(ctx, params.target_dir);
       if (!db) return notInitialized();
       refreshFromDocs3(db, params.target_dir);
-      const currentPhase = db.prepare(
+      let currentPhase = db.prepare(
         "SELECT id, name FROM phases WHERE status = 'in-progress' ORDER BY phase_number LIMIT 1"
       ).get();
+      if (!currentPhase) {
+        currentPhase = db.prepare(
+          "SELECT id, name FROM phases WHERE status = 'planned' ORDER BY phase_number LIMIT 1"
+        ).get();
+      }
       if (!currentPhase) {
         return {
           content: [
             {
               type: "text",
-              text: "No phase is currently in-progress. Use `arcbridge_get_phase_plan` to see all phases."
+              text: "No active or planned phases found. Use `arcbridge_get_phase_plan` to see all phases."
             }
           ]
         };
@@ -4395,6 +4402,103 @@ You can commit this file to preserve the activity record in git.`
   );
 }
 
+// src/tools/update-arc42-section.ts
+import { z as z34 } from "zod";
+import { join as join4 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+function splitFrontmatter(raw) {
+  if (!raw.startsWith("---")) {
+    return { frontmatterBlock: "", body: raw };
+  }
+  const endIndex = raw.indexOf("\n---", 3);
+  if (endIndex < 0) {
+    return { frontmatterBlock: "", body: raw };
+  }
+  const fmEnd = endIndex + 4;
+  return {
+    frontmatterBlock: raw.slice(0, fmEnd),
+    body: raw.slice(fmEnd).replace(/^\n/, "")
+  };
+}
+var VALID_SECTIONS = [
+  "01-introduction",
+  "02-constraints",
+  "03-context",
+  "04-solution-strategy",
+  "06-runtime-views",
+  "07-deployment",
+  "08-crosscutting",
+  "11-risks-debt"
+];
+var SECTION_LABELS = {
+  "01-introduction": "Introduction & Goals",
+  "02-constraints": "Architecture Constraints",
+  "03-context": "Context & Scope",
+  "04-solution-strategy": "Solution Strategy",
+  "06-runtime-views": "Runtime Views",
+  "07-deployment": "Deployment View",
+  "08-crosscutting": "Crosscutting Concepts",
+  "11-risks-debt": "Risks & Technical Debt"
+};
+function registerUpdateArc42Section(server, ctx) {
+  server.tool(
+    "arcbridge_update_arc42_section",
+    "Read or update an arc42 documentation section. Omit `content` to read the current section. Provide `content` to replace the markdown body (frontmatter is preserved automatically). Use this for sections without dedicated tools: introduction, constraints, context, solution strategy, runtime views, deployment, crosscutting concepts, risks & debt. For building blocks use `arcbridge_get_building_blocks`, for quality scenarios use `arcbridge_get_quality_scenarios`.",
+    {
+      target_dir: z34.string().describe("Absolute path to the project directory"),
+      section: z34.enum(VALID_SECTIONS).describe(
+        "Arc42 section to read or update: " + VALID_SECTIONS.map((s) => `${s} (${SECTION_LABELS[s]})`).join(", ")
+      ),
+      content: z34.string().optional().describe(
+        "New markdown content for the section body. Omit to read the current content. Frontmatter is preserved automatically \u2014 only provide the markdown body."
+      )
+    },
+    async (params) => {
+      const db = ensureDb(ctx, params.target_dir);
+      if (!db) return notInitialized();
+      const filePath = join4(
+        params.target_dir,
+        ".arcbridge",
+        "arc42",
+        `${params.section}.md`
+      );
+      if (!existsSync4(filePath)) {
+        return textResult(
+          `Section file \`${params.section}.md\` not found. Run \`arcbridge_init_project\` first.`
+        );
+      }
+      if (params.content === void 0) {
+        const raw2 = readFileSync2(filePath, "utf-8");
+        const { body } = splitFrontmatter(raw2);
+        const label2 = SECTION_LABELS[params.section];
+        const trimmedBody = body.trim();
+        const startsWithHeading = /^#\s+/.test(trimmedBody);
+        const outputLines = [];
+        if (!startsWithHeading) {
+          outputLines.push(`# ${label2}`, "");
+        }
+        outputLines.push(
+          `**File:** \`.arcbridge/arc42/${params.section}.md\``,
+          "",
+          trimmedBody
+        );
+        return textResult(outputLines.join("\n"));
+      }
+      const raw = readFileSync2(filePath, "utf-8");
+      const { frontmatterBlock } = splitFrontmatter(raw);
+      const updated = frontmatterBlock ? `${frontmatterBlock}
+${params.content}
+` : `${params.content}
+`;
+      writeFileSync2(filePath, updated, "utf-8");
+      const label = SECTION_LABELS[params.section];
+      return textResult(
+        `Updated **${label}** (\`${params.section}.md\`). Frontmatter preserved.`
+      );
+    }
+  );
+}
+
 // src/server.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -4434,6 +4538,7 @@ function createArcBridgeServer() {
   registerVerifyScenarios(server, ctx);
   registerUpdateScenarioStatus(server, ctx);
   registerRunRoleCheck(server, ctx);
+  registerUpdateArc42Section(server, ctx);
   registerRecordActivity(server, ctx);
   registerGetMetrics(server, ctx);
   registerExportMetrics(server, ctx);