@ksm0709/context 0.0.34 → 0.0.36

package/dist/mcp.js

@@ -32638,8 +32638,556 @@ class StdioServerTransport {
 }
 
 // src/lib/mcp-server.ts
+import * as fs2 from "fs/promises";
+import * as path2 from "path";
+
+// src/lib/knowledge-search.ts
 import * as fs from "fs/promises";
 import * as path from "path";
+var SEARCH_DIRECTORIES = ["docs", ".context"];
+var FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+var HEADING_REGEX = /^#\s+(.+)$/m;
+var WIKI_LINK_REGEX = /\[\[([^[\]]+?)\]\]/g;
+var SNIPPET_LENGTH = 160;
+var KNOWLEDGE_READ_MAX_LENGTH = 32 * 1024;
+var RELATED_NOTES_SECTION_MAX_LENGTH = 6 * 1024;
+var STOP_WORDS = new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "but",
+  "by",
+  "for",
+  "from",
+  "how",
+  "i",
+  "in",
+  "is",
+  "it",
+  "of",
+  "on",
+  "or",
+  "that",
+  "the",
+  "this",
+  "to",
+  "what",
+  "when",
+  "where",
+  "which",
+  "with",
+  "\uAC00",
+  "\uB294",
+  "\uB3C4",
+  "\uB97C",
+  "\uC5D0",
+  "\uC640",
+  "\uC744",
+  "\uC758",
+  "\uC774",
+  "\uC880",
+  "\uD560",
+  "\uB54C"
+]);
+function normalizeKnowledgePath(filePath) {
+  const normalizedPath = path.normalize(filePath);
+  if (normalizedPath.startsWith("..") || path.isAbsolute(normalizedPath)) {
+    throw new Error("Invalid path: Directory traversal is not allowed");
+  }
+  const relativePath = toPosixPath(normalizedPath);
+  if (!SEARCH_DIRECTORIES.some((dir) => relativePath.startsWith(`${dir}/`))) {
+    throw new Error("Invalid path: Only files in docs/ or .context/ are allowed");
+  }
+  return relativePath;
+}
+async function loadKnowledgeNotes(rootDir) {
+  const notes = [];
+  for (const dir of SEARCH_DIRECTORIES) {
+    const fullDirPath = path.resolve(rootDir, dir);
+    try {
+      const files = await fs.readdir(fullDirPath, { recursive: true });
+      for (const file2 of files) {
+        if (typeof file2 !== "string" || !file2.endsWith(".md")) {
+          continue;
+        }
+        const fullPath = path.join(fullDirPath, file2);
+        const content = await fs.readFile(fullPath, "utf-8");
+        const relativePath = toPosixPath(path.relative(rootDir, fullPath));
+        notes.push(parseKnowledgeNote(relativePath, content));
+      }
+    } catch (error45) {
+      if (error45.code !== "ENOENT") {
+        throw error45;
+      }
+    }
+  }
+  return notes.sort((left, right) => left.file.localeCompare(right.file));
+}
+function buildSearchKnowledgeResponse(results) {
+  if (results.length === 0) {
+    return "No matches found.";
+  }
+  return [
+    ...results.map((result, index) => [
+      `Result ${index + 1}`,
+      `Path: ${result.file}`,
+      `Title: ${result.title}`,
+      `Description: ${result.description || "(none)"}`,
+      `Tags: ${result.tags.length > 0 ? result.tags.join(", ") : "(none)"}`,
+      `Score: ${result.score}`,
+      `Match reasons: ${result.matchReasons.length > 0 ? result.matchReasons.join(", ") : "(general overlap)"}`,
+      `Snippet: ${result.snippet}`
+    ].join(`
+`)),
+    "Open a relevant note with read_knowledge to inspect the full content and linked-note metadata."
+  ].join(`
+
+`);
+}
+function formatRelatedNotesSection(relatedNotes) {
+  if (relatedNotes.resolved.length === 0 && relatedNotes.unresolved.length === 0) {
+    return "";
+  }
+  const lines = ["## Related Notes", ""];
+  if (relatedNotes.resolved.length > 0) {
+    for (const note of relatedNotes.resolved) {
+      lines.push(`- Title: ${note.title}`);
+      lines.push(`  Path: ${note.file}`);
+      lines.push(`  Description: ${note.description || "(none)"}`);
+      lines.push(`  Tags: ${note.tags.length > 0 ? note.tags.join(", ") : "(none)"}`);
+    }
+    lines.push("");
+  }
+  if (relatedNotes.unresolved.length > 0) {
+    lines.push(`Unresolved links: ${relatedNotes.unresolved.join(", ")}`);
+    lines.push("");
+  }
+  lines.push("If one of these related notes looks relevant, open it with `read_knowledge` to continue exploring.");
+  return lines.join(`
+`).trim();
+}
+function buildReadKnowledgeResponse(content, relatedNotesSection) {
+  if (!relatedNotesSection) {
+    return content.length > KNOWLEDGE_READ_MAX_LENGTH ? `${content.substring(0, KNOWLEDGE_READ_MAX_LENGTH)}
+
+... (content truncated due to size limit)` : content;
+  }
+  const truncatedRelatedSection = relatedNotesSection.length > RELATED_NOTES_SECTION_MAX_LENGTH ? `${relatedNotesSection.slice(0, RELATED_NOTES_SECTION_MAX_LENGTH)}
+... (related notes truncated)` : relatedNotesSection;
+  const reservedLength = truncatedRelatedSection.length + 2;
+  const mainBudget = Math.max(0, KNOWLEDGE_READ_MAX_LENGTH - reservedLength);
+  const truncatedMainContent = content.length > mainBudget ? `${content.substring(0, mainBudget)}
+
+... (content truncated due to size limit)` : content;
+  return `${truncatedMainContent}
+
+${truncatedRelatedSection}`;
+}
+function parseKnowledgeNote(file2, content) {
+  const { body, metadata } = parseFrontmatter(content);
+  const title = resolveTitle(file2, body, metadata);
+  const description = resolveDescription(body, metadata);
+  const tags = resolveTags(metadata);
+  return {
+    body,
+    content,
+    description,
+    file: file2,
+    links: extractWikiLinks(content),
+    pathStem: normalizeSearchText(stripExtension(file2)),
+    tags,
+    title
+  };
+}
+function searchKnowledgeNotes(notes, query, limit) {
+  const normalizedQuery = normalizeSearchText(query);
+  const queryTokens = tokenizeQuery(query);
+  if (normalizedQuery.length === 0 && queryTokens.length === 0) {
+    return [];
+  }
+  return notes.map((note) => scoreKnowledgeNote(note, normalizedQuery, queryTokens)).filter((match) => match.score > 0).sort((left, right) => {
+    if (right.score !== left.score) {
+      return right.score - left.score;
+    }
+    return left.file.localeCompare(right.file);
+  }).slice(0, limit);
+}
+function resolveRelatedKnowledgeLinks(notes, currentFile, links) {
+  const lookup = new Map;
+  for (const note of notes) {
+    const keys = [normalizeSearchText(note.title), note.pathStem];
+    for (const key of keys) {
+      if (!key || lookup.has(key)) {
+        continue;
+      }
+      lookup.set(key, note);
+    }
+  }
+  const resolved = [];
+  const unresolved = [];
+  const seenFiles = new Set;
+  for (const rawLink of links) {
+    const normalizedLink = normalizeSearchText(rawLink);
+    const note = lookup.get(normalizedLink);
+    if (!note || note.file === currentFile || seenFiles.has(note.file)) {
+      if (!note) {
+        unresolved.push(rawLink);
+      }
+      continue;
+    }
+    resolved.push(note);
+    seenFiles.add(note.file);
+  }
+  return { resolved, unresolved };
+}
+function scoreKnowledgeNote(note, normalizedQuery, queryTokens) {
+  const matchReasons = [];
+  let score = 0;
+  score += scoreTextField({
+    exactPhraseWeight: 80,
+    label: "title",
+    matchReasons,
+    queryTokens,
+    text: note.title,
+    tokenWeight: 24,
+    normalizedQuery
+  });
+  score += scoreTags(note.tags, queryTokens, matchReasons);
+  score += scoreTextField({
+    exactPhraseWeight: 40,
+    label: "description",
+    matchReasons,
+    queryTokens,
+    text: note.description,
+    tokenWeight: 14,
+    normalizedQuery
+  });
+  score += scoreTextField({
+    exactPhraseWeight: 20,
+    label: "body",
+    matchReasons,
+    queryTokens,
+    text: note.body,
+    tokenWeight: 6,
+    normalizedQuery
+  });
+  score += scoreTextField({
+    exactPhraseWeight: 12,
+    label: "path",
+    matchReasons,
+    queryTokens,
+    text: note.file,
+    tokenWeight: 4,
+    normalizedQuery
+  });
+  return {
+    description: note.description,
+    file: note.file,
+    matchReasons,
+    score,
+    snippet: buildSnippet(note, queryTokens),
+    tags: note.tags,
+    title: note.title
+  };
+}
+function scoreTextField(params) {
+  const normalizedText = normalizeSearchText(params.text);
+  if (!normalizedText) {
+    return 0;
+  }
+  const tokenSet = new Set(tokenizeQuery(params.text));
+  const matchedTokenCount = params.queryTokens.filter((token) => tokenSet.has(token)).length;
+  let score = matchedTokenCount * params.tokenWeight;
+  if (matchedTokenCount > 0) {
+    params.matchReasons.push(`${params.label}:${matchedTokenCount}`);
+  }
+  if (params.normalizedQuery && normalizedText.includes(params.normalizedQuery)) {
+    score += params.exactPhraseWeight;
+    params.matchReasons.push(`${params.label}:phrase`);
+  }
+  return score;
+}
+function scoreTags(tags, queryTokens, matchReasons) {
+  const normalizedTags = tags.map((tag) => normalizeSearchText(tag)).filter(Boolean);
+  let score = 0;
+  let matched = 0;
+  for (const token of queryTokens) {
+    const hasMatch = normalizedTags.some((tag) => tag === token || tag.includes(token));
+    if (!hasMatch) {
+      continue;
+    }
+    matched += 1;
+    score += 20;
+  }
+  if (matched > 0) {
+    matchReasons.push(`tags:${matched}`);
+  }
+  return score;
+}
+function buildSnippet(note, queryTokens) {
+  const preferredSources = [note.description, note.body, note.title];
+  for (const source of preferredSources) {
+    const snippet = buildSnippetFromText(source, queryTokens);
+    if (snippet) {
+      return snippet;
+    }
+  }
+  return truncateInlineText(note.title || note.file, SNIPPET_LENGTH);
+}
+function buildSnippetFromText(text, queryTokens) {
+  const inlineText = text.replace(/\s+/g, " ").trim();
+  if (!inlineText) {
+    return "";
+  }
+  const lowerText = inlineText.toLowerCase();
+  let firstIndex = Number.POSITIVE_INFINITY;
+  for (const token of queryTokens) {
+    const matchIndex = lowerText.indexOf(token.toLowerCase());
+    if (matchIndex !== -1 && matchIndex < firstIndex) {
+      firstIndex = matchIndex;
+    }
+  }
+  if (!Number.isFinite(firstIndex)) {
+    return truncateInlineText(inlineText, SNIPPET_LENGTH);
+  }
+  const start = Math.max(0, firstIndex - Math.floor(SNIPPET_LENGTH / 3));
+  const end = Math.min(inlineText.length, start + SNIPPET_LENGTH);
+  let snippet = inlineText.slice(start, end);
+  if (start > 0) {
+    snippet = `...${snippet}`;
+  }
+  if (end < inlineText.length) {
+    snippet = `${snippet}...`;
+  }
+  return snippet;
+}
+function truncateInlineText(text, maxLength) {
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return `${text.slice(0, maxLength - 3)}...`;
+}
+function parseFrontmatter(content) {
+  const match = FRONTMATTER_REGEX.exec(content);
+  if (!match) {
+    return {
+      body: content,
+      metadata: {}
+    };
+  }
+  return {
+    body: content.slice(match[0].length),
+    metadata: parseFrontmatterBlock(match[1])
+  };
+}
+function parseFrontmatterBlock(block) {
+  const metadata = {};
+  const lines = block.split(/\r?\n/);
+  let currentArrayKey = null;
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd();
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    if (currentArrayKey && /^\s*-\s+/.test(line)) {
+      const arrayValue = normalizeScalarValue(trimmed.replace(/^-+\s*/, ""));
+      const existing = metadata[currentArrayKey];
+      if (Array.isArray(existing)) {
+        existing.push(arrayValue);
+      } else {
+        metadata[currentArrayKey] = [arrayValue];
+      }
+      continue;
+    }
+    currentArrayKey = null;
+    const separatorIndex = line.indexOf(":");
+    if (separatorIndex === -1) {
+      continue;
+    }
+    const key = line.slice(0, separatorIndex).trim().toLowerCase();
+    const value = line.slice(separatorIndex + 1).trim();
+    if (!value) {
+      currentArrayKey = key;
+      metadata[key] = [];
+      continue;
+    }
+    if (value.startsWith("[") && value.endsWith("]")) {
+      metadata[key] = value.slice(1, -1).split(",").map((item) => normalizeScalarValue(item)).filter(Boolean);
+      continue;
+    }
+    metadata[key] = normalizeScalarValue(value);
+  }
+  return metadata;
+}
+function resolveTitle(file2, body, metadata) {
+  const frontmatterTitle = getMetadataString(metadata, "title");
+  if (frontmatterTitle) {
+    return frontmatterTitle;
+  }
+  const headingMatch = HEADING_REGEX.exec(body);
+  if (headingMatch) {
+    return headingMatch[1].trim();
+  }
+  return humanizeSlug(path.basename(file2, ".md"));
+}
+function resolveDescription(body, metadata) {
+  const frontmatterDescription = getMetadataString(metadata, "description") ?? getMetadataString(metadata, "summary");
+  if (frontmatterDescription) {
+    return frontmatterDescription;
+  }
+  const lines = body.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#"));
+  const paragraph = lines.find((line) => !line.startsWith("- ") && !line.startsWith("* "));
+  return paragraph ? truncateInlineText(paragraph, 200) : "";
+}
+function resolveTags(metadata) {
+  const tags = metadata.tags;
+  if (Array.isArray(tags)) {
+    return tags.map((tag) => tag.trim()).filter(Boolean);
+  }
+  if (typeof tags === "string") {
+    return tags.split(",").map((tag) => tag.trim()).filter(Boolean);
+  }
+  return [];
+}
+function getMetadataString(metadata, key) {
+  const value = metadata[key];
+  if (typeof value === "string" && value.trim()) {
+    return value.trim();
+  }
+  return null;
+}
+function normalizeScalarValue(value) {
+  return value.replace(/^['"]|['"]$/g, "").trim();
+}
+function extractWikiLinks(content) {
+  const links = new Set;
+  for (const match of content.matchAll(WIKI_LINK_REGEX)) {
+    const rawTarget = match[1].split("|")[0].split("#")[0].trim();
+    if (rawTarget) {
+      links.add(rawTarget);
+    }
+  }
+  return [...links];
+}
+function tokenizeQuery(text) {
+  const rawTokens = text.toLowerCase().split(/[^\p{L}\p{N}]+/u).map((token) => token.trim()).filter(Boolean);
+  const filteredTokens = rawTokens.filter((token) => !STOP_WORDS.has(token));
+  return [...new Set(filteredTokens.length > 0 ? filteredTokens : rawTokens)];
+}
+function normalizeSearchText(text) {
+  return text.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function toPosixPath(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
+function humanizeSlug(slug) {
+  const words = slug.split(/[-_]+/).filter(Boolean).map((word) => word.length > 0 ? word[0].toUpperCase() + word.slice(1) : word);
+  return words.join(" ") || slug;
+}
+function stripExtension(file2) {
+  return file2.endsWith(".md") ? file2.slice(0, -3) : file2;
+}
+
+// src/lib/knowledge-note-template-validation.ts
+var HEADING_REGEX2 = /^(#{1,3})\s+(.+)$/;
+var ADDITIONAL_FORBIDDEN_SNIPPETS = ["[\uC81C\uBAA9]", "[\uAC04\uB2E8\uD55C \uC124\uBA85]", "TODO"];
+var RELATED_NOTES_TITLES = ["\uAD00\uB828 \uB178\uD2B8", "Related Notes"];
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function parseMarkdownHeadings(content) {
+  const lines = content.split(`
+`);
+  return lines.flatMap((line, index) => {
+    const match = line.match(HEADING_REGEX2);
+    if (!match) {
+      return [];
+    }
+    return [
+      {
+        level: match[1].length,
+        line: index,
+        raw: line.trim(),
+        text: match[2].trim()
+      }
+    ];
+  });
+}
+function buildHeadingPattern(templateText) {
+  const escaped = escapeRegExp(templateText).replace(/\\\[[^\]]+\\\]/g, "(.+)");
+  return new RegExp(`^${escaped}$`);
+}
+function headingMatches(template, candidate) {
+  if (template.level !== candidate.level) {
+    return false;
+  }
+  return buildHeadingPattern(template.text).test(candidate.text);
+}
+function collectForbiddenSnippets(templateContent) {
+  const snippets = new Set(ADDITIONAL_FORBIDDEN_SNIPPETS);
+  for (const line of templateContent.split(`
+`)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const headingMatch = trimmed.match(HEADING_REGEX2);
+    if (headingMatch) {
+      if (trimmed.includes("[") || trimmed.includes("...") || trimmed.includes("TODO")) {
+        snippets.add(trimmed);
+      }
+      continue;
+    }
+    snippets.add(trimmed);
+  }
+  return [...snippets];
+}
+function isRelatedNotesHeading(heading) {
+  return RELATED_NOTES_TITLES.includes(heading.text);
+}
+function validateTemplatedKnowledgeNoteContent(templateContent, content) {
+  const templateHeadings = parseMarkdownHeadings(templateContent);
+  const contentHeadings = parseMarkdownHeadings(content);
+  const contentLines = content.split(`
+`);
+  const errors3 = [];
+  const matchedHeadings = [];
+  let searchStart = 0;
+  for (const templateHeading of templateHeadings) {
+    const matchIndex = contentHeadings.findIndex((candidate, index) => index >= searchStart && headingMatches(templateHeading, candidate));
+    if (matchIndex === -1) {
+      errors3.push(`Missing required heading: ${templateHeading.raw}`);
+      continue;
+    }
+    matchedHeadings.push(contentHeadings[matchIndex]);
+    searchStart = matchIndex + 1;
+  }
+  for (const forbiddenSnippet of collectForbiddenSnippets(templateContent)) {
+    if (content.includes(forbiddenSnippet)) {
+      errors3.push(`Template placeholder was not replaced: ${forbiddenSnippet}`);
+    }
+  }
+  matchedHeadings.forEach((heading, index) => {
+    const nextHeadingLine = matchedHeadings[index + 1]?.line ?? contentLines.length;
+    const sectionBody = contentLines.slice(heading.line + 1, nextHeadingLine).join(`
+`).trim();
+    if (heading.level > 1 && !sectionBody) {
+      errors3.push(`Section is empty: ${heading.raw}`);
+      return;
+    }
+    if (isRelatedNotesHeading(heading) && !/\[\[[^[\]]+\]\]/.test(sectionBody)) {
+      errors3.push(`Related notes section must include at least one wikilink: ${heading.raw}`);
+    }
+  });
+  return { errors: errors3 };
+}
+
+// src/lib/mcp-server.ts
 function startMcpServer() {
   const server = new McpServer({
     name: "context-mcp-server",
@@ -32648,62 +33196,20 @@ function startMcpServer() {
     capabilities: {}
   });
   server.registerTool("search_knowledge", {
-    description: "Search .md files in docs/ and .context/ directories for a keyword or regex",
+    description: "Search knowledge notes in docs/ and .context/ using weighted metadata/body matching and ranked results",
     inputSchema: {
-      query: exports_external.string().describe("The keyword or regex to search for"),
+      query: exports_external.string().describe("The search query to match against titles, descriptions, tags, and note content"),
       limit: exports_external.number().optional().describe("Maximum number of results to return (default: 50)")
     }
   }, async ({ query, limit = 50 }) => {
-    const searchDirs = ["docs", ".context"];
-    const results = [];
-    const maxResults = limit;
-    const snippetLength = 100;
     try {
-      const regex = new RegExp(query, "i");
-      for (const dir of searchDirs) {
-        const fullDirPath = path.resolve(process.cwd(), dir);
-        try {
-          const files = await fs.readdir(fullDirPath, { recursive: true });
-          for (const file2 of files) {
-            if (typeof file2 === "string" && file2.endsWith(".md")) {
-              const filePath = path.join(fullDirPath, file2);
-              const content = await fs.readFile(filePath, "utf-8");
-              const match = regex.exec(content);
-              if (match) {
-                const start = Math.max(0, match.index - snippetLength / 2);
-                const end = Math.min(content.length, match.index + match[0].length + snippetLength / 2);
-                let snippet = content.substring(start, end).replace(/\n/g, " ");
-                if (start > 0)
-                  snippet = "..." + snippet;
-                if (end < content.length)
-                  snippet = snippet + "...";
-                results.push({
-                  file: path.relative(process.cwd(), filePath),
-                  snippet
-                });
-                if (results.length >= maxResults) {
-                  break;
-                }
-              }
-            }
-          }
-        } catch (err) {
-          if (err.code !== "ENOENT") {
-            console.error(`Error reading directory ${dir}:`, err);
-          }
-        }
-        if (results.length >= maxResults) {
-          break;
-        }
-      }
+      const notes = await loadKnowledgeNotes(process.cwd());
+      const results = searchKnowledgeNotes(notes, query, limit);
       return {
         content: [
           {
             type: "text",
-            text: results.length > 0 ? results.map((r) => `File: ${r.file}
-Snippet: ${r.snippet}`).join(`
-
-`) : "No matches found."
+            text: buildSearchKnowledgeResponse(results)
           }
         ]
       };
@@ -32720,25 +33226,19 @@ Snippet: ${r.snippet}`).join(`
     }
   });
   server.registerTool("read_knowledge", {
-    description: "Read the content of a specific .md file in docs/ or .context/ directories",
+    description: "Read a specific knowledge note and append linked-note metadata to help agents explore related notes",
     inputSchema: {
       path: exports_external.string().describe("The relative path to the file (e.g., docs/architecture.md)")
     }
   }, async ({ path: filePath }) => {
     try {
-      const normalizedPath = path.normalize(filePath);
-      if (normalizedPath.startsWith("..") || path.isAbsolute(normalizedPath)) {
-        throw new Error("Invalid path: Directory traversal is not allowed");
-      }
-      if (!normalizedPath.startsWith("docs/") && !normalizedPath.startsWith(".context/")) {
-        throw new Error("Invalid path: Only files in docs/ or .context/ are allowed");
-      }
-      const fullPath = path.resolve(process.cwd(), normalizedPath);
-      const content = await fs.readFile(fullPath, "utf-8");
-      const MAX_LENGTH = 32 * 1024;
-      const truncatedContent = content.length > MAX_LENGTH ? content.substring(0, MAX_LENGTH) + `
-
-... (content truncated due to size limit)` : content;
+      const normalizedPath = normalizeKnowledgePath(filePath);
+      const fullPath = path2.resolve(process.cwd(), normalizedPath);
+      const notes = await loadKnowledgeNotes(process.cwd());
+      const note = notes.find((entry) => entry.file === normalizedPath);
+      const content = note?.content ?? await fs2.readFile(fullPath, "utf-8");
+      const relatedNotesSection = note ? formatRelatedNotesSection(resolveRelatedKnowledgeLinks(notes, note.file, note.links)) : "";
+      const truncatedContent = buildReadKnowledgeResponse(content, relatedNotesSection);
       return {
         content: [
           {
@@ -32775,15 +33275,15 @@ Snippet: ${r.snippet}`).join(`
       const seconds = String(date6.getSeconds()).padStart(2, "0");
       const dateString = `${year}-${month}-${day}`;
       const timestamp = `[${year}-${month}-${day} ${hours}:${minutes}:${seconds}]`;
-      const dirPath = path.resolve(process.cwd(), ".context/memory/daily");
-      const filePath = path.join(dirPath, `${dateString}.md`);
-      await fs.mkdir(dirPath, { recursive: true });
+      const dirPath = path2.resolve(process.cwd(), ".context/memory/daily");
+      const filePath = path2.join(dirPath, `${dateString}.md`);
+      await fs2.mkdir(dirPath, { recursive: true });
       let textToAppend = content;
       if (!content.startsWith(`[${year}-${month}-${day}`)) {
         textToAppend = `${timestamp} ${content}`;
       }
       try {
-        const existingContent = await fs.readFile(filePath, "utf-8");
+        const existingContent = await fs2.readFile(filePath, "utf-8");
         if (existingContent.length > 0 && !existingContent.endsWith(`
 `)) {
           textToAppend = `
@@ -32795,7 +33295,7 @@ Snippet: ${r.snippet}`).join(`
         textToAppend += `
 `;
       }
-      await fs.appendFile(filePath, textToAppend, "utf-8");
+      await fs2.appendFile(filePath, textToAppend, "utf-8");
       return {
         content: [
           {
@@ -32834,10 +33334,10 @@ Snippet: ${r.snippet}`).join(`
       const month = String(date6.getMonth() + 1).padStart(2, "0");
       const day = String(date6.getDate()).padStart(2, "0");
       const dateString = `${year}-${month}-${day}`;
-      const filePath = path.resolve(process.cwd(), ".context/memory/daily", `${dateString}.md`);
+      const filePath = path2.resolve(process.cwd(), ".context/memory/daily", `${dateString}.md`);
       let fileContent;
       try {
-        fileContent = await fs.readFile(filePath, "utf-8");
+        fileContent = await fs2.readFile(filePath, "utf-8");
       } catch (err) {
         if (err.code === "ENOENT") {
           return {
@@ -32877,35 +33377,65 @@ Snippet: ${r.snippet}`).join(`
     }
   });
   server.registerTool("create_knowledge_note", {
-    description: "Create a new Zettelkasten knowledge note with frontmatter and wikilinks. You can optionally use a template by providing the `template` parameter. Available templates: adr (Architecture Decision Records), pattern (Design patterns), bug (Bug reports and analysis), gotcha (Pitfalls and gotchas), decision (General decisions), context (General context and background), runbook (Procedures and runbooks), insight (Insights and learnings).",
+    description: "Create a new Zettelkasten knowledge note with frontmatter and wikilinks. When you provide `template`, first read `.context/templates/<template>.md` and pass fully completed markdown in `content`. Available templates: adr (Architecture Decision Records), pattern (Design patterns), bug (Bug reports and analysis), gotcha (Pitfalls and gotchas), decision (General decisions), context (General context and background), runbook (Procedures and runbooks), insight (Insights and learnings).",
     inputSchema: {
       title: exports_external.string().describe("The title of the note"),
-      content: exports_external.string().describe("The main content of the note"),
-      tags: exports_external.array(exports_external.string()).optional().describe("Optional tags for the note"),
-      linked_notes: exports_external.array(exports_external.string()).optional().describe("Optional list of related note titles to link to"),
-      template: exports_external.enum(["adr", "pattern", "bug", "gotcha", "decision", "context", "runbook", "insight"]).optional().describe("Optional template to use for the note")
+      content: exports_external.string().describe("The main content of the note. When `template` is set, this must be the complete markdown document that already follows the template."),
+      tags: exports_external.array(exports_external.string()).optional().describe("Optional tags for the note. Not supported when `template` is set."),
+      linked_notes: exports_external.array(exports_external.string()).optional().describe("Optional list of related note titles to link to. Not supported when `template` is set; include related notes directly in the markdown content instead."),
+      template: exports_external.enum(["adr", "pattern", "bug", "gotcha", "decision", "context", "runbook", "insight"]).optional().describe("Optional template to validate against. Read the template file first and pass fully completed markdown in `content`.")
     }
   }, async ({ title, content, tags, linked_notes, template }) => {
     try {
       const filename = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "") + ".md";
-      const dirPath = path.resolve(process.cwd(), ".context/memory");
-      const filePath = path.join(dirPath, filename);
-      await fs.mkdir(dirPath, { recursive: true });
+      const dirPath = path2.resolve(process.cwd(), ".context/memory");
+      const filePath = path2.join(dirPath, filename);
+      await fs2.mkdir(dirPath, { recursive: true });
       const date6 = new Date().toISOString().split("T")[0];
       let fileContent = "";
       if (template) {
-        const templatePath = path.resolve(process.cwd(), `.context/templates/${template}.md`);
-        try {
-          fileContent = await fs.readFile(templatePath, "utf-8");
-          fileContent = fileContent.replace(/\[\uC81C\uBAA9\]/g, title);
-          fileContent += `
-
-${content}`;
-        } catch (err) {
-          fileContent = `Error loading template: ${err instanceof Error ? err.message : String(err)}
-
-${content}`;
+        if (tags && tags.length > 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error creating knowledge note: `tags` is not supported in template mode. Read the template and include any frontmatter or metadata directly in the markdown content."
+              }
+            ],
+            isError: true
+          };
         }
+        if (linked_notes && linked_notes.length > 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error creating knowledge note: `linked_notes` is not supported in template mode. Read the template and include related notes directly in the markdown content."
+              }
+            ],
+            isError: true
+          };
+        }
+        const templatePath = path2.resolve(process.cwd(), `.context/templates/${template}.md`);
+        const templateContent = await fs2.readFile(templatePath, "utf-8");
+        const validation = validateTemplatedKnowledgeNoteContent(templateContent, content);
+        if (validation.errors.length > 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error creating knowledge note: template content is invalid.
+- ${validation.errors.join(`
+- `)}
+Read the template and provide the fully completed markdown document in \`content\`.`
+              }
+            ],
+            isError: true
+          };
+        }
+        fileContent = content.endsWith(`
+`) ? content : `${content}
+`;
       } else {
         fileContent = `---
 `;
@@ -32937,7 +33467,7 @@ ${tags.map((t) => `  - ${t}`).join(`
 `) + `
 `;
       }
-      await fs.writeFile(filePath, fileContent, "utf-8");
+      await fs2.writeFile(filePath, fileContent, "utf-8");
       return {
         content: [
           {
@@ -32967,19 +33497,19 @@ ${tags.map((t) => `  - ${t}`).join(`
     }
   }, async ({ path: filePath, content, mode }) => {
     try {
-      const normalizedPath = path.normalize(filePath);
-      if (normalizedPath.startsWith("..") || path.isAbsolute(normalizedPath)) {
+      const normalizedPath = path2.normalize(filePath);
+      if (normalizedPath.startsWith("..") || path2.isAbsolute(normalizedPath)) {
         throw new Error("Invalid path: Directory traversal is not allowed");
       }
       if (!normalizedPath.startsWith("docs/") && !normalizedPath.startsWith(".context/")) {
         throw new Error("Invalid path: Only files in docs/ or .context/ are allowed");
       }
-      const fullPath = path.resolve(process.cwd(), normalizedPath);
-      await fs.mkdir(path.dirname(fullPath), { recursive: true });
+      const fullPath = path2.resolve(process.cwd(), normalizedPath);
+      await fs2.mkdir(path2.dirname(fullPath), { recursive: true });
       if (mode === "append") {
         let textToAppend = content;
         try {
-          const existingContent = await fs.readFile(fullPath, "utf-8");
+          const existingContent = await fs2.readFile(fullPath, "utf-8");
           if (existingContent.length > 0 && !existingContent.endsWith(`
 `)) {
             textToAppend = `
@@ -32991,9 +33521,9 @@ ${tags.map((t) => `  - ${t}`).join(`
           textToAppend += `
 `;
         }
-        await fs.appendFile(fullPath, textToAppend, "utf-8");
+        await fs2.appendFile(fullPath, textToAppend, "utf-8");
       } else {
-        await fs.writeFile(fullPath, content, "utf-8");
+        await fs2.writeFile(fullPath, content, "utf-8");
       }
       return {
         content: [
@@ -33061,12 +33591,12 @@ ${tags.map((t) => `  - ${t}`).join(`
       };
     }
     try {
-      const dirPath = path.resolve(process.cwd(), ".context");
-      const filePath = path.join(dirPath, ".work-complete");
-      await fs.mkdir(dirPath, { recursive: true });
+      const dirPath = path2.resolve(process.cwd(), ".context");
+      const filePath = path2.join(dirPath, ".work-complete");
+      await fs2.mkdir(dirPath, { recursive: true });
       const content = `timestamp=${Date.now()}
 `;
-      await fs.writeFile(filePath, content, "utf-8");
+      await fs2.writeFile(filePath, content, "utf-8");
       return {
         content: [
           {