openclew 0.2.1 → 0.3.0

package/lib/mcp-server.js

@@ -0,0 +1,313 @@
+/**
+ * openclew MCP server — Model Context Protocol over stdio.
+ *
+ * Exposes openclew docs as MCP tools so AI agents (Claude Code, Cursor, etc.)
+ * can search and read project documentation natively.
+ *
+ * Tools:
+ *   - search_docs(query)           Search docs by keyword (L1/metadata)
+ *   - read_doc(path, level?)       Read a doc at specified level (L1/L2/L3/full)
+ *   - list_docs(kind?)             List all docs with L1 metadata
+ *
+ * Protocol: MCP 2024-11-05 over stdio (JSON-RPC line-delimited)
+ * Zero dependencies — Node 16+ standard library only.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+const { searchDocs, collectDocs, parseFile } = require("./search");
+
+const PROJECT_ROOT = process.cwd();
+const DOC_DIR = path.join(PROJECT_ROOT, "doc");
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+function ocVersion() {
+  try {
+    return require(path.join(__dirname, "..", "package.json")).version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function extractLevel(content, level) {
+  if (level === "full") return content;
+
+  const markers = {
+    L1: [/<!--\s*L1_START\s*-->/, /<!--\s*L1_END\s*-->/],
+    L2: [/<!--\s*L2_START\s*-->/, /<!--\s*L2_END\s*-->/],
+    L3: [/<!--\s*L3_START\s*-->/, /<!--\s*L3_END\s*-->/],
+  };
+
+  const key = level.toUpperCase();
+  if (!markers[key]) return content;
+
+  const [startRe, endRe] = markers[key];
+  const startMatch = content.match(startRe);
+  const endMatch = content.match(endRe);
+  if (!startMatch || !endMatch) return `No ${key} block found in this document.`;
+
+  const startIdx = startMatch.index + startMatch[0].length;
+  const endIdx = endMatch.index;
+  return content.slice(startIdx, endIdx).trim();
+}
+
+// ── MCP Tool implementations ────────────────────────────────────────
+
+function toolSearchDocs(params) {
+  const query = params.query;
+  if (!query) return { error: "Missing required parameter: query" };
+  if (!fs.existsSync(DOC_DIR)) return { error: "No doc/ directory found." };
+
+  const results = searchDocs(DOC_DIR, query);
+  return results.map((r) => ({
+    path: path.relative(PROJECT_ROOT, r.filepath),
+    kind: r.kind,
+    subject: r.meta.subject || r.filename,
+    doc_brief: r.meta.doc_brief || "",
+    status: r.meta.status || "",
+    category: r.meta.category || "",
+    score: r.score,
+  }));
+}
+
+function toolReadDoc(params) {
+  const docPath = params.path;
+  if (!docPath) return { error: "Missing required parameter: path" };
+
+  const absPath = path.resolve(PROJECT_ROOT, docPath);
+  // Security: ensure path is within project
+  if (!absPath.startsWith(PROJECT_ROOT)) return { error: "Path outside project." };
+  if (!fs.existsSync(absPath)) return { error: `File not found: ${docPath}` };
+
+  const content = fs.readFileSync(absPath, "utf-8");
+  const level = params.level || "L2";
+
+  return {
+    path: docPath,
+    level: level,
+    content: extractLevel(content, level),
+  };
+}
+
+function toolListDocs(params) {
+  if (!fs.existsSync(DOC_DIR)) return { error: "No doc/ directory found." };
+
+  const docs = collectDocs(DOC_DIR);
+  const kind = params.kind; // "refdoc", "log", or undefined (all)
+
+  return docs
+    .filter((d) => !kind || d.kind === kind)
+    .map((d) => ({
+      path: path.relative(PROJECT_ROOT, d.filepath),
+      kind: d.kind,
+      subject: d.meta.subject || d.filename,
+      doc_brief: d.meta.doc_brief || "",
+      status: d.meta.status || "",
+      category: d.meta.category || "",
+    }));
+}
+
+// ── MCP Protocol ────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: "search_docs",
+    description:
+      "Search project documentation by keyword. Searches subject, doc_brief, category, keywords, type, and status fields. Returns results sorted by relevance.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search query (space-separated terms)",
+        },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "read_doc",
+    description:
+      "Read a project document at a specified level. L1 = subject + brief (~40 tokens). L2 = summary + key points. L3 = full technical details. full = entire file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Relative path to the document (e.g. doc/_ARCHITECTURE.md)",
+        },
+        level: {
+          type: "string",
+          enum: ["L1", "L2", "L3", "full"],
+          description: "Level of detail to return (default: L2)",
+        },
+      },
+      required: ["path"],
+    },
+  },
+  {
+    name: "list_docs",
+    description:
+      "List all project documents with their L1 metadata (subject, brief, status, category).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kind: {
+          type: "string",
+          enum: ["refdoc", "log"],
+          description: "Filter by document type. Omit to list all.",
+        },
+      },
+    },
+  },
+];
+
+const TOOL_HANDLERS = {
+  search_docs: toolSearchDocs,
+  read_doc: toolReadDoc,
+  list_docs: toolListDocs,
+};
+
+function handleMessage(msg) {
+  const { method, id, params } = msg;
+
+  switch (method) {
+    case "initialize":
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: "2024-11-05",
+          capabilities: { tools: {} },
+          serverInfo: {
+            name: "openclew",
+            version: ocVersion(),
+          },
+        },
+      };
+
+    case "notifications/initialized":
+      return null; // No response for notifications
+
+    case "tools/list":
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: { tools: TOOLS },
+      };
+
+    case "tools/call": {
+      const toolName = params && params.name;
+      const handler = TOOL_HANDLERS[toolName];
+      if (!handler) {
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32601, message: `Unknown tool: ${toolName}` },
+        };
+      }
+
+      const toolArgs = params.arguments || {};
+      const result = handler(toolArgs);
+
+      // If result has an error field, return as tool error content
+      if (result && result.error) {
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: result.error }],
+            isError: true,
+          },
+        };
+      }
+
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          content: [
+            {
+              type: "text",
+              text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
+            },
+          ],
+        },
+      };
+    }
+
+    default:
+      if (id !== undefined) {
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32601, message: `Method not found: ${method}` },
+        };
+      }
+      return null; // Ignore unknown notifications
+  }
+}
+
+// ── stdio transport ─────────────────────────────────────────────────
+
+function run() {
+  // Check if running as CLI help
+  const args = process.argv.slice(2);
+  const cmdIndex = args.indexOf("mcp");
+  const extraArgs = cmdIndex >= 0 ? args.slice(cmdIndex + 1) : args.slice(1);
+
+  if (extraArgs.includes("--help") || extraArgs.includes("-h")) {
+    console.log("openclew MCP server — Model Context Protocol over stdio");
+    console.log("");
+    console.log("Usage: openclew mcp");
+    console.log("");
+    console.log("Starts an MCP server on stdin/stdout for AI agent integration.");
+    console.log("Configure in your AI tool's MCP settings:");
+    console.log("");
+    console.log('  { "command": "npx", "args": ["openclew", "mcp"] }');
+    console.log("");
+    console.log("Tools exposed:");
+    console.log("  search_docs(query)       Search docs by keyword");
+    console.log("  read_doc(path, level?)   Read doc at L1/L2/L3/full");
+    console.log("  list_docs(kind?)         List all docs with L1 metadata");
+    process.exit(0);
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, terminal: false });
+
+  rl.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      const err = {
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32700, message: "Parse error" },
+      };
+      process.stdout.write(JSON.stringify(err) + "\n");
+      return;
+    }
+
+    const response = handleMessage(msg);
+    if (response) {
+      process.stdout.write(JSON.stringify(response) + "\n");
+    }
+  });
+
+  rl.on("close", () => process.exit(0));
+}
+
+// Export for tests
+module.exports = { handleMessage, extractLevel, TOOLS };
+
+// Run as CLI (invoked via dispatcher or directly)
+const calledAsMcp = process.argv.includes("mcp");
+if (require.main === module || calledAsMcp) {
+  run();
+}

package/lib/new-doc.js

@@ -8,13 +8,21 @@ const { refdocContent, slugify } = require("./templates");
 const { readConfig } = require("./config");
 
 const args = process.argv.slice(2);
-// Remove "new" command from args
-const cmdIndex = args.indexOf("new");
-const titleArgs = cmdIndex >= 0 ? args.slice(cmdIndex + 1) : args.slice(1);
+// Support both "add ref <title>" and legacy "new <title>"
+const refIndex = args.indexOf("ref");
+const newIndex = args.indexOf("new");
+let titleArgs;
+if (refIndex >= 0) {
+  titleArgs = args.slice(refIndex + 1);
+} else if (newIndex >= 0) {
+  titleArgs = args.slice(newIndex + 1);
+} else {
+  titleArgs = args.slice(1);
+}
 const title = titleArgs.join(" ");
 
 if (!title) {
-  console.error('Usage: openclew new "Title of the document"');
+  console.error('Usage: openclew add ref "Title of the document"');
   process.exit(1);
 }
 

package/lib/new-log.js

@@ -8,13 +8,13 @@ const { logContent, slugifyLog, today } = require("./templates");
 const { readConfig } = require("./config");
 
 const args = process.argv.slice(2);
-// Remove "log" command from args
-const cmdIndex = args.indexOf("log");
-const titleArgs = cmdIndex >= 0 ? args.slice(cmdIndex + 1) : args.slice(1);
+// Support both "add log <title>" and legacy "log <title>"
+const logIndex = args.lastIndexOf("log");
+const titleArgs = logIndex >= 0 ? args.slice(logIndex + 1) : args.slice(1);
 const title = titleArgs.join(" ");
 
 if (!title) {
-  console.error('Usage: openclew log "Title of the log"');
+  console.error('Usage: openclew add log "Title of the log"');
   process.exit(1);
 }
 

package/lib/search.js

@@ -0,0 +1,242 @@
+/**
+ * openclew search <query> — search docs by keyword.
+ *
+ * Searches metadata line (category, keywords, type, status) and
+ * L1 fields (subject, doc_brief) across all refdocs and logs.
+ * Returns results sorted by relevance score.
+ *
+ * Zero dependencies — Node 16+ standard library only.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ── Parsers (JS port of generate-index.py) ─────────────────────────
+
+function parseMetadataLine(content) {
+  const meta = {};
+  const firstLine = content.split("\n", 1)[0].trim();
+  if (!firstLine.startsWith("openclew@")) return meta;
+
+  const parts = firstLine.split(" · ");
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (trimmed.startsWith("openclew@")) {
+      meta.version = trimmed.split("@")[1];
+      continue;
+    }
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx > 0) {
+      const key = trimmed.slice(0, colonIdx).trim().toLowerCase();
+      const value = trimmed.slice(colonIdx + 1).trim();
+      meta[key] = value;
+    }
+  }
+  return meta;
+}
+
+function parseL1(content) {
+  const meta = {};
+  const match = content.match(
+    /<!--\s*L1_START\s*-->([\s\S]+?)<!--\s*L1_END\s*-->/
+  );
+  if (!match) return meta;
+
+  const block = match[1];
+  const subjectMatch = block.match(/\*\*subject:\*\*\s*(.+)/);
+  if (subjectMatch) meta.subject = subjectMatch[1].trim();
+
+  const briefMatch = block.match(/\*\*doc_brief:\*\*\s*(.+)/);
+  if (briefMatch) meta.doc_brief = briefMatch[1].trim();
+
+  return meta;
+}
+
+function parseL1Legacy(content) {
+  const meta = {};
+  const match = content.match(
+    /<!--\s*L1_START\s*-->([\s\S]+?)<!--\s*L1_END\s*-->/
+  );
+  if (!match) return meta;
+
+  for (const line of match[1].split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx > 0) {
+      const key = trimmed.slice(0, colonIdx).trim().toLowerCase();
+      const value = trimmed.slice(colonIdx + 1).trim();
+      meta[key] = value;
+    }
+  }
+  return meta;
+}
+
+function parseFile(filepath) {
+  let content;
+  try {
+    content = fs.readFileSync(filepath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const metaLine = parseMetadataLine(content);
+  const l1 = parseL1(content);
+
+  if (l1.subject) {
+    return { ...metaLine, ...l1 };
+  }
+
+  const legacy = parseL1Legacy(content);
+  if (Object.keys(legacy).length) {
+    return { ...metaLine, ...legacy };
+  }
+
+  return null;
+}
+
+// ── Collector ───────────────────────────────────────────────────────
+
+function collectDocs(docDir) {
+  const docs = [];
+
+  // Refdocs: doc/_*.md
+  if (fs.existsSync(docDir)) {
+    for (const entry of fs.readdirSync(docDir).sort()) {
+      if (entry.startsWith("_") && entry.endsWith(".md") && entry !== "_INDEX.md") {
+        const filepath = path.join(docDir, entry);
+        const meta = parseFile(filepath);
+        if (meta) docs.push({ filepath, filename: entry, kind: "refdoc", meta });
+      }
+    }
+  }
+
+  // Logs: doc/log/*.md
+  const logDir = path.join(docDir, "log");
+  if (fs.existsSync(logDir)) {
+    for (const entry of fs.readdirSync(logDir).sort().reverse()) {
+      if (entry.endsWith(".md")) {
+        const filepath = path.join(logDir, entry);
+        const meta = parseFile(filepath);
+        if (meta) docs.push({ filepath, filename: entry, kind: "log", meta });
+      }
+    }
+  }
+
+  return docs;
+}
+
+// ── Search engine ───────────────────────────────────────────────────
+
+/**
+ * Score a document against query terms.
+ * Higher score = more relevant.
+ *
+ * Weights: subject (3), doc_brief (2), keywords (2), category (1.5), type (1), status (0.5)
+ */
+function scoreDoc(doc, queryTerms) {
+  const fields = [
+    { value: doc.meta.subject || "", weight: 3 },
+    { value: doc.meta.doc_brief || "", weight: 2 },
+    { value: doc.meta.keywords || "", weight: 2 },
+    { value: doc.meta.category || "", weight: 1.5 },
+    { value: doc.meta.type || "", weight: 1 },
+    { value: doc.meta.status || "", weight: 0.5 },
+  ];
+
+  let score = 0;
+  for (const term of queryTerms) {
+    const termLower = term.toLowerCase();
+    for (const field of fields) {
+      const valueLower = field.value.toLowerCase();
+      if (valueLower.includes(termLower)) {
+        score += field.weight;
+        // Bonus for exact word match (not substring)
+        if (new RegExp(`\\b${termLower.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(field.value)) {
+          score += field.weight * 0.5;
+        }
+      }
+    }
+  }
+  return score;
+}
+
+/**
+ * Search docs matching query. Returns sorted results.
+ *
+ * @param {string} docDir - Path to doc/ directory
+ * @param {string} query - Search query (space-separated terms, AND logic)
+ * @returns {Array<{filepath, filename, kind, meta, score}>}
+ */
+function searchDocs(docDir, query) {
+  const docs = collectDocs(docDir);
+  const queryTerms = query.trim().split(/\s+/).filter(Boolean);
+  if (!queryTerms.length) return [];
+
+  const results = [];
+  for (const doc of docs) {
+    const score = scoreDoc(doc, queryTerms);
+    if (score > 0) {
+      results.push({ ...doc, score });
+    }
+  }
+
+  results.sort((a, b) => b.score - a.score);
+  return results;
+}
+
+// ── CLI runner ──────────────────────────────────────────────────────
+
+function run() {
+  const args = process.argv.slice(2);
+  const cmdIndex = args.indexOf("search");
+  const queryArgs = cmdIndex >= 0 ? args.slice(cmdIndex + 1) : args.slice(1);
+  const query = queryArgs.join(" ");
+
+  if (!query) {
+    console.error('Usage: openclew search <query>');
+    console.error('');
+    console.error('Examples:');
+    console.error('  openclew search auth          # find docs about authentication');
+    console.error('  openclew search "API design"   # multi-word search');
+    process.exit(1);
+  }
+
+  const projectRoot = process.cwd();
+  const docDir = path.join(projectRoot, "doc");
+  if (!fs.existsSync(docDir)) {
+    console.error("No doc/ directory found. Run 'openclew init' first.");
+    process.exit(1);
+  }
+
+  const results = searchDocs(docDir, query);
+
+  if (!results.length) {
+    console.log(`No docs matching "${query}".`);
+    process.exit(0);
+  }
+
+  console.log(`Found ${results.length} doc${results.length > 1 ? "s" : ""} matching "${query}":\n`);
+
+  for (const r of results) {
+    const relPath = path.relative(projectRoot, r.filepath);
+    const icon = r.kind === "refdoc" ? "📘" : "📝";
+    const subject = r.meta.subject || r.filename;
+    const brief = r.meta.doc_brief || "";
+    const status = r.meta.status ? ` [${r.meta.status}]` : "";
+
+    console.log(`${icon} ${subject}${status}`);
+    console.log(`   ${relPath}`);
+    if (brief) console.log(`   ${brief}`);
+    console.log("");
+  }
+}
+
+// Export for MCP server + tests
+module.exports = { searchDocs, collectDocs, parseFile, parseMetadataLine, parseL1, parseL1Legacy };
+
+// Run as CLI (invoked via dispatcher or directly)
+const calledAsSearch = process.argv.includes("search");
+if (require.main === module || calledAsSearch) {
+  run();
+}