rebar-mcp 2.0.0

package/src/tools/knowledge.ts

@@ -0,0 +1,162 @@
+/**
+ * Tier 2: Knowledge Base Tools
+ * rebar_create_knowledge, rebar_create_adr
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as path from "node:path";
+import {
+  CreateKnowledgeInputSchema,
+  CreateADRInputSchema,
+} from "../schemas/scaffolding.js";
+import {
+  atomicWrite,
+  ensureDir,
+  fileExists,
+  listFiles,
+} from "../services/file-ops.js";
+import type { ToolResult } from "../types.js";
+
+function makeResult(text: string, isError = false): ToolResult {
+  return {
+    content: [{ type: "text", text }],
+    ...(isError ? { isError: true } : {}),
+  };
+}
+
+export function registerKnowledgeTools(server: McpServer): void {
+  // ─── rebar_create_knowledge ──────────────────────────────────────
+  server.registerTool(
+    "rebar_create_knowledge",
+    {
+      title: "Create Knowledge Document",
+      description:
+        "[Rebar] Adds a reference document to .claude/docs/ that Claude Code can use as context. " +
+        "Use this for ADRs, runbooks, API specs, data schemas, and style guides.\n\n" +
+        "Knowledge documents give Claude deep domain context — the kind of information " +
+        "that turns generic AI suggestions into expert-level guidance specific to your system.\n\n" +
+        "Categories:\n" +
+        "• adr: Architecture Decision Records\n" +
+        "• runbook: Operational procedures\n" +
+        "• api: API documentation and contracts\n" +
+        "• schema: Data model definitions\n" +
+        "• style: Code style guides and conventions\n\n" +
+        "Examples:\n" +
+        "  rebar_create_knowledge({ title: 'Payment Processing Flow', category: 'api', content: '## Overview\\nPayments go through 3 stages...', tags: ['payments', 'stripe'] })\n" +
+        "  rebar_create_knowledge({ title: 'Incident Response', category: 'runbook', content: '## When PagerDuty fires...', tags: ['ops', 'oncall'] })\n\n" +
+        "Returns: Document location, category, and tags.\n" +
+        "Error: If document with same title already exists.",
+      inputSchema: CreateKnowledgeInputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      const { title, category, content, tags } = args;
+      const docsDir = path.join(process.cwd(), ".claude", "docs");
+      const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/(^-|-$)/g, "");
+      const filePath = path.join(docsDir, category, `${slug}.md`);
+
+      try {
+        if (await fileExists(filePath)) {
+          return makeResult(
+            `Document "${title}" already exists at ${filePath}\n\n` +
+            `Options:\n` +
+            `• Use a different title\n` +
+            `• Remove the existing document and try again`,
+            true
+          );
+        }
+
+        await ensureDir(path.join(docsDir, category));
+
+        const now = new Date().toISOString().split("T")[0];
+        const tagsLine = tags && tags.length > 0 ? `tags: [${tags.join(", ")}]\n` : "";
+        const doc =
+          `---\ntitle: ${title}\ncategory: ${category}\ndate: ${now}\n${tagsLine}---\n\n# ${title}\n\n${content}\n`;
+
+        await atomicWrite(filePath, doc);
+
+        return makeResult(
+          `Knowledge document created: ${title}\n\n` +
+          `Location: ${filePath}\n` +
+          `Category: ${category}\n` +
+          `Tags: ${tags && tags.length > 0 ? tags.join(", ") : "(none)"}\n\n` +
+          `Claude Code will use this as context when working in this project.`
+        );
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        return makeResult(`Failed to create knowledge document: ${message}`, true);
+      }
+    }
+  );
+
+  // ─── rebar_create_adr ────────────────────────────────────────────
+  server.registerTool(
+    "rebar_create_adr",
+    {
+      title: "Create ADR",
+      description:
+        "[Rebar] Generates an Architecture Decision Record following the standard ADR template. " +
+        "ADRs are the most valuable knowledge documents for AI — they explain WHY " +
+        "architectural decisions were made, which prevents Claude from suggesting " +
+        "approaches that were already considered and rejected.\n\n" +
+        "Auto-numbers ADRs sequentially (0001, 0002, etc.).\n\n" +
+        "Examples:\n" +
+        "  rebar_create_adr({ title: 'Use PostgreSQL over MongoDB', status: 'accepted', context: 'We need ACID transactions for payment processing...', decision: 'Use PostgreSQL with Prisma ORM...', consequences: 'Must manage migrations, but get strong consistency...' })\n" +
+        "  rebar_create_adr({ title: 'Adopt tRPC for API layer', status: 'proposed', context: 'REST endpoints lack type safety across client/server boundary...', decision: 'Replace REST with tRPC...', consequences: 'Tight coupling to TypeScript, but eliminates entire class of bugs...' })\n\n" +
+        "Returns: ADR number, file path, status.",
+      inputSchema: CreateADRInputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      const { title, status, context, decision, consequences } = args;
+      const adrDir = path.join(process.cwd(), ".claude", "docs", "adr");
+      await ensureDir(adrDir);
+
+      const existing = await listFiles(adrDir, ".md");
+      const nextNum = existing.length + 1;
+      const paddedNum = String(nextNum).padStart(4, "0");
+      const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/(^-|-$)/g, "");
+      const fileName = `${paddedNum}-${slug}.md`;
+      const filePath = path.join(adrDir, fileName);
+
+      try {
+        const now = new Date().toISOString().split("T")[0];
+        const content =
+          `# ADR ${paddedNum}: ${title}\n\n` +
+          `**Status:** ${status}\n` +
+          `**Date:** ${now}\n\n` +
+          `## Context\n\n${context}\n\n` +
+          `## Decision\n\n${decision}\n\n` +
+          `## Consequences\n\n${consequences}\n`;
+
+        await atomicWrite(filePath, content);
+
+        return makeResult(
+          `ADR created: #${paddedNum}\n\n` +
+          `Title: ${title}\n` +
+          `Status: ${status}\n` +
+          `Location: ${filePath}\n\n` +
+          `Claude will reference this ADR when making related architectural decisions.`
+        );
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        return makeResult(`Failed to create ADR: ${message}`, true);
+      }
+    }
+  );
+}