@winci/local-rag 0.2.4 → 0.2.6

package/.claude-plugin/hooks/hooks.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}

package/.claude-plugin/skills/local-rag/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: local-rag
+description: >
+  TRIGGER when: starting a new session, exploring unfamiliar code, searching for
+  functions/types/files, planning refactors, or needing context about past decisions.
+  Use local-rag MCP tools (search, read_relevant, project_map, etc.) instead of
+  manually grepping or reading files when semantic understanding is needed.
+user-invocable: false
+---
+
+## Using local-rag tools
+
+This project has a local RAG index (local-rag). Use these MCP tools:
+
+- **`search`**: Discover which files are relevant to a topic. Returns file paths
+  with snippet previews — use this when you need to know *where* something is.
+- **`read_relevant`**: Get the actual content of relevant semantic chunks —
+  individual functions, classes, or markdown sections — ranked by relevance.
+  Results include exact line ranges (`src/db.ts:42-67`) so you can navigate
+  directly to the edit location. Use this instead of `search` + `Read` when
+  you need the content itself. Two chunks from the same file can both appear
+  (no file deduplication).
+- **`project_map`**: When you need to understand how files relate to each other,
+  generate a dependency graph. Use `focus` to zoom into a specific file's
+  neighborhood. This is faster than reading import statements across many files.
+- **`search_conversation`**: Search past conversation history to recall previous
+  decisions, discussions, and tool outputs. Use this before re-investigating
+  something that may have been discussed in an earlier session.
+- **`create_checkpoint`**: Mark important moments — decisions, milestones,
+  blockers, direction changes. Do this liberally: after completing any feature
+  or task, after adding/modifying tools, after key technical decisions, before
+  and after large refactors, or when changing direction. If in doubt, create one.
+- **`list_checkpoints`** / **`search_checkpoints`**: Review or search past
+  checkpoints to understand project history and prior decisions.
+- **`index_files`**: If you've created or modified files and want them searchable,
+  re-index the project directory.
+- **`search_analytics`**: Check what queries return no results or low-relevance
+  results — this reveals documentation gaps.
+- **`search_symbols`**: When you know a symbol name (function, class, type, etc.),
+  find it directly by name instead of using semantic search.
+- **`find_usages`**: Before changing a function or type, find all its call sites.
+  Use this to understand the blast radius of a rename or API change. Faster and
+  more reliable than semantic search for finding usages.
+- **`git_context`**: At the start of a session (or any time you need orientation),
+  call this to see what files have already been modified, recent commits, and
+  which changed files are in the index. Avoids redundant searches and conflicting
+  edits on already-modified files.
+- **`annotate`**: Attach a persistent note to a file or symbol — "known race
+  condition", "don't refactor until auth rewrite lands", etc. Notes appear as
+  `[NOTE]` blocks inline in `read_relevant` results automatically.
+- **`get_annotations`**: Retrieve all notes for a file, or search semantically
+  across all annotations to find relevant caveats before editing.
+- **`write_relevant`**: Before adding new code or docs, find the best insertion
+  point — returns the most semantically appropriate file and anchor.

package/.mcp.json

@@ -1,11 +1,8 @@
 {
-    "mcpServers": {
-        "local-rag": {
-            "command": "bunx",
-            "args": [
-                "@winci/local-rag",
-                "serve"
-            ]
-        }
+  "mcpServers": {
+    "local-rag": {
+      "command": "bunx",
+      "args": ["@winci/local-rag@latest", "serve"]
     }
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winci/local-rag",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Semantic search for your codebase — local-first RAG MCP server with hybrid search, AST-aware chunking, and usage analytics",
   "type": "module",
   "license": "MIT",

package/src/cli/commands/init.ts

@@ -2,11 +2,12 @@ import { resolve } from "path";
 import { RagDB } from "../../db";
 import { loadConfig } from "../../config";
 import { indexDirectory } from "../../indexing/indexer";
-import { runSetup, mcpConfigSnippet, detectAgentHints, confirm } from "../setup";
+import { runSetup, confirm } from "../setup";
 import { cliProgress } from "../progress";
 
 export async function initCommand(args: string[], getFlag: (flag: string) => string | undefined) {
   const dir = resolve(args[1] && !args[1].startsWith("--") ? args[1] : ".");
+  const autoYes = args.includes("--yes") || args.includes("-y");
   const { actions } = await runSetup(dir);
   if (actions.length === 0) {
     console.log("Already set up — nothing to do.");
@@ -14,14 +15,8 @@ export async function initCommand(args: string[], getFlag: (flag: string) => str
     for (const action of actions) console.log(action);
   }
 
-  console.log("\nAdd this to your agent's MCP config (mcpServers):\n");
-  console.log(mcpConfigSnippet(dir));
-  const hints = detectAgentHints(dir);
   console.log();
-  for (const hint of hints) console.log(`  ${hint}`);
-
-  console.log();
-  const shouldIndex = await confirm("Index project now? [Y/n] ");
+  const shouldIndex = autoYes || await confirm("Index project now? [Y/n] ");
   if (shouldIndex) {
     const db = new RagDB(dir);
     const config = await loadConfig(dir);

package/src/cli/setup.ts

@@ -154,6 +154,79 @@ export function mcpConfigSnippet(projectDir: string): string {
   }, null, 2);
 }
 
+function mcpServerEntry(projectDir: string) {
+  return {
+    command: "bunx",
+    args: ["@winci/local-rag@latest"],
+    env: { RAG_PROJECT_DIR: resolve(projectDir) },
+  };
+}
+
+export async function ensureMcpJson(projectDir: string): Promise<string[]> {
+  const actions: string[] = [];
+  const entry = mcpServerEntry(projectDir);
+
+  // Claude Code — .mcp.json
+  const claudeMcpPath = join(projectDir, ".mcp.json");
+  if (existsSync(claudeMcpPath)) {
+    const raw = JSON.parse(await readFile(claudeMcpPath, "utf-8"));
+    if (!raw.mcpServers?.["local-rag"]) {
+      raw.mcpServers = raw.mcpServers || {};
+      raw.mcpServers["local-rag"] = entry;
+      await writeFile(claudeMcpPath, JSON.stringify(raw, null, 2) + "\n");
+      actions.push("Added local-rag to .mcp.json");
+    }
+  } else {
+    await writeFile(
+      claudeMcpPath,
+      JSON.stringify({ mcpServers: { "local-rag": entry } }, null, 2) + "\n"
+    );
+    actions.push("Created .mcp.json with local-rag");
+  }
+
+  // Cursor — .cursor/mcp.json
+  if (existsSync(join(projectDir, ".cursor"))) {
+    const cursorMcpPath = join(projectDir, ".cursor", "mcp.json");
+    if (existsSync(cursorMcpPath)) {
+      const raw = JSON.parse(await readFile(cursorMcpPath, "utf-8"));
+      if (!raw.mcpServers?.["local-rag"]) {
+        raw.mcpServers = raw.mcpServers || {};
+        raw.mcpServers["local-rag"] = entry;
+        await writeFile(cursorMcpPath, JSON.stringify(raw, null, 2) + "\n");
+        actions.push("Added local-rag to .cursor/mcp.json");
+      }
+    } else {
+      await writeFile(
+        cursorMcpPath,
+        JSON.stringify({ mcpServers: { "local-rag": entry } }, null, 2) + "\n"
+      );
+      actions.push("Created .cursor/mcp.json with local-rag");
+    }
+  }
+
+  // Windsurf — .windsurf/mcp.json
+  if (existsSync(join(projectDir, ".windsurf"))) {
+    const windsurfMcpPath = join(projectDir, ".windsurf", "mcp.json");
+    if (existsSync(windsurfMcpPath)) {
+      const raw = JSON.parse(await readFile(windsurfMcpPath, "utf-8"));
+      if (!raw.mcpServers?.["local-rag"]) {
+        raw.mcpServers = raw.mcpServers || {};
+        raw.mcpServers["local-rag"] = entry;
+        await writeFile(windsurfMcpPath, JSON.stringify(raw, null, 2) + "\n");
+        actions.push("Added local-rag to .windsurf/mcp.json");
+      }
+    } else {
+      await writeFile(
+        windsurfMcpPath,
+        JSON.stringify({ mcpServers: { "local-rag": entry } }, null, 2) + "\n"
+      );
+      actions.push("Created .windsurf/mcp.json with local-rag");
+    }
+  }
+
+  return actions;
+}
+
 export function detectAgentHints(projectDir: string): string[] {
   const hints: string[] = [];
   if (existsSync(join(projectDir, ".mcp.json")))
@@ -186,6 +259,9 @@ export async function runSetup(projectDir: string): Promise<SetupResult> {
   const instructionActions = await ensureAgentInstructions(projectDir);
   actions.push(...instructionActions);
 
+  const mcpActions = await ensureMcpJson(projectDir);
+  actions.push(...mcpActions);
+
   const gitignoreAction = await ensureGitignore(projectDir);
   if (gitignoreAction) actions.push(gitignoreAction);
 

package/src/server/index.ts

@@ -8,6 +8,7 @@ import { indexDirectory } from "../indexing/indexer";
 import { startWatcher, type Watcher } from "../indexing/watcher";
 import { discoverSessions } from "../conversation/parser";
 import { indexConversation, startConversationTail } from "../conversation/indexer";
+import { ensureGitignore } from "../cli/setup";
 import { registerAllTools } from "../tools";
 import { log } from "../utils/log";
 
@@ -54,6 +55,11 @@ export async function startServer() {
   let convWatcher: Watcher | null = null;
 
   if (!isHomeDirTrap) {
+    // Ensure .rag/ is gitignored
+    ensureGitignore(startupDir).catch((err) => {
+      log.warn(`Failed to update .gitignore: ${err instanceof Error ? err.message : err}`, "server");
+    });
+
     // Index in background — don't block server startup
     indexDirectory(startupDir, startupDb, startupConfig, (msg) => {
       process.stderr.write(`[local-rag] ${msg}\n`);