zigsm 1.4.0

package/dist/tools.js

@@ -0,0 +1,225 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import z from "zod";
+import { getStdLibItem, searchStdLib } from "./std.js";
+import { cosineSimilarity, embedTexts, getVoyageConfig } from "./voyage.js";
+let builtinEmbeddingState = null;
+function builtinEmbeddingText(fn) {
+    return `${fn.func}\n${fn.signature}\n${fn.docs}`;
+}
+async function getBuiltinEmbeddings(functions) {
+    const voyage = getVoyageConfig();
+    if (!voyage) {
+        return null;
+    }
+    if (builtinEmbeddingState && builtinEmbeddingState.functions === functions) {
+        return builtinEmbeddingState;
+    }
+    const vectors = await embedTexts(functions.map((fn) => builtinEmbeddingText(fn)), voyage, "document");
+    const state = {
+        functions,
+        vectors,
+    };
+    builtinEmbeddingState = state;
+    return state;
+}
+function createListBuiltinFunctionsTool(builtinFunctions) {
+    return {
+        name: "list_builtin_functions",
+        config: {
+            description: "Lists all available Zig builtin functions. Builtin functions are provided by the compiler and are prefixed with '@'. The comptime keyword on a parameter means that the parameter must be known at compile time. Use this to discover what functions are available, then use 'get_builtin_function' to get detailed documentation.",
+        },
+        handler: async () => {
+            const functionList = builtinFunctions.map((fn) => `- ${fn.signature}`).join("\n");
+            const message = `Available ${builtinFunctions.length} builtin functions:\n\n${functionList}`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: message,
+                    },
+                ],
+            };
+        },
+    };
+}
+function getBuiltinFunctionTool(builtinFunctions) {
+    return {
+        name: "get_builtin_function",
+        config: {
+            description: "Search for Zig builtin functions by name and get their documentation, signatures, and usage information. Returns all matching functions ranked by relevance.",
+            inputSchema: {
+                function_name: z
+                    .string()
+                    .min(1, "Query cannot be empty")
+                    .describe("Function name or keywords (e.g., '@addWithOverflow', 'overflow', 'atomic')"),
+            },
+        },
+        handler: async ({ function_name }) => {
+            const queryLower = function_name.toLowerCase().trim();
+            if (!queryLower) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Please provide a function name or keywords. Try searching for a function name like '@addWithOverflow' or keywords like 'overflow' or 'atomic'.",
+                        },
+                    ],
+                };
+            }
+            const scoredFunctions = builtinFunctions.map((fn) => {
+                const funcLower = fn.func.toLowerCase();
+                let score = 0;
+                if (funcLower === queryLower)
+                    score += 1000;
+                else if (funcLower.startsWith(queryLower))
+                    score += 500;
+                else if (funcLower.includes(queryLower))
+                    score += 300;
+                if (score > 0)
+                    score += Math.max(0, 50 - fn.func.length);
+                return { ...fn, score };
+            });
+            try {
+                const voyage = getVoyageConfig();
+                if (voyage) {
+                    const embeddingState = await getBuiltinEmbeddings(builtinFunctions);
+                    if (embeddingState && embeddingState.vectors.length > 0) {
+                        const queryVector = (await embedTexts([function_name], voyage, "query"))[0];
+                        for (let i = 0; i < scoredFunctions.length; i++) {
+                            const semantic = cosineSimilarity(queryVector, embeddingState.vectors[i]);
+                            scoredFunctions[i].score += semantic * 220;
+                        }
+                    }
+                }
+            }
+            catch {
+            }
+            const rankedFunctions = scoredFunctions.filter((fn) => fn.score > 0);
+            rankedFunctions.sort((a, b) => b.score - a.score);
+            if (rankedFunctions.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No builtin functions found matching "${function_name}". Try using 'list_builtin_functions' to see available functions, or refine your search terms.`,
+                        },
+                    ],
+                };
+            }
+            const results = rankedFunctions
+                .map((fn) => `**${fn.func}**\n\`\`\`zig\n${fn.signature}\n\`\`\`\n\n${fn.docs}`)
+                .join("\n\n---\n\n");
+            const message = rankedFunctions.length === 1
+                ? results
+                : `Found ${rankedFunctions.length} matching functions:\n\n${results}`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: message,
+                    },
+                ],
+            };
+        },
+    };
+}
+function searchStdLibTool(wasmPath, stdSources, options) {
+    return {
+        name: "search_std_lib",
+        config: {
+            description: "Search the Zig standard library for functions, types, namespaces, and other declarations. Returns detailed markdown documentation for each matching item. Use this to explore the standard library and discover available functionality. Supports fuzzy matching and returns results ranked by relevance.",
+            inputSchema: {
+                query: z
+                    .string()
+                    .min(1, "Search query cannot be empty")
+                    .describe("Search terms to find in the standard library (e.g., 'ArrayList', 'print', 'allocator', 'HashMap')"),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .default(20)
+                    .describe("Maximum number of results to return (default: 20)"),
+            },
+        },
+        handler: async ({ query, limit = 20 }) => {
+            try {
+                const markdown = await searchStdLib(wasmPath, stdSources, query, limit, {
+                    zigVersion: options.zigVersion,
+                    docSource: options.docSource,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: markdown,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error searching standard library: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                };
+            }
+        },
+    };
+}
+function getStdLibItemTool(wasmPath, stdSources) {
+    return {
+        name: "get_std_lib_item",
+        config: {
+            description: "Get detailed documentation for a specific item in the Zig standard library. Provide the fully qualified name (e.g., 'std.ArrayList', 'std.debug.print', 'std.mem.Allocator') to get comprehensive documentation including function signatures, parameters, return types, error sets, example usage, and optionally source code.",
+            inputSchema: {
+                name: z
+                    .string()
+                    .min(1, "Item name cannot be empty")
+                    .describe("Fully qualified name of the standard library item (e.g., 'std.ArrayList', 'std.debug.print', 'std.mem.Allocator')"),
+                get_source_file: z
+                    .boolean()
+                    .default(false)
+                    .describe("Return the entire source file where this item is implemented (default: false - shows detailed documentation with item source code only)"),
+            },
+        },
+        handler: async ({ name, get_source_file = false, }) => {
+            try {
+                const markdown = await getStdLibItem(wasmPath, stdSources, name, get_source_file);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: markdown,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error getting standard library item: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                };
+            }
+        },
+    };
+}
+export async function registerAllTools(mcpServer, builtinFunctions, stdSources, options) {
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    const wasmPath = path.join(currentDir, "main.wasm");
+    const listBuiltinFunctionsTool = createListBuiltinFunctionsTool(builtinFunctions);
+    mcpServer.registerTool(listBuiltinFunctionsTool.name, listBuiltinFunctionsTool.config, listBuiltinFunctionsTool.handler);
+    const getBuiltinFunction = getBuiltinFunctionTool(builtinFunctions);
+    mcpServer.registerTool(getBuiltinFunction.name, getBuiltinFunction.config, getBuiltinFunction.handler);
+    const stdLibSearch = searchStdLibTool(wasmPath, stdSources, options);
+    mcpServer.registerTool(stdLibSearch.name, stdLibSearch.config, stdLibSearch.handler);
+    const stdLibItem = getStdLibItemTool(wasmPath, stdSources);
+    mcpServer.registerTool(stdLibItem.name, stdLibItem.config, stdLibItem.handler);
+}

package/dist/voyage.js

@@ -0,0 +1,88 @@
+export function getVoyageConfig() {
+    const env = globalThis.process?.env;
+    const apiKey = env?.VOYAGE_API_KEY?.trim();
+    if (!apiKey) {
+        return null;
+    }
+    return {
+        apiKey,
+        model: env?.VOYAGE_MODEL?.trim() || "voyage-3-lite",
+    };
+}
+async function embedBatch(input, config, inputType) {
+    const maxAttempts = 3;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const response = await fetch("https://api.voyageai.com/v1/embeddings", {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${config.apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    model: config.model,
+                    input,
+                    input_type: inputType,
+                }),
+                signal: AbortSignal.timeout(15_000),
+            });
+            if (!response.ok) {
+                const body = await response.text();
+                const retriable = response.status === 429 || response.status >= 500;
+                if (retriable && attempt < maxAttempts) {
+                    await new Promise((resolve) => setTimeout(resolve, 300 * attempt));
+                    continue;
+                }
+                throw new Error(`Voyage embeddings failed: ${response.status} ${response.statusText} ${body}`);
+            }
+            const json = (await response.json());
+            if (!Array.isArray(json.data) || json.data.length !== input.length) {
+                throw new Error("Voyage embeddings returned an invalid response shape");
+            }
+            return json.data.map((item) => item.embedding);
+        }
+        catch (error) {
+            if (attempt < maxAttempts) {
+                await new Promise((resolve) => setTimeout(resolve, 300 * attempt));
+                continue;
+            }
+            if (error instanceof Error) {
+                throw error;
+            }
+            throw new Error(String(error));
+        }
+    }
+    throw new Error("Voyage embeddings failed");
+}
+export async function embedTexts(texts, config, inputType) {
+    const batchSize = 64;
+    const vectors = [];
+    for (let i = 0; i < texts.length; i += batchSize) {
+        const batch = texts.slice(i, i + batchSize);
+        const batchVectors = await embedBatch(batch, config, inputType);
+        vectors.push(...batchVectors);
+    }
+    return vectors;
+}
+export function dot(a, b) {
+    const len = Math.min(a.length, b.length);
+    let sum = 0;
+    for (let i = 0; i < len; i++) {
+        sum += a[i] * b[i];
+    }
+    return sum;
+}
+export function magnitude(a) {
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+        sum += a[i] * a[i];
+    }
+    return Math.sqrt(sum);
+}
+export function cosineSimilarity(a, b) {
+    const denom = magnitude(a) * magnitude(b);
+    if (denom === 0) {
+        return 0;
+    }
+    return dot(a, b) / denom;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "zigsm",
+  "version": "1.4.0",
+  "type": "module",
+  "bin": {
+    "zsm": "dist/mcp.js"
+  },
+  "main": "dist/mcp.js",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun run build && bunx @modelcontextprotocol/inspector bun dist/mcp.js",
+    "build": "zig build --release && tsc && cp zig-out/main.wasm mcp/index.html dist/",
+    "prepublishOnly": "npm run build",
+    "lint": "bunx biome check",
+    "lint:fix": "bunx biome check --write",
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Andrey Ryapov <dev@zigwasm.org> (https://zigwasm.org/)",
+  "license": "MIT",
+  "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"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "zig",
+    "ziglang",
+    "zig-docs",
+    "cli"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.15.0",
+    "cheerio": "^1.1.0",
+    "env-paths": "^3.0.0",
+    "zod": "^3.25.75"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.1.1",
+    "@types/bun": "latest",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18.0.0"
+  }
+}