distill-mcp 0.6.0-beta

package/dist/tools/lazy-mcp.js

@@ -0,0 +1,151 @@
+/**
+ * Lazy MCP - Pattern for 95% token reduction
+ *
+ * Implements the lazy-mcp pattern where only 2 meta-tools are exposed:
+ * - browse_tools: Navigate the tool hierarchy
+ * - run_tool: Execute any tool by name
+ *
+ * This reduces initial context from ~15,000 tokens to ~800 tokens.
+ *
+ * @see https://github.com/voicetreelab/lazy-mcp
+ */
+import { getDynamicLoader, TOOL_CATALOG } from "./dynamic-loader.js";
+// ============================================================================
+// browse_tools - Navigate the tool hierarchy
+// ============================================================================
+const browseToolsSchema = {
+    type: "object",
+    properties: {
+        category: {
+            type: "string",
+            enum: ["compress", "analyze", "logs", "code", "pipeline"],
+        },
+    },
+};
+async function executeBrowseTools(args) {
+    const { category } = args;
+    const loader = getDynamicLoader();
+    if (!category) {
+        // Return category overview with tool counts
+        const categories = new Map();
+        for (const tool of TOOL_CATALOG) {
+            if (tool.category !== "core") {
+                categories.set(tool.category, (categories.get(tool.category) || 0) + 1);
+            }
+        }
+        const lines = ["ctxopt/", ""];
+        for (const [cat, count] of categories) {
+            lines.push(`  ${cat}/ (${count} tools)`);
+        }
+        lines.push("");
+        lines.push("Use category to list tools. Use run_tool to execute.");
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    // Return tools in category
+    const tools = loader.getToolsByCategory(category);
+    if (tools.length === 0) {
+        return {
+            content: [{ type: "text", text: `No tools in category: ${category}` }],
+        };
+    }
+    const lines = [`ctxopt/${category}/`, ""];
+    for (const tool of tools) {
+        lines.push(`  ${tool.name}: ${tool.description}`);
+    }
+    lines.push("");
+    const firstTool = tools[0];
+    if (firstTool) {
+        lines.push(`run_tool name="${firstTool.name}" args={...}`);
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+}
+export const browseToolsTool = {
+    name: "browse_tools",
+    description: "List tool categories or tools in a category. Omit category for overview.",
+    inputSchema: browseToolsSchema,
+    execute: executeBrowseTools,
+};
+// ============================================================================
+// run_tool - Execute any tool by name
+// ============================================================================
+const runToolSchema = {
+    type: "object",
+    properties: {
+        name: { type: "string" },
+        args: { type: "object" },
+    },
+    required: ["name"],
+};
+// Registry reference for tool execution (set by server)
+let registryRef = null;
+/**
+ * Set the registry reference for tool execution
+ * Called by the server during initialization
+ */
+export function setLazyMcpRegistry(registry) {
+    registryRef = registry;
+}
+async function executeRunTool(args) {
+    const { name, args: toolArgs = {} } = args;
+    // Check if tool exists in catalog
+    const toolMeta = TOOL_CATALOG.find((t) => t.name === name);
+    if (!toolMeta) {
+        const available = TOOL_CATALOG.map((t) => t.name).join(", ");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Unknown tool: ${name}\n\nAvailable: ${available}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Load tool if not already loaded
+    const loader = getDynamicLoader();
+    if (!loader.isLoaded(name)) {
+        await loader.loadByNames([name]);
+    }
+    // Execute via registry (which applies middleware)
+    if (!registryRef) {
+        // Fallback: direct execution without middleware
+        const loadedTools = loader.getLoadedTools();
+        const tool = loadedTools.find((t) => t.name === name);
+        if (!tool) {
+            return {
+                content: [{ type: "text", text: `Failed to load tool: ${name}` }],
+                isError: true,
+            };
+        }
+        return tool.execute(toolArgs);
+    }
+    // Use registry for proper middleware chain
+    const result = await registryRef.execute(name, toolArgs);
+    return {
+        content: result.content,
+        isError: result.isError,
+    };
+}
+export const runToolTool = {
+    name: "run_tool",
+    description: "Execute a tool by name. Use browse_tools to find tools.",
+    inputSchema: runToolSchema,
+    execute: executeRunTool,
+};
+// ============================================================================
+// Lazy MCP meta-tools collection
+// ============================================================================
+export const lazyMcpTools = [browseToolsTool, runToolTool];
+/**
+ * Calculate token savings from lazy loading
+ */
+export function calculateLazySavings() {
+    // Approximate token counts based on schema sizes
+    const lazyTokens = 150; // 2 simple tools with minimal schemas
+    const fullTokens = TOOL_CATALOG.length * 100; // ~100 tokens per tool definition
+    return {
+        lazyTokens,
+        fullTokens,
+        savingsPercent: Math.round((1 - lazyTokens / fullTokens) * 100),
+    };
+}

package/dist/tools/lazy-mcp.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Lazy MCP Tests
+ *
+ * Tests for the lazy-mcp pattern implementation:
+ * - browse_tools meta-tool for navigating tool hierarchy
+ * - run_tool meta-tool for executing tools by name
+ * - Token savings from lazy loading (95%+ reduction)
+ */
+export {};
+//# sourceMappingURL=lazy-mcp.test.d.ts.map

package/dist/tools/lazy-mcp.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-mcp.test.d.ts","sourceRoot":"","sources":["../../src/tools/lazy-mcp.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/tools/lazy-mcp.test.js

@@ -0,0 +1,172 @@
+/**
+ * Lazy MCP Tests
+ *
+ * Tests for the lazy-mcp pattern implementation:
+ * - browse_tools meta-tool for navigating tool hierarchy
+ * - run_tool meta-tool for executing tools by name
+ * - Token savings from lazy loading (95%+ reduction)
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import { browseToolsTool, runToolTool, lazyMcpTools, setLazyMcpRegistry, calculateLazySavings, } from "./lazy-mcp.js";
+import { resetDynamicLoader, TOOL_CATALOG } from "./dynamic-loader.js";
+import { countTokens } from "../utils/token-counter.js";
+describe("Lazy MCP Pattern", () => {
+    beforeEach(() => {
+        resetDynamicLoader();
+    });
+    describe("browse_tools", () => {
+        it("should list categories when no category specified", async () => {
+            const result = await browseToolsTool.execute({});
+            const text = result.content[0]?.text ?? "";
+            expect(text).toContain("ctxopt/");
+            expect(text).toContain("compress/");
+            expect(text).toContain("analyze/");
+            expect(text).toContain("logs/");
+            expect(text).toContain("code/");
+            expect(text).toContain("pipeline/");
+        });
+        it("should list tools in a specific category", async () => {
+            const result = await browseToolsTool.execute({ category: "compress" });
+            const text = result.content[0]?.text ?? "";
+            expect(text).toContain("ctxopt/compress/");
+            expect(text).toContain("compress_context");
+            expect(text).toContain("semantic_compress");
+        });
+        it("should show tool count per category", async () => {
+            const result = await browseToolsTool.execute({});
+            const text = result.content[0]?.text ?? "";
+            // Should show something like "compress/ (4 tools)"
+            expect(text).toMatch(/\(\d+ tools?\)/);
+        });
+        it("should handle invalid category", async () => {
+            const result = await browseToolsTool.execute({ category: "invalid" });
+            const text = result.content[0]?.text ?? "";
+            expect(text).toContain("No tools in category");
+        });
+    });
+    describe("run_tool", () => {
+        it("should execute a tool by name", async () => {
+            const result = await runToolTool.execute({
+                name: "auto_optimize",
+                args: { content: "test content that is long enough to process" },
+            });
+            // Should return tool output (not error about unknown tool)
+            expect(result.isError).not.toBe(true);
+        });
+        it("should return error for unknown tool", async () => {
+            const result = await runToolTool.execute({
+                name: "nonexistent_tool",
+                args: {},
+            });
+            const text = result.content[0]?.text ?? "";
+            expect(result.isError).toBe(true);
+            expect(text).toContain("Unknown tool");
+        });
+        it("should list available tools on error", async () => {
+            const result = await runToolTool.execute({
+                name: "bad_tool",
+                args: {},
+            });
+            const text = result.content[0]?.text ?? "";
+            expect(text).toContain("Available:");
+            expect(text).toContain("auto_optimize");
+        });
+        it("should pass args to the tool", async () => {
+            const result = await runToolTool.execute({
+                name: "auto_optimize",
+                args: {
+                    content: "Error: Something went wrong\nError: Something went wrong",
+                    hint: "errors",
+                },
+            });
+            expect(result.isError).not.toBe(true);
+        });
+    });
+    describe("lazyMcpTools collection", () => {
+        it("should contain exactly 2 tools", () => {
+            expect(lazyMcpTools).toHaveLength(2);
+        });
+        it("should contain browse_tools and run_tool", () => {
+            const names = lazyMcpTools.map((t) => t.name);
+            expect(names).toContain("browse_tools");
+            expect(names).toContain("run_tool");
+        });
+        it("should have minimal schemas", () => {
+            for (const tool of lazyMcpTools) {
+                const schemaStr = JSON.stringify(tool.inputSchema);
+                const tokens = countTokens(schemaStr);
+                expect(tokens).toBeLessThan(100);
+            }
+        });
+    });
+    describe("Token savings", () => {
+        it("should calculate significant savings", () => {
+            const savings = calculateLazySavings();
+            expect(savings.savingsPercent).toBeGreaterThan(80);
+            expect(savings.lazyTokens).toBeLessThan(savings.fullTokens);
+            console.log(`  Lazy tokens: ${savings.lazyTokens}, Full tokens: ${savings.fullTokens}, Savings: ${savings.savingsPercent}%`);
+        });
+        it("should use fewer tokens than core loading", async () => {
+            // Calculate lazy mode tokens
+            const lazyTokens = lazyMcpTools.reduce((sum, tool) => {
+                const serialized = JSON.stringify({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                });
+                return sum + countTokens(serialized);
+            }, 0);
+            // Calculate full catalog tokens (simulated)
+            const fullTokens = TOOL_CATALOG.length * 80; // ~80 tokens per tool
+            const savingsPercent = Math.round((1 - lazyTokens / fullTokens) * 100);
+            expect(savingsPercent).toBeGreaterThan(90);
+            console.log(`  Lazy: ${lazyTokens} tokens, Full: ${fullTokens} tokens, Savings: ${savingsPercent}%`);
+        });
+    });
+    describe("Registry integration", () => {
+        it("should work with custom registry", async () => {
+            let executedTool = "";
+            let executedArgs = null;
+            setLazyMcpRegistry({
+                execute: async (name, args) => {
+                    executedTool = name;
+                    executedArgs = args;
+                    return { content: [{ type: "text", text: "mocked result" }] };
+                },
+            });
+            const result = await runToolTool.execute({
+                name: "auto_optimize",
+                args: { content: "test" },
+            });
+            expect(executedTool).toBe("auto_optimize");
+            expect(executedArgs).toEqual({ content: "test" });
+            expect(result.content[0]?.text).toBe("mocked result");
+        });
+    });
+});
+describe("Lazy mode comparison", () => {
+    beforeEach(() => {
+        resetDynamicLoader();
+    });
+    it("should show lazy vs core vs all token usage", async () => {
+        // Lazy mode: 2 tools
+        const lazyTokens = lazyMcpTools.reduce((sum, tool) => {
+            const serialized = JSON.stringify({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+            });
+            return sum + countTokens(serialized);
+        }, 0);
+        // Simulated core mode: ~4 tools
+        const coreTokens = 4 * 80;
+        // Simulated all mode: all catalog tools
+        const allTokens = TOOL_CATALOG.length * 80;
+        console.log(`  Mode comparison:`);
+        console.log(`    lazy: ${lazyTokens} tokens (2 tools)`);
+        console.log(`    core: ~${coreTokens} tokens (4 tools)`);
+        console.log(`    all:  ~${allTokens} tokens (${TOOL_CATALOG.length} tools)`);
+        expect(lazyTokens).toBeLessThan(coreTokens);
+        expect(coreTokens).toBeLessThan(allTokens);
+    });
+});

package/dist/tools/multifile-compress.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Multi-File Compress Tool
+ *
+ * Compresses multiple files with cross-file deduplication,
+ * extracting shared imports and types.
+ */
+import type { ToolDefinition } from "./registry.js";
+export declare const multifileCompressSchema: {
+    type: "object";
+    properties: {
+        patterns: {
+            type: string;
+            items: {
+                type: string;
+            };
+            description: string;
+        };
+        strategy: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        maxTokens: {
+            type: string;
+            description: string;
+        };
+        action: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+    };
+    required: string[];
+};
+export declare const multifileCompressTool: ToolDefinition;
+//# sourceMappingURL=multifile-compress.d.ts.map

package/dist/tools/multifile-compress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multifile-compress.d.ts","sourceRoot":"","sources":["../../src/tools/multifile-compress.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAepD,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;CAwBnC,CAAC;AAuPF,eAAO,MAAM,qBAAqB,EAAE,cAMnC,CAAC"}

package/dist/tools/multifile-compress.js

@@ -0,0 +1,223 @@
+/**
+ * Multi-File Compress Tool
+ *
+ * Compresses multiple files with cross-file deduplication,
+ * extracting shared imports and types.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { z } from "zod";
+import { compressMultiFile, extractSharedElements, createChunks, } from "../compressors/multifile.js";
+import { detectLanguageFromPath } from "../utils/language-detector.js";
+import { getSessionTracker } from "../analytics/session-tracker.js";
+import { getOutputConfig } from "../config/output-config.js";
+import { serializeResultToToon, } from "../utils/toon-serializer.js";
+export const multifileCompressSchema = {
+    type: "object",
+    properties: {
+        patterns: {
+            type: "array",
+            items: { type: "string" },
+            description: "Glob patterns for files to compress (e.g., [\"src/**/*.ts\"])",
+        },
+        strategy: {
+            type: "string",
+            enum: ["deduplicate", "skeleton", "smart-chunk"],
+            description: "Compression strategy: deduplicate (default), skeleton, or smart-chunk",
+        },
+        maxTokens: {
+            type: "number",
+            description: "Maximum tokens for output (default: 50000)",
+        },
+        action: {
+            type: "string",
+            enum: ["compress", "extract-shared", "chunk"],
+            description: "Action: compress (default), extract-shared, or chunk",
+        },
+    },
+    required: ["patterns"],
+};
+const inputSchema = z.object({
+    patterns: z.array(z.string()).min(1),
+    strategy: z
+        .enum(["deduplicate", "skeleton", "smart-chunk"])
+        .optional()
+        .default("deduplicate"),
+    maxTokens: z.number().optional().default(50000),
+    action: z
+        .enum(["compress", "extract-shared", "chunk"])
+        .optional()
+        .default("compress"),
+});
+/**
+ * Find files matching glob patterns (simple implementation)
+ */
+function findFiles(patterns, workingDir) {
+    const files = [];
+    const seen = new Set();
+    function walkDir(dir, pattern) {
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                const relativePath = path.relative(workingDir, fullPath);
+                if (entry.isDirectory()) {
+                    if (!entry.name.startsWith(".") && entry.name !== "node_modules") {
+                        walkDir(fullPath, pattern);
+                    }
+                }
+                else if (entry.isFile()) {
+                    if (matchesPattern(relativePath, pattern) && !seen.has(relativePath)) {
+                        seen.add(relativePath);
+                        files.push(relativePath);
+                    }
+                }
+            }
+        }
+        catch {
+            // Skip directories we can't read
+        }
+    }
+    for (const pattern of patterns) {
+        walkDir(workingDir, pattern);
+    }
+    return files.slice(0, 100); // Limit results
+}
+/**
+ * Simple glob pattern matching
+ */
+function matchesPattern(filePath, pattern) {
+    // Handle **/*.ext patterns
+    if (pattern.includes("**")) {
+        const ext = pattern.split(".").pop();
+        if (ext) {
+            return filePath.endsWith(`.${ext}`);
+        }
+    }
+    // Handle *.ext patterns
+    if (pattern.startsWith("*.")) {
+        const ext = pattern.slice(1);
+        return filePath.endsWith(ext);
+    }
+    // Direct path match
+    return filePath.includes(pattern.replace(/\*/g, ""));
+}
+/**
+ * Load file contents
+ */
+function loadFiles(filePaths, workingDir) {
+    const files = [];
+    for (const filePath of filePaths) {
+        try {
+            const fullPath = path.join(workingDir, filePath);
+            const content = fs.readFileSync(fullPath, "utf-8");
+            const language = detectLanguageFromPath(filePath);
+            files.push({
+                path: filePath,
+                content,
+                language,
+            });
+        }
+        catch {
+            // Skip files that can't be read
+        }
+    }
+    return files;
+}
+/**
+ * Format output for display
+ */
+function formatOutput(result, action) {
+    const config = getOutputConfig();
+    if (config.mode === "toon" || config.useToon) {
+        const schema = {
+            name: action === "chunk" ? "Chunks" : "MultiFileCompress",
+            fields: ["compressed", "filesIncluded", "sharedElements", "stats"],
+        };
+        return serializeResultToToon(result, schema, {
+            verbosity: config.verbosity,
+            includeStats: config.includeStats,
+        });
+    }
+    // Standard format
+    const parts = [];
+    if (result.stats) {
+        parts.push(`[MultiFile] ${result.stats.originalTokens}→${result.stats.compressedTokens} tokens (-${result.stats.reductionPercent}%)`);
+        parts.push(`Files: ${result.stats.filesProcessed}, Deduplicated: ${result.stats.deduplicatedItems}`);
+        parts.push("");
+    }
+    if (result.compressed) {
+        parts.push(result.compressed);
+    }
+    if (result.chunks) {
+        parts.push(`Chunks: ${result.chunks.length}`);
+        for (const chunk of result.chunks) {
+            parts.push(`  ${chunk.id}: ${chunk.files.length} files, ${chunk.tokens} tokens`);
+        }
+    }
+    return parts.join("\n");
+}
+/**
+ * Execute multi-file compress tool
+ */
+async function executeMultifileCompress(args) {
+    const input = inputSchema.parse(args);
+    const workingDir = process.cwd();
+    // Find files matching patterns
+    const filePaths = findFiles(input.patterns, workingDir);
+    if (filePaths.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `No files found matching patterns: ${input.patterns.join(", ")}`,
+                },
+            ],
+        };
+    }
+    // Load file contents
+    const files = loadFiles(filePaths, workingDir);
+    let output;
+    switch (input.action) {
+        case "extract-shared": {
+            const shared = extractSharedElements(files);
+            output = formatOutput({
+                sharedElements: shared,
+                stats: {
+                    originalTokens: 0,
+                    compressedTokens: 0,
+                    filesProcessed: files.length,
+                    deduplicatedItems: shared.imports.length + shared.types.length,
+                    reductionPercent: 0,
+                },
+            }, "extract-shared");
+            break;
+        }
+        case "chunk": {
+            const chunks = createChunks(files, input.maxTokens / 3);
+            output = formatOutput({ chunks }, "chunk");
+            break;
+        }
+        case "compress":
+        default: {
+            const result = compressMultiFile(files, {
+                strategy: input.strategy,
+                maxTokens: input.maxTokens,
+            });
+            // Track usage
+            const tokensSaved = result.stats.originalTokens - result.stats.compressedTokens;
+            getSessionTracker().recordInvocation("multifile_compress", result.stats.originalTokens, result.stats.compressedTokens, tokensSaved, 0);
+            output = formatOutput(result, "compress");
+            break;
+        }
+    }
+    return {
+        content: [{ type: "text", text: output }],
+    };
+}
+export const multifileCompressTool = {
+    name: "multifile_compress",
+    description: "Compress multiple files with cross-file deduplication. Extracts shared imports/types. Strategies: deduplicate, skeleton, smart-chunk.",
+    inputSchema: multifileCompressSchema,
+    execute: executeMultifileCompress,
+};

package/dist/tools/optimization-tips.d.ts

@@ -0,0 +1,18 @@
+import type { ServerConfig } from "../server";
+export declare const optimizationTipsSchema: {
+    type: "object";
+    properties: {
+        focus: {
+            type: string;
+            enum: string[];
+        };
+    };
+    required: never[];
+};
+export declare function optimizationTips(args: unknown, _config: ServerConfig): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=optimization-tips.d.ts.map

package/dist/tools/optimization-tips.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimization-tips.d.ts","sourceRoot":"","sources":["../../src/tools/optimization-tips.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,eAAO,MAAM,sBAAsB;;;;;;;;;CAMlC,CAAC;AAyHF,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAc7D"}