coding-friend-cli 1.1.1 → 1.2.1

package/lib/learn-mcp/README.md

@@ -0,0 +1,169 @@
+# coding-friend-learn-mcp
+
+MCP (Model Context Protocol) server that exposes your `/cf-learn` docs as tools for Claude — letting Claude read, search, write, and improve your learning notes directly.
+
+## Usage (via CLI)
+
+```bash
+cf mcp                     # setup MCP for docs/learn/
+cf mcp ./my-docs           # setup MCP for a custom directory
+```
+
+The CLI builds the server and prints the config to add to Claude Desktop / Claude Code.
+
+## Local Development
+
+Run the server directly without the CLI — useful when working on tools or docs logic.
+
+### 1. Install dependencies
+
+```bash
+cd cli/lib/learn-mcp
+npm install
+```
+
+### 2. Run with tsx (no build needed)
+
+The server accepts the docs directory as the first CLI argument, or via `LEARN_DOCS_DIR` env var.
+
+```bash
+# Using argument
+npx tsx src/index.ts /path/to/your/docs/learn
+
+# Using env var
+LEARN_DOCS_DIR=/path/to/your/docs/learn npx tsx src/index.ts
+
+# Point to this repo's own learn docs
+npx tsx src/index.ts ../../../docs/learn
+```
+
+The server communicates over stdio (MCP protocol), so you won't see output when running manually — it's meant to be connected to Claude.
+
+### 3. Connect to Claude Code (dev mode)
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "coding-friend-learn": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "tsx",
+        "/path/to/coding-friend/cli/lib/learn-mcp/src/index.ts",
+        "/path/to/your/docs/learn"
+      ]
+    }
+  }
+}
+```
+
+Or for Claude Desktop, add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "coding-friend-learn": {
+      "command": "npx",
+      "args": [
+        "tsx",
+        "/path/to/coding-friend/cli/lib/learn-mcp/src/index.ts",
+        "/path/to/your/docs/learn"
+      ]
+    }
+  }
+}
+```
+
+### 4. Watch mode (auto-rebuild)
+
+Keep a terminal running to auto-rebuild on every file change:
+
+```bash
+npm run dev:watch
+```
+
+Then restart the MCP server in Claude Code (`/mcp` → restart) to pick up the latest changes.
+
+### 5. Build and run compiled
+
+```bash
+npm run build
+node dist/index.js /path/to/docs/learn
+```
+
+## Docs Directory Structure
+
+```
+docs/
+└── learn/
+    ├── category-one/
+    │   ├── my-doc.md
+    │   └── another-doc.md
+    └── category-two/
+        └── some-doc.md
+```
+
+Each `.md` file needs frontmatter:
+
+```md
+---
+title: My Doc Title
+category: category-one
+tags: [typescript, patterns]
+created: 2025-01-01
+updated: 2025-01-15
+---
+
+Content here...
+```
+
+## Available Tools
+
+| Tool              | Type  | Description                                      |
+| ----------------- | ----- | ------------------------------------------------ |
+| `list-categories` | Read  | List all doc categories                          |
+| `list-docs`       | Read  | List docs (optionally filter by category or tag) |
+| `read-doc`        | Read  | Read a specific doc by category + slug           |
+| `search-docs`     | Read  | Full-text search across all docs                 |
+| `get-review-list` | Read  | Get docs needing review                          |
+| `create-doc`      | Write | Create a new doc with frontmatter                |
+| `update-doc`      | Write | Append content or update tags on an existing doc |
+| `improve-doc`     | Write | Replace doc content while preserving frontmatter |
+| `track-knowledge` | Write | Mark a doc as remembered / needs-review / new    |
+
+## Structure
+
+```
+src/
+├── index.ts          # Entry: parses docs dir, starts MCP server
+├── server.ts         # Registers all tools
+├── bin/
+│   └── learn-mcp.ts  # CLI binary entry
+├── tools/            # One file per MCP tool
+│   ├── list-categories.ts
+│   ├── list-docs.ts
+│   ├── read-doc.ts
+│   ├── search-docs.ts
+│   ├── create-doc.ts
+│   ├── update-doc.ts
+│   ├── improve-doc.ts
+│   ├── track-knowledge.ts
+│   └── get-review-list.ts
+└── lib/
+    ├── docs.ts       # Shared doc utilities (read, write, search)
+    ├── types.ts      # TypeScript interfaces
+    └── knowledge.ts  # Knowledge tracking state
+```
+
+## How It Fits Together
+
+```
+cf mcp [path]
+  └─ resolves docs dir
+  └─ npm install + build (one-time)
+  └─ prints MCP config to add to Claude
+```
+
+Once configured, Claude can call these tools directly to read and write your learning notes without leaving the conversation.

package/lib/learn-mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coding-friend-learn-mcp",
-  "version": "1.0.0",
+  "version": "0.0.2",
   "private": true,
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/index.ts",
+    "dev:watch": "tsc --watch --preserveWatchOutput",
     "start": "node dist/index.js"
   },
   "dependencies": {

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

@@ -8,7 +8,7 @@ const docsDir = path.resolve(rawDir);
 
 const server = new McpServer({
   name: "coding-friend-learn",
-  version: "1.0.0",
+  version: "0.0.1",
 });
 
 registerAllTools(server, docsDir);

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

@@ -181,9 +181,7 @@ export function updateDoc(
   const today = new Date().toISOString().split("T")[0];
 
   if (updates.tags) {
-    raw.data.tags = [
-      ...new Set([...(raw.data.tags || []), ...updates.tags]),
-    ];
+    raw.data.tags = [...new Set([...(raw.data.tags || []), ...updates.tags])];
   }
   if (updates.title) {
     raw.data.title = updates.title;

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

@@ -71,7 +71,8 @@ export function getReviewList(
       lastReviewed: null,
       reviewCount: 0,
       notes: "",
-      firstSeen: doc.frontmatter.created || new Date().toISOString().split("T")[0]!,
+      firstSeen:
+        doc.frontmatter.created || new Date().toISOString().split("T")[0]!,
     };
 
     if (statusFilter && entry.status !== statusFilter) continue;

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

@@ -14,10 +14,7 @@ export function registerGetReviewList(
         .enum(["needs-review", "new"])
         .optional()
         .describe("Filter by specific status"),
-      limit: z
-        .number()
-        .optional()
-        .describe("Max number of results to return"),
+      limit: z.number().optional().describe("Max number of results to return"),
     },
     async ({ status, limit }) => {
       const results = getReviewList(docsDir, status, limit);

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

@@ -8,10 +8,7 @@ export function registerSearchDocs(server: McpServer, docsDir: string): void {
     "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"),
+      category: z.string().optional().describe("Limit search to this category"),
     },
     async ({ query, category }) => {
       const results = searchDocs(docsDir, query, category);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coding-friend-cli",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "CLI for coding-friend — host learning docs, setup MCP server, initialize projects",
   "type": "module",
   "bin": {
@@ -8,9 +8,12 @@
   },
   "scripts": {
     "build": "tsup src/index.ts src/postinstall.ts --format esm --dts --clean",
-    "postinstall": "node dist/postinstall.js || true",
-    "prepublishOnly": "npm run build && node scripts/bundle-libs.js",
-    "dev": "tsx src/index.ts"
+    "postinstall": "test -f dist/postinstall.js && node dist/postinstall.js || true",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/index.ts",
+    "watch": "tsup src/index.ts src/postinstall.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "files": [
     "dist",
@@ -23,7 +26,11 @@
     "mcp",
     "claude"
   ],
-  "author": "Anh-Thi Dinh",
+  "author": {
+    "name": "Anh-Thi Dinh",
+    "email": "me@dinhanhthi.com",
+    "url": "https://dinhanhthi.com"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -42,6 +49,7 @@
     "@types/node": "^22.0.0",
     "tsup": "^8.0.0",
     "tsx": "^4.0.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
   }
 }

package/dist/chunk-VHZQ6KEU.js

@@ -1,73 +0,0 @@
-import {
-  log
-} from "./chunk-6DUFTBTO.js";
-
-// src/lib/shell-completion.ts
-import { appendFileSync, existsSync, readFileSync } from "fs";
-import { homedir } from "os";
-var MARKER_START = "# >>> coding-friend CLI completion >>>";
-var MARKER_END = "# <<< coding-friend CLI completion <<<";
-var BASH_BLOCK = `
-
-${MARKER_START}
-_cf_completions() {
-  local cur="\${COMP_WORDS[COMP_CWORD]}"
-  local commands="init host mcp statusline update"
-  COMPREPLY=($(compgen -W "$commands" -- "$cur"))
-}
-complete -o default -F _cf_completions cf
-${MARKER_END}
-`;
-var ZSH_BLOCK = `
-
-${MARKER_START}
-_cf() {
-  local -a commands
-  commands=(
-    'init:Initialize coding-friend in current project'
-    'host:Build and serve learning docs as a static website'
-    'mcp:Setup MCP server for learning docs'
-    'statusline:Setup coding-friend statusline in Claude Code'
-    'update:Update coding-friend plugin and refresh statusline'
-  )
-  _describe 'command' commands
-}
-compdef _cf cf
-${MARKER_END}
-`;
-function getShellRcPath() {
-  const shell = process.env.SHELL ?? "";
-  if (shell.includes("zsh")) return `${homedir()}/.zshrc`;
-  return `${homedir()}/.bashrc`;
-}
-function getRcName(rcPath) {
-  return rcPath.endsWith(".zshrc") ? ".zshrc" : ".bashrc";
-}
-function isZsh(rcPath) {
-  return rcPath.endsWith(".zshrc");
-}
-function hasShellCompletion() {
-  const rcPath = getShellRcPath();
-  if (!existsSync(rcPath)) return false;
-  return readFileSync(rcPath, "utf-8").includes(MARKER_START);
-}
-function ensureShellCompletion(opts) {
-  const rcPath = getShellRcPath();
-  const rcName = getRcName(rcPath);
-  if (hasShellCompletion()) {
-    if (!opts?.silent) log.dim(`Tab completion already in ~/${rcName}`);
-    return false;
-  }
-  const block = isZsh(rcPath) ? ZSH_BLOCK : BASH_BLOCK;
-  appendFileSync(rcPath, block);
-  if (!opts?.silent) {
-    log.success(`Tab completion added to ~/${rcName}`);
-    log.dim(`Run \`source ~/${rcName}\` or open a new terminal to activate.`);
-  }
-  return true;
-}
-
-export {
-  hasShellCompletion,
-  ensureShellCompletion
-};

package/lib/learn-host/src/app/search/page.tsx

@@ -1,19 +0,0 @@
-"use client";
-
-import { Suspense } from "react";
-import { useSearchParams } from "next/navigation";
-import PagefindSearch from "@/components/PagefindSearch";
-
-function SearchWithParams() {
-  const searchParams = useSearchParams();
-  const query = searchParams.get("q") ?? "";
-  return <PagefindSearch initialQuery={query} />;
-}
-
-export default function SearchPage() {
-  return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <SearchWithParams />
-    </Suspense>
-  );
-}

package/lib/learn-host/src/components/SearchBar.tsx

@@ -1,36 +0,0 @@
-"use client";
-
-import { useRouter } from "next/navigation";
-import { useState } from "react";
-
-export default function SearchBar() {
-  const [query, setQuery] = useState("");
-  const router = useRouter();
-
-  function handleSubmit(e: React.FormEvent) {
-    e.preventDefault();
-    if (query.trim()) {
-      router.push(`/search/?q=${encodeURIComponent(query.trim())}`);
-    }
-  }
-
-  return (
-    <form onSubmit={handleSubmit} className="relative">
-      <svg
-        className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-gray-400"
-        fill="none"
-        viewBox="0 0 24 24"
-        stroke="currentColor"
-      >
-        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
-      </svg>
-      <input
-        type="text"
-        value={query}
-        onChange={(e) => setQuery(e.target.value)}
-        placeholder="Search docs..."
-        className="w-full pl-10 pr-4 py-2 text-sm rounded-lg border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-800 focus:outline-none focus:ring-2 focus:ring-blue-500 dark:focus:ring-blue-400"
-      />
-    </form>
-  );
-}