context-mode 0.5.4 → 0.5.6

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "name": "context-mode",
       "source": "./",
       "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 10 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-      "version": "0.5.4",
+      "version": "0.5.6",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 10 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
   "author": {
     "name": "Mert Koseoğlu",

package/build/server.js

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { PolyglotExecutor } from "./executor.js";
 import { ContentStore } from "./store.js";
 import { detectRuntimes, getRuntimeSummary, getAvailableLanguages, hasBunRuntime, } from "./runtime.js";
-const VERSION = "0.5.4";
+const VERSION = "0.5.6";
 const runtimes = detectRuntimes();
 const available = getAvailableLanguages(runtimes);
 const server = new McpServer({
@@ -128,7 +128,7 @@ function indexStdout(stdout, source) {
         content: [
             {
                 type: "text",
-                text: `Indexed ${indexed.totalChunks} sections (${indexed.codeChunks} with code) from: ${indexed.label}\nUse search() to query this content.`,
+                text: `Indexed ${indexed.totalChunks} sections (${indexed.codeChunks} with code) from: ${indexed.label}\nUse search() to query this content. Use source: "${indexed.label}" to scope results.`,
             },
         ],
     };
@@ -360,7 +360,7 @@ server.registerTool("index", {
             content: [
                 {
                     type: "text",
-                    text: `Indexed ${result.totalChunks} sections (${result.codeChunks} with code) from: ${result.label}\nUse search() to query this content.`,
+                    text: `Indexed ${result.totalChunks} sections (${result.codeChunks} with code) from: ${result.label}\nUse search() to query this content. Use source: "${result.label}" to scope results.`,
                 },
             ],
         };
@@ -389,9 +389,11 @@ server.registerTool("search", {
         "- Get configuration details ('Tailwind responsive breakpoints')\n" +
         "- Find migration steps ('App Router data fetching')\n\n" +
         "SEARCH TIPS:\n" +
-        "- Use specific technical terms, not concepts ('__proto__' not 'security')\n" +
+        "- Queries use OR semantics — results matching more terms rank higher via BM25\n" +
+        "- Use 2-4 specific technical terms per query for best results\n" +
+        "- Use 'source' parameter to scope search to a specific indexed source (partial match)\n" +
         "- Check 'Searchable terms' from execute/execute_file results for available vocabulary\n" +
-        "- Combine multiple specific terms for better results\n\n" +
+        "- For broad topics, send multiple focused searches in parallel\n\n" +
         "Returns exact content — not summaries. Each result includes heading hierarchy and full section text.",
     inputSchema: z.object({
         query: z.string().describe("Natural language search query"),
@@ -400,17 +402,26 @@ server.registerTool("search", {
             .optional()
             .default(3)
             .describe("Maximum results to return (default: 3)"),
+        source: z
+            .string()
+            .optional()
+            .describe("Filter results to a specific indexed source (partial match). " +
+            "Use the source label from index/fetch_and_index response."),
     }),
-}, async ({ query, limit }) => {
+}, async ({ query, limit, source }) => {
     try {
         const store = getStore();
-        const results = store.search(query, limit);
+        const results = store.search(query, limit, source);
         if (results.length === 0) {
+            const sources = store.listSources();
+            const sourceList = sources.length > 0
+                ? `\nIndexed sources: ${sources.map((s) => `"${s.label}" (${s.chunkCount} sections)`).join(", ")}`
+                : "";
             return {
                 content: [
                     {
                         type: "text",
-                        text: `No results found for: "${query}". Make sure content has been indexed first.`,
+                        text: `No results found for: "${query}"${source ? ` in source "${source}"` : ""}.${sourceList}`,
                     },
                 ],
             };

package/build/store.d.ts

@@ -39,7 +39,11 @@ export declare class ContentStore {
      * look for headings — it chunks by line count with overlap.
      */
     indexPlainText(content: string, source: string, linesPerChunk?: number): IndexResult;
-    search(query: string, limit?: number): SearchResult[];
+    search(query: string, limit?: number, source?: string): SearchResult[];
+    listSources(): Array<{
+        label: string;
+        chunkCount: number;
+    }>;
     getDistinctiveTerms(sourceId: number, maxTerms?: number): string[];
     getStats(): StoreStats;
     close(): void;

package/build/store.js

@@ -40,7 +40,7 @@ function sanitizeQuery(query) {
         !["AND", "OR", "NOT", "NEAR"].includes(w.toUpperCase()));
     if (words.length === 0)
         return '""';
-    return words.map((w) => `"${w}"`).join(" ");
+    return words.map((w) => `"${w}"`).join(" OR ");
 }
 // ─────────────────────────────────────────────────────────
 // ContentStore
@@ -149,8 +149,9 @@ export class ContentStore {
         };
     }
     // ── Search ──
-    search(query, limit = 3) {
+    search(query, limit = 3, source) {
         const sanitized = sanitizeQuery(query);
+        const sourceFilter = source ? "AND sources.label LIKE ?" : "";
         const stmt = this.#db.prepare(`
       SELECT
         chunks.title,
@@ -160,11 +161,14 @@ export class ContentStore {
         bm25(chunks, 2.0, 1.0) AS rank
       FROM chunks
       JOIN sources ON sources.id = chunks.source_id
-      WHERE chunks MATCH ?
+      WHERE chunks MATCH ? ${sourceFilter}
       ORDER BY rank
       LIMIT ?
     `);
-        const rows = stmt.all(sanitized, limit);
+        const params = source
+            ? [sanitized, `%${source}%`, limit]
+            : [sanitized, limit];
+        const rows = stmt.all(...params);
         return rows.map((r) => ({
             title: r.title,
             content: r.content,
@@ -173,6 +177,12 @@ export class ContentStore {
             contentType: r.content_type,
         }));
     }
+    // ── Sources ──
+    listSources() {
+        return this.#db
+            .prepare("SELECT label, chunk_count as chunkCount FROM sources ORDER BY id DESC")
+            .all();
+    }
     // ── Vocabulary ──
     getDistinctiveTerms(sourceId, maxTerms = 40) {
         const stats = this.#db

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "type": "module",
   "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution, FTS5 knowledge base, and intent-driven search.",
   "author": "Mert Koseoğlu",

package/skills/context-mode/SKILL.md

@@ -92,6 +92,23 @@ Use context-mode for ANY of these, without being asked:
 | Shell commands with pipes | `shell` | grep, awk, jq, native tools |
 | File pattern matching | `shell` | find, wc, sort, uniq |
 
+## Search Query Strategy
+
+- BM25 uses **OR semantics** — results matching more terms rank higher automatically
+- Use 2-4 specific technical terms per query: `search("transform refine pipe")`
+- **Always use `source` parameter** when multiple docs are indexed to avoid cross-source contamination
+  - After `fetch_and_index` returns `source: "Zod API docs"`, use `search("refine", source: "Zod")`
+  - Partial match works: `source: "Node"` matches `"Node.js v22 CHANGELOG"`
+- Send multiple `search()` calls **in parallel** for different aspects of a topic
+- Example: instead of one broad search, send 3 focused parallel queries:
+  - `search("transform pipe", source: "Zod")` + `search("refine superRefine", source: "Zod")` + `search("coerce codec", source: "Zod")`
+
+## External Documentation
+
+- **Always use `fetch_and_index`** for external docs — NEVER `cat` or `execute` with local paths for packages you don't own
+- For GitHub-hosted projects, use the raw URL: `https://raw.githubusercontent.com/org/repo/main/CHANGELOG.md`
+- After indexing, use the `source` parameter in search to scope results to that specific document
+
 ## Critical Rules
 
 1. **Always console.log/print your findings.** stdout is all that enters context. No output = wasted call.