coding-friend-cli 1.0.0

package/lib/learn-mcp/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "coding-friend-learn-mcp",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "learn-mcp": "./dist/bin/learn-mcp.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "gray-matter": "^4.0.3",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/lib/learn-mcp/src/bin/learn-mcp.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../index.js";

package/lib/learn-mcp/src/index.ts

@@ -0,0 +1,17 @@
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerAllTools } from "./server.js";
+
+const rawDir = process.argv[2] ?? process.env.LEARN_DOCS_DIR ?? "./docs/learn";
+const docsDir = path.resolve(rawDir);
+
+const server = new McpServer({
+  name: "coding-friend-learn",
+  version: "1.0.0",
+});
+
+registerAllTools(server, docsDir);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/lib/learn-mcp/src/lib/docs.ts

@@ -0,0 +1,199 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import type { CategoryInfo, Doc, DocFrontmatter, DocMeta } from "./types.js";
+
+function isMarkdownDoc(filePath: string): boolean {
+  const name = path.basename(filePath);
+  return name.endsWith(".md") && name !== "README.md";
+}
+
+function parseFrontmatter(raw: matter.GrayMatterFile<string>): DocFrontmatter {
+  const d = raw.data;
+  return {
+    title: String(d.title ?? "Untitled"),
+    category: String(d.category ?? ""),
+    tags: Array.isArray(d.tags) ? d.tags.map(String) : [],
+    created: String(d.created ?? ""),
+    updated: String(d.updated ?? ""),
+  };
+}
+
+function makeExcerpt(content: string, maxLen = 160): string {
+  const text = content
+    .replace(/^#+\s.*/gm, "")
+    .replace(/```[\s\S]*?```/g, "")
+    .replace(/\n{2,}/g, " ")
+    .replace(/\n/g, " ")
+    .trim();
+  return text.length > maxLen ? text.slice(0, maxLen) + "..." : text;
+}
+
+export function getCategories(docsDir: string): CategoryInfo[] {
+  if (!fs.existsSync(docsDir)) return [];
+  return fs
+    .readdirSync(docsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+    .map((d) => {
+      const catPath = path.join(docsDir, d.name);
+      const count = fs
+        .readdirSync(catPath)
+        .filter((f) => isMarkdownDoc(f)).length;
+      return { name: d.name, docCount: count };
+    })
+    .filter((c) => c.docCount > 0);
+}
+
+export function getAllDocs(docsDir: string): DocMeta[] {
+  const docs: DocMeta[] = [];
+  const categories = getCategories(docsDir);
+
+  for (const cat of categories) {
+    const catPath = path.join(docsDir, cat.name);
+    const files = fs.readdirSync(catPath).filter(isMarkdownDoc);
+
+    for (const file of files) {
+      const filePath = path.join(catPath, file);
+      const raw = matter(fs.readFileSync(filePath, "utf-8"));
+      const frontmatter = parseFrontmatter(raw);
+
+      docs.push({
+        slug: path.basename(file, ".md"),
+        category: cat.name,
+        frontmatter: { ...frontmatter, category: cat.name },
+        excerpt: makeExcerpt(raw.content),
+      });
+    }
+  }
+
+  return docs.sort(
+    (a, b) =>
+      new Date(b.frontmatter.updated || b.frontmatter.created).getTime() -
+      new Date(a.frontmatter.updated || a.frontmatter.created).getTime(),
+  );
+}
+
+export function getDocsByCategory(
+  docsDir: string,
+  category: string,
+): DocMeta[] {
+  return getAllDocs(docsDir).filter((d) => d.category === category);
+}
+
+export function getDocsByTag(docsDir: string, tag: string): DocMeta[] {
+  const lowerTag = tag.toLowerCase();
+  return getAllDocs(docsDir).filter((d) =>
+    d.frontmatter.tags.some((t) => t.toLowerCase() === lowerTag),
+  );
+}
+
+export function readDoc(
+  docsDir: string,
+  category: string,
+  slug: string,
+): Doc | null {
+  const filePath = path.join(docsDir, category, `${slug}.md`);
+  if (!fs.existsSync(filePath)) return null;
+
+  const raw = matter(fs.readFileSync(filePath, "utf-8"));
+  const frontmatter = parseFrontmatter(raw);
+
+  return {
+    slug,
+    category,
+    frontmatter: { ...frontmatter, category },
+    excerpt: makeExcerpt(raw.content),
+    content: raw.content,
+  };
+}
+
+export function searchDocs(
+  docsDir: string,
+  query: string,
+  category?: string,
+): DocMeta[] {
+  const lowerQuery = query.toLowerCase();
+  let docs = getAllDocs(docsDir);
+
+  if (category) {
+    docs = docs.filter((d) => d.category === category);
+  }
+
+  return docs.filter((d) => {
+    const titleMatch = d.frontmatter.title.toLowerCase().includes(lowerQuery);
+    const tagMatch = d.frontmatter.tags.some((t) =>
+      t.toLowerCase().includes(lowerQuery),
+    );
+    const excerptMatch = d.excerpt.toLowerCase().includes(lowerQuery);
+
+    if (titleMatch || tagMatch || excerptMatch) return true;
+
+    const full = readDoc(docsDir, d.category, d.slug);
+    return full?.content.toLowerCase().includes(lowerQuery) ?? false;
+  });
+}
+
+export function slugify(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+export function createDoc(
+  docsDir: string,
+  category: string,
+  title: string,
+  tags: string[],
+  content: string,
+): string {
+  const catDir = path.join(docsDir, category);
+  if (!fs.existsSync(catDir)) {
+    fs.mkdirSync(catDir, { recursive: true });
+  }
+
+  const slug = slugify(title);
+  const filePath = path.join(catDir, `${slug}.md`);
+  const today = new Date().toISOString().split("T")[0];
+
+  const doc = matter.stringify(content, {
+    title,
+    category,
+    tags,
+    created: today,
+    updated: today,
+  });
+
+  fs.writeFileSync(filePath, doc, "utf-8");
+  return filePath;
+}
+
+export function updateDoc(
+  docsDir: string,
+  category: string,
+  slug: string,
+  updates: { content?: string; tags?: string[]; title?: string },
+): string | null {
+  const filePath = path.join(docsDir, category, `${slug}.md`);
+  if (!fs.existsSync(filePath)) return null;
+
+  const raw = matter(fs.readFileSync(filePath, "utf-8"));
+  const today = new Date().toISOString().split("T")[0];
+
+  if (updates.tags) {
+    raw.data.tags = [
+      ...new Set([...(raw.data.tags || []), ...updates.tags]),
+    ];
+  }
+  if (updates.title) {
+    raw.data.title = updates.title;
+  }
+  raw.data.updated = today;
+
+  const newContent = updates.content
+    ? raw.content + "\n\n" + updates.content
+    : raw.content;
+
+  fs.writeFileSync(filePath, matter.stringify(newContent, raw.data), "utf-8");
+  return filePath;
+}

package/lib/learn-mcp/src/lib/knowledge.ts

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { KnowledgeEntry, KnowledgeTracking } from "./types.js";
+import { getAllDocs } from "./docs.js";
+
+const TRACKING_FILE = ".knowledge-tracking.json";
+
+function trackingPath(docsDir: string): string {
+  return path.join(docsDir, TRACKING_FILE);
+}
+
+export function readTracking(docsDir: string): KnowledgeTracking {
+  const filePath = trackingPath(docsDir);
+  if (!fs.existsSync(filePath)) {
+    return { version: 1, entries: {} };
+  }
+  const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  return { version: 1, entries: raw.entries ?? {} };
+}
+
+export function writeTracking(
+  docsDir: string,
+  tracking: KnowledgeTracking,
+): void {
+  fs.writeFileSync(
+    trackingPath(docsDir),
+    JSON.stringify(tracking, null, 2) + "\n",
+    "utf-8",
+  );
+}
+
+export function trackKnowledge(
+  docsDir: string,
+  category: string,
+  slug: string,
+  status: KnowledgeEntry["status"],
+  notes?: string,
+): KnowledgeEntry {
+  const tracking = readTracking(docsDir);
+  const key = `${category}/${slug}`;
+  const today = new Date().toISOString().split("T")[0]!;
+  const existing = tracking.entries[key];
+
+  const entry: KnowledgeEntry = {
+    status,
+    lastReviewed: today,
+    reviewCount: (existing?.reviewCount ?? 0) + 1,
+    notes: notes ?? existing?.notes ?? "",
+    firstSeen: existing?.firstSeen ?? today,
+  };
+
+  tracking.entries[key] = entry;
+  writeTracking(docsDir, tracking);
+  return entry;
+}
+
+export function getReviewList(
+  docsDir: string,
+  statusFilter?: "needs-review" | "new",
+  limit?: number,
+): Array<{ key: string; entry: KnowledgeEntry }> {
+  const tracking = readTracking(docsDir);
+  const allDocs = getAllDocs(docsDir);
+
+  const results: Array<{ key: string; entry: KnowledgeEntry }> = [];
+
+  for (const doc of allDocs) {
+    const key = `${doc.category}/${doc.slug}`;
+    const entry = tracking.entries[key] ?? {
+      status: "new" as const,
+      lastReviewed: null,
+      reviewCount: 0,
+      notes: "",
+      firstSeen: doc.frontmatter.created || new Date().toISOString().split("T")[0]!,
+    };
+
+    if (statusFilter && entry.status !== statusFilter) continue;
+    if (!statusFilter && entry.status === "remembered") continue;
+
+    results.push({ key, entry });
+  }
+
+  results.sort((a, b) => {
+    if (a.entry.status === "needs-review" && b.entry.status !== "needs-review")
+      return -1;
+    if (a.entry.status !== "needs-review" && b.entry.status === "needs-review")
+      return 1;
+
+    const dateA = a.entry.lastReviewed ?? a.entry.firstSeen;
+    const dateB = b.entry.lastReviewed ?? b.entry.firstSeen;
+    return new Date(dateA).getTime() - new Date(dateB).getTime();
+  });
+
+  return limit ? results.slice(0, limit) : results;
+}

package/lib/learn-mcp/src/lib/types.ts

@@ -0,0 +1,36 @@
+export interface DocFrontmatter {
+  title: string;
+  category: string;
+  tags: string[];
+  created: string;
+  updated: string;
+}
+
+export interface DocMeta {
+  slug: string;
+  category: string;
+  frontmatter: DocFrontmatter;
+  excerpt: string;
+}
+
+export interface Doc extends DocMeta {
+  content: string;
+}
+
+export interface CategoryInfo {
+  name: string;
+  docCount: number;
+}
+
+export interface KnowledgeEntry {
+  status: "remembered" | "needs-review" | "new";
+  lastReviewed: string | null;
+  reviewCount: number;
+  notes: string;
+  firstSeen: string;
+}
+
+export interface KnowledgeTracking {
+  version: 1;
+  entries: Record<string, KnowledgeEntry>;
+}

package/lib/learn-mcp/src/server.ts

@@ -0,0 +1,22 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerListCategories } from "./tools/list-categories.js";
+import { registerListDocs } from "./tools/list-docs.js";
+import { registerReadDoc } from "./tools/read-doc.js";
+import { registerSearchDocs } from "./tools/search-docs.js";
+import { registerCreateDoc } from "./tools/create-doc.js";
+import { registerUpdateDoc } from "./tools/update-doc.js";
+import { registerImproveDoc } from "./tools/improve-doc.js";
+import { registerTrackKnowledge } from "./tools/track-knowledge.js";
+import { registerGetReviewList } from "./tools/get-review-list.js";
+
+export function registerAllTools(server: McpServer, docsDir: string): void {
+  registerListCategories(server, docsDir);
+  registerListDocs(server, docsDir);
+  registerReadDoc(server, docsDir);
+  registerSearchDocs(server, docsDir);
+  registerCreateDoc(server, docsDir);
+  registerUpdateDoc(server, docsDir);
+  registerImproveDoc(server, docsDir);
+  registerTrackKnowledge(server, docsDir);
+  registerGetReviewList(server, docsDir);
+}

package/lib/learn-mcp/src/tools/create-doc.ts

@@ -0,0 +1,29 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { createDoc } from "../lib/docs.js";
+
+export function registerCreateDoc(server: McpServer, docsDir: string): void {
+  server.tool(
+    "create-doc",
+    "Create a new learning doc with proper YAML frontmatter. Provide the category, title, tags, and markdown content.",
+    {
+      category: z
+        .string()
+        .describe("Category folder name (created if missing)"),
+      title: z.string().describe("Doc title"),
+      tags: z.array(z.string()).describe("Tags for the doc"),
+      content: z.string().describe("Markdown content (without frontmatter)"),
+    },
+    async ({ category, title, tags, content }) => {
+      const filePath = createDoc(docsDir, category, title, tags, content);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ path: filePath, created: true }, null, 2),
+          },
+        ],
+      };
+    },
+  );
+}

package/lib/learn-mcp/src/tools/get-review-list.ts

@@ -0,0 +1,29 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { getReviewList } from "../lib/knowledge.js";
+
+export function registerGetReviewList(
+  server: McpServer,
+  docsDir: string,
+): void {
+  server.tool(
+    "get-review-list",
+    "Get learning docs that need review. Returns docs marked as 'needs-review' or 'new', sorted by staleness. Docs marked 'remembered' are excluded.",
+    {
+      status: z
+        .enum(["needs-review", "new"])
+        .optional()
+        .describe("Filter by specific status"),
+      limit: z
+        .number()
+        .optional()
+        .describe("Max number of results to return"),
+    },
+    async ({ status, limit }) => {
+      const results = getReviewList(docsDir, status, limit);
+      return {
+        content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+      };
+    },
+  );
+}

package/lib/learn-mcp/src/tools/improve-doc.ts

@@ -0,0 +1,95 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { readDoc } from "../lib/docs.js";
+
+const EXPECTED_SECTIONS = ["What", "Why", "How", "Gotchas", "Read More"];
+
+export function registerImproveDoc(server: McpServer, docsDir: string): void {
+  server.tool(
+    "improve-doc",
+    "Analyze a learning doc and return improvement suggestions. Checks for missing sections, short content, missing code examples, stale dates, etc.",
+    {
+      category: z.string().describe("Category folder name"),
+      slug: z.string().describe("Doc filename without .md extension"),
+    },
+    async ({ category, slug }) => {
+      const doc = readDoc(docsDir, category, slug);
+      if (!doc) {
+        return {
+          content: [
+            { type: "text", text: `Doc not found: ${category}/${slug}.md` },
+          ],
+          isError: true,
+        };
+      }
+
+      const suggestions: string[] = [];
+
+      for (const section of EXPECTED_SECTIONS) {
+        const regex = new RegExp(`^##\\s+${section}`, "m");
+        if (!regex.test(doc.content)) {
+          suggestions.push(`Missing section: ## ${section}`);
+        }
+      }
+
+      const howMatch = doc.content.match(/## How\n([\s\S]*?)(?=\n## |$)/);
+      if (howMatch && !howMatch[1]!.includes("```")) {
+        suggestions.push(
+          "The 'How' section has no code examples. Add real code from the project.",
+        );
+      }
+
+      const sections = doc.content.split(/^## /m).slice(1);
+      for (const section of sections) {
+        const lines = section.split("\n").filter((l) => l.trim()).length;
+        const name = section.split("\n")[0]?.trim();
+        if (lines < 3 && name) {
+          suggestions.push(
+            `Section '${name}' is very short (${lines} lines). Consider expanding.`,
+          );
+        }
+      }
+
+      if (doc.frontmatter.tags.length === 0) {
+        suggestions.push(
+          "No tags found. Add relevant tags for discoverability.",
+        );
+      }
+
+      if (doc.frontmatter.updated) {
+        const updated = new Date(doc.frontmatter.updated);
+        const daysSince = Math.floor(
+          (Date.now() - updated.getTime()) / (1000 * 60 * 60 * 24),
+        );
+        if (daysSince > 90) {
+          suggestions.push(
+            `Doc hasn't been updated in ${daysSince} days. Review if content is still accurate.`,
+          );
+        }
+      }
+
+      const readMoreMatch = doc.content.match(
+        /## Read More\n([\s\S]*?)(?=\n## |$)/,
+      );
+      if (readMoreMatch && !readMoreMatch[1]!.includes("http")) {
+        suggestions.push(
+          "The 'Read More' section has no external links. Add links to official docs or tutorials.",
+        );
+      }
+
+      const result =
+        suggestions.length > 0
+          ? suggestions
+          : ["Doc looks good! No improvement suggestions."];
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ suggestions: result }, null, 2),
+          },
+        ],
+      };
+    },
+  );
+}

package/lib/learn-mcp/src/tools/list-categories.ts

@@ -0,0 +1,19 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { getCategories } from "../lib/docs.js";
+
+export function registerListCategories(
+  server: McpServer,
+  docsDir: string,
+): void {
+  server.tool(
+    "list-categories",
+    "List all learning doc categories with document counts",
+    {},
+    async () => {
+      const categories = getCategories(docsDir);
+      return {
+        content: [{ type: "text", text: JSON.stringify(categories, null, 2) }],
+      };
+    },
+  );
+}

package/lib/learn-mcp/src/tools/list-docs.ts

@@ -0,0 +1,30 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { getAllDocs, getDocsByCategory, getDocsByTag } from "../lib/docs.js";
+
+export function registerListDocs(server: McpServer, docsDir: string): void {
+  server.tool(
+    "list-docs",
+    "List learning docs. Optionally filter by category or tag. Returns doc metadata (title, category, tags, dates, excerpt).",
+    {
+      category: z.string().optional().describe("Filter by category name"),
+      tag: z.string().optional().describe("Filter by tag"),
+      limit: z.number().optional().describe("Max number of docs to return"),
+    },
+    async ({ category, tag, limit }) => {
+      let docs = category
+        ? getDocsByCategory(docsDir, category)
+        : tag
+          ? getDocsByTag(docsDir, tag)
+          : getAllDocs(docsDir);
+
+      if (limit && limit > 0) {
+        docs = docs.slice(0, limit);
+      }
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(docs, null, 2) }],
+      };
+    },
+  );
+}

package/lib/learn-mcp/src/tools/read-doc.ts

@@ -0,0 +1,29 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { readDoc } from "../lib/docs.js";
+
+export function registerReadDoc(server: McpServer, docsDir: string): void {
+  server.tool(
+    "read-doc",
+    "Read the full content of a single learning doc by category and slug (filename without .md).",
+    {
+      category: z.string().describe("Category folder name"),
+      slug: z.string().describe("Doc filename without .md extension"),
+    },
+    async ({ category, slug }) => {
+      const doc = readDoc(docsDir, category, slug);
+      if (!doc) {
+        return {
+          content: [
+            { type: "text", text: `Doc not found: ${category}/${slug}.md` },
+          ],
+          isError: true,
+        };
+      }
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(doc, null, 2) }],
+      };
+    },
+  );
+}

package/lib/learn-mcp/src/tools/search-docs.ts

@@ -0,0 +1,23 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { searchDocs } from "../lib/docs.js";
+
+export function registerSearchDocs(server: McpServer, docsDir: string): void {
+  server.tool(
+    "search-docs",
+    "Full-text search across all learning docs. Searches titles, tags, and content. Optionally filter by category.",
+    {
+      query: z.string().describe("Search query text"),
+      category: z
+        .string()
+        .optional()
+        .describe("Limit search to this category"),
+    },
+    async ({ query, category }) => {
+      const results = searchDocs(docsDir, query, category);
+      return {
+        content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+      };
+    },
+  );
+}