zigsm 1.4.0 → 1.4.2

package/README.md

@@ -12,7 +12,7 @@ It uses the same approach as Zig's official autodoc (ziglang.org) by reading STD
 By default, the server uses your locally installed Zig compiler to serve documentation, ensuring you always get docs that match your actual Zig version. It can also fetch documentation from ziglang.org if needed.
 
 > [!TIP]
-> Add `use zigdocs` to your prompt if you want to explicitly instruct the LLM to use Zig docs tools. Otherwise, LLM will automatically decide when to utilize MCP tools based on the context of your questions.
+> Add `use zsm` to your prompt if you want to explicitly instruct the LLM to use zsm tools. Otherwise, LLM will automatically decide when to utilize MCP tools based on the context of your questions.
 
 <p align="center" width="100%">
   <img src="https://raw.githubusercontent.com/zig-wasm/.github/refs/heads/main/static/readme_mcp_1.gif" width="49%" />
@@ -82,7 +82,7 @@ When using `--doc-source remote`, documentation is fetched from ziglang.org and
 
 Optional environment variables:
 - `VOYAGE_API_KEY` - Enables embeddings for doc search when set.
-- `VOYAGE_MODEL` - Embedding model override (default: `voyage-3-lite`).
+- `VOYAGE_MODEL` - Embedding model override (default: `voyage-code-3`).
 
 Embeddings are cached per Zig version, doc source, and model in the same cache directory used for docs.
 
@@ -117,13 +117,19 @@ Add the JSON configuration below to your MCP settings file.
 
 ### JSON Configuration Template
 
+To enable semantic search with Voyage embeddings, include an `env` block like shown below.
+
 **Node.js:**
 ```json
 {
   "mcpServers": {
     "zsm": {
       "command": "npx",
-      "args": ["-y", "zigsm@latest"]
+      "args": ["-y", "zigsm@latest"],
+      "env": {
+        "VOYAGE_API_KEY": "your_voyage_api_key",
+        "VOYAGE_MODEL": "voyage-code-3"
+      }
     }
   }
 }
@@ -135,7 +141,11 @@ Add the JSON configuration below to your MCP settings file.
   "mcpServers": {
     "zsm": {
       "command": "bunx",
-      "args": ["zigsm@latest"]
+      "args": ["zigsm@latest"],
+      "env": {
+        "VOYAGE_API_KEY": "your_voyage_api_key",
+        "VOYAGE_MODEL": "voyage-code-3"
+      }
     }
   }
 }
@@ -161,7 +171,11 @@ claude mcp add zsm -- bunx zigsm@latest --doc-source remote --version 0.14.1
   "mcpServers": {
     "zsm": {
       "command": "npx",
-      "args": ["-y", "zigsm@latest", "--doc-source", "remote", "--version", "master"]
+      "args": ["-y", "zigsm@latest", "--doc-source", "remote", "--version", "master"],
+      "env": {
+        "VOYAGE_API_KEY": "your_voyage_api_key",
+        "VOYAGE_MODEL": "voyage-code-3"
+      }
     }
   }
 }
@@ -173,7 +187,11 @@ claude mcp add zsm -- bunx zigsm@latest --doc-source remote --version 0.14.1
   "mcpServers": {
     "zsm": {
       "command": "bunx",
-      "args": ["zigsm@latest", "--doc-source", "remote", "--version", "0.14.1"]
+      "args": ["zigsm@latest", "--doc-source", "remote", "--version", "0.14.1"],
+      "env": {
+        "VOYAGE_API_KEY": "your_voyage_api_key",
+        "VOYAGE_MODEL": "voyage-code-3"
+      }
     }
   }
 }

package/dist/mcp.js

@@ -103,7 +103,7 @@ async function main() {
     const builtinFunctions = await ensureDocs(options.version, options.updatePolicy, true, options.docSource);
     const stdSources = await downloadSourcesTar(options.version, true, false, options.docSource);
     const mcpServer = new McpServer({
-        name: "ZigDocs",
+        name: "ZSM",
         description: "Retrieves up-to-date documentation for the Zig programming language standard library and builtin functions.",
         version: options.version,
     });

package/dist/std.js

@@ -741,6 +741,38 @@ function setInputString(s) {
     wasmArray.set(jsArray);
 }
 let inMemoryEmbeddingCache = null;
+let cachedSourceTextIndex = null;
+let cachedSourceTextRef = null;
+function countWordHits(text, words) {
+    let hits = 0;
+    for (const word of words) {
+        if (text.includes(word))
+            hits++;
+    }
+    return hits;
+}
+function scoreDeclMatch(decl, queryLower, queryWords) {
+    const nameLower = decl.name.toLowerCase();
+    const pathLower = decl.path.toLowerCase();
+    let score = 0;
+    if (nameLower === queryLower)
+        score += 1000;
+    else if (nameLower.startsWith(queryLower))
+        score += 700;
+    else if (nameLower.includes(queryLower))
+        score += 450;
+    if (pathLower.includes(queryLower))
+        score += 150;
+    if (score === 0 && queryWords.length > 0) {
+        const searchable = `${nameLower} ${decl.preview.toLowerCase()} ${pathLower}`;
+        const wordHits = countWordHits(searchable, queryWords);
+        if (wordHits === queryWords.length)
+            score += 300;
+        else if (wordHits > 0)
+            score += wordHits * 80;
+    }
+    return score;
+}
 async function initWasmRuntime(wasmPath, stdSources) {
     const fs = await import("node:fs");
     const wasmBytes = typeof wasmPath === "string" ? fs.readFileSync(wasmPath) : wasmPath;
@@ -813,6 +845,169 @@ function stripMarkdown(input) {
         .replace(/\s+/g, " ")
         .trim();
 }
+function parseTarOctal(raw) {
+    const cleaned = raw.replace(/\0/g, "").trim();
+    if (!cleaned)
+        return 0;
+    const parsed = Number.parseInt(cleaned, 8);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function parseSourcesTar(stdSources) {
+    const files = [];
+    let offset = 0;
+    while (offset + 512 <= stdSources.length) {
+        const header = stdSources.subarray(offset, offset + 512);
+        let emptyHeader = true;
+        for (let i = 0; i < 512; i++) {
+            if (header[i] !== 0) {
+                emptyHeader = false;
+                break;
+            }
+        }
+        if (emptyHeader)
+            break;
+        const name = text_decoder.decode(header.subarray(0, 100)).replace(/\0.*$/, "").trim();
+        const sizeRaw = text_decoder
+            .decode(header.subarray(124, 136))
+            .replace(/\0.*$/, "")
+            .trim();
+        const prefix = text_decoder
+            .decode(header.subarray(345, 500))
+            .replace(/\0.*$/, "")
+            .trim();
+        const size = parseTarOctal(sizeRaw);
+        const fullPath = prefix.length > 0 ? `${prefix}/${name}` : name;
+        const contentStart = offset + 512;
+        const contentEnd = contentStart + size;
+        if (size > 0 && contentEnd <= stdSources.length && fullPath.endsWith(".zig")) {
+            const text = text_decoder.decode(stdSources.subarray(contentStart, contentEnd));
+            files.push({ path: fullPath, text, lowerText: text.toLowerCase() });
+        }
+        const paddedSize = Math.ceil(size / 512) * 512;
+        offset = contentStart + paddedSize;
+    }
+    return files;
+}
+function buildSourceTextIndex(stdSources) {
+    if (cachedSourceTextIndex && cachedSourceTextRef === stdSources) {
+        return cachedSourceTextIndex;
+    }
+    const files = parseSourcesTar(stdSources);
+    const decls = [];
+    const declRegex = /^\s*(?:pub\s+)?(?:const|var|fn)\s+([A-Za-z_][A-Za-z0-9_]*)/;
+    for (let fileIndex = 0; fileIndex < files.length; fileIndex++) {
+        const file = files[fileIndex];
+        const lines = file.text.split("\n");
+        for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+            const line = lines[lineIndex];
+            const match = line.match(declRegex);
+            if (!match)
+                continue;
+            decls.push({
+                name: match[1],
+                path: file.path,
+                line: lineIndex + 1,
+                preview: line.trim(),
+            });
+        }
+    }
+    cachedSourceTextRef = stdSources;
+    cachedSourceTextIndex = { files, decls };
+    return cachedSourceTextIndex;
+}
+function fallbackSearchStdLib(stdSources, query, limit) {
+    const index = buildSourceTextIndex(stdSources);
+    const queryLower = query.toLowerCase().trim();
+    const queryWords = queryLower.split(/\s+/).filter(Boolean);
+    const declScored = index.decls
+        .map((decl) => ({ decl, score: scoreDeclMatch(decl, queryLower, queryWords) }))
+        .filter((item) => item.score > 0)
+        .sort((a, b) => b.score - a.score);
+    const contentMatches = [];
+    if (declScored.length < limit) {
+        for (const file of index.files) {
+            const lines = file.text.split("\n");
+            for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+                const wordHits = countWordHits(lines[lineIndex].toLowerCase(), queryWords);
+                if (wordHits === queryWords.length) {
+                    contentMatches.push({
+                        path: file.path,
+                        line: lineIndex + 1,
+                        preview: lines[lineIndex].trim().slice(0, 120),
+                        score: 200 + wordHits * 30,
+                    });
+                }
+                if (contentMatches.length >= limit * 3)
+                    break;
+            }
+            if (contentMatches.length >= limit * 3)
+                break;
+        }
+        contentMatches.sort((a, b) => b.score - a.score);
+    }
+    let markdown = `# Search Results\n\nQuery: "${query}"\n\n`;
+    markdown += `_Fallback mode: text index (parser-incompatible Zig version)_\n\n`;
+    if (declScored.length === 0 && contentMatches.length === 0) {
+        markdown += "No results found.";
+        return markdown;
+    }
+    if (declScored.length > 0) {
+        const limited = declScored.slice(0, limit);
+        markdown += `Found ${declScored.length} declaration matches (showing ${limited.length}):\n\n`;
+        for (let i = 0; i < limited.length; i++) {
+            const entry = limited[i].decl;
+            markdown += `- std.${entry.name} (${entry.path}:${entry.line})\n`;
+        }
+    }
+    if (contentMatches.length > 0 && declScored.length < limit) {
+        const remaining = limit - declScored.length;
+        const limited = contentMatches.slice(0, remaining);
+        markdown += `\nContent matches:\n\n`;
+        for (let i = 0; i < limited.length; i++) {
+            const entry = limited[i];
+            markdown += `- ${entry.path}:${entry.line} — \`${entry.preview}\`\n`;
+        }
+    }
+    return markdown;
+}
+function fallbackGetStdLibItem(stdSources, name, getSourceFile) {
+    const index = buildSourceTextIndex(stdSources);
+    if (getSourceFile) {
+        const normalized = name.replace(/^src\//, "");
+        const matchedFile = index.files.find((file) => file.path === normalized) ||
+            index.files.find((file) => file.path.endsWith(`/${normalized}`)) ||
+            index.files.find((file) => file.path.endsWith(name));
+        if (!matchedFile) {
+            return `# Error\n\nCould not find source file for "${name}" in fallback mode.`;
+        }
+        return `# ${matchedFile.path}\n\n${matchedFile.text}`;
+    }
+    const target = name.split(".").pop()?.trim() || name.trim();
+    const targetLower = target.toLowerCase();
+    const ranked = index.decls
+        .map((decl) => ({ decl, score: scoreDeclMatch(decl, targetLower, [targetLower]) }))
+        .filter((item) => item.score > 0)
+        .sort((a, b) => b.score - a.score);
+    if (ranked.length === 0) {
+        return `# Error\n\nDeclaration "${name}" not found (fallback mode).`;
+    }
+    const best = ranked[0].decl;
+    const file = index.files.find((entry) => entry.path === best.path);
+    if (!file) {
+        return `# Error\n\nDeclaration "${name}" matched, but source file could not be loaded.`;
+    }
+    const lines = file.text.split("\n");
+    const startLine = Math.max(1, best.line - 20);
+    const endLine = Math.min(lines.length, best.line + 80);
+    const snippet = lines.slice(startLine - 1, endLine).join("\n");
+    let markdown = `# ${name}\n\n`;
+    markdown += `_Fallback mode: text index (parser-incompatible Zig version)_\n\n`;
+    markdown += `Match: ${best.path}:${best.line}\n\n`;
+    markdown += "```zig\n";
+    markdown += snippet;
+    markdown += "\n```\n";
+    return markdown;
+}
 function buildDeclEmbeddingText(decl) {
     const category = wasm_exports.categorize_decl(decl, 0);
     const fqn = fullyQualifiedName(decl);
@@ -832,6 +1027,14 @@ function buildDeclEmbeddingText(decl) {
     const text = stripMarkdown(`${fqn}\n${name}\n${proto}\n${typeInfo}\n${docs}\n${source}`).slice(0, 4000);
     return { decl, fqn, text };
 }
+function tryBuildDeclEmbeddingText(decl) {
+    try {
+        return buildDeclEmbeddingText(decl);
+    }
+    catch {
+        return null;
+    }
+}
 async function getEmbeddingCachePath(zigVersion, docSource, model) {
     const envPathsMod = await import("env-paths");
     const path = await import("node:path");
@@ -891,9 +1094,14 @@ async function getOrBuildEmbeddingCache(wasmPath, stdSources, options) {
         inMemoryEmbeddingCache = existing;
         return existing;
     }
-    await initWasmRuntime(wasmPath, stdSources);
     const decls = collectDeclsForEmbeddings();
-    const docs = decls.map((decl) => buildDeclEmbeddingText(decl)).filter((doc) => doc.text.length > 0);
+    const docs = [];
+    for (let i = 0; i < decls.length; i++) {
+        const doc = tryBuildDeclEmbeddingText(decls[i]);
+        if (doc && doc.text.length > 0) {
+            docs.push(doc);
+        }
+    }
     if (docs.length === 0) {
         return null;
     }
@@ -929,7 +1137,12 @@ function buildHybridRanking(lexicalDecls, semanticDecls, maxResults) {
         .map(([decl]) => decl);
 }
 export async function searchStdLib(wasmPath, stdSources, query, limit = 20, options = {}) {
-    await initWasmRuntime(wasmPath, stdSources);
+    try {
+        await initWasmRuntime(wasmPath, stdSources);
+    }
+    catch {
+        return fallbackSearchStdLib(stdSources, query, limit);
+    }
     const ignoreCase = query.toLowerCase() === query;
     const lexicalResults = Array.from(executeQuery(query, ignoreCase));
     let mergedResults = lexicalResults;
@@ -968,7 +1181,12 @@ export async function searchStdLib(wasmPath, stdSources, query, limit = 20, opti
     return markdown;
 }
 export async function getStdLibItem(wasmPath, stdSources, name, getSourceFile = false) {
-    await initWasmRuntime(wasmPath, stdSources);
+    try {
+        await initWasmRuntime(wasmPath, stdSources);
+    }
+    catch {
+        return fallbackGetStdLibItem(stdSources, name, getSourceFile);
+    }
     const exports = wasm_exports;
     const decl_index = findDecl(name);
     if (decl_index === null) {

package/dist/tools.js

@@ -67,15 +67,26 @@ function getBuiltinFunctionTool(builtinFunctions) {
                     ],
                 };
             }
+            const queryBare = queryLower.replace(/@/g, "");
+            const queryWords = queryBare.split(/\s+/).filter(Boolean);
             const scoredFunctions = builtinFunctions.map((fn) => {
                 const funcLower = fn.func.toLowerCase();
+                const funcBare = funcLower.replace(/^@/, "");
                 let score = 0;
-                if (funcLower === queryLower)
+                if (funcLower === queryLower || funcBare === queryBare)
                     score += 1000;
                 else if (funcLower.startsWith(queryLower))
                     score += 500;
                 else if (funcLower.includes(queryLower))
                     score += 300;
+                if (score === 0 && queryWords.length > 0) {
+                    const searchable = `${funcBare} ${fn.docs.toLowerCase()} ${fn.signature.toLowerCase()}`;
+                    const wordHits = queryWords.filter((w) => searchable.includes(w)).length;
+                    if (wordHits === queryWords.length)
+                        score += 200;
+                    else if (wordHits > 0)
+                        score += wordHits * 60;
+                }
                 if (score > 0)
                     score += Math.max(0, 50 - fn.func.length);
                 return { ...fn, score };

package/dist/voyage.js

@@ -6,7 +6,7 @@ export function getVoyageConfig() {
     }
     return {
         apiKey,
-        model: env?.VOYAGE_MODEL?.trim() || "voyage-3-lite",
+        model: env?.VOYAGE_MODEL?.trim() || "voyage-code-3",
     };
 }
 async function embedBatch(input, config, inputType) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zigsm",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "type": "module",
   "bin": {
     "zsm": "dist/mcp.js"
@@ -24,14 +24,14 @@
   "description": "MCP server that provides up-to-date documentation for the Zig programming language standard library and builtin functions.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/zig-wasm/zig-mcp.git"
+    "url": "git+https://github.com/pokeylooted/zsm.git"
   },
   "keywords": [
     "mcp",
     "modelcontextprotocol",
     "zig",
     "ziglang",
-    "zig-docs",
+    "zsm",
     "cli"
   ],
   "dependencies": {