distill-mcp 0.6.0-beta

package/dist/tools/optimization-tips.js

@@ -0,0 +1,133 @@
+import { z } from "zod";
+export const optimizationTipsSchema = {
+    type: "object",
+    properties: {
+        focus: { type: "string", enum: ["general", "prompts", "context", "cost", "performance"] },
+    },
+    required: [],
+};
+const inputSchema = z.object({
+    focus: z
+        .enum(["general", "prompts", "context", "cost", "performance"])
+        .optional()
+        .default("general"),
+});
+const TIPS = {
+    general: `## Context Engineering Best Practices
+
+### 1. Structure Your Context
+- Place long documents at the **top** of your prompt
+- Put instructions and queries **after** the context
+- Use clear section delimiters (XML tags, markdown headers)
+
+### 2. Be Specific
+- Tell the model exactly what format you want
+- Provide examples of desired output (few-shot prompting)
+- Avoid ambiguous instructions
+
+### 3. Optimize Token Usage
+- Remove redundant information between messages
+- Summarize conversation history for long sessions
+- Use system prompts for reusable instructions
+
+### 4. Monitor and Iterate
+- Track token usage per request
+- A/B test different prompt structures
+- Measure output quality vs token cost`,
+    prompts: `## Prompt Optimization Tips
+
+### System Prompts
+- Keep system prompts concise but complete
+- Extract role definitions to system prompt (saves input tokens)
+- Avoid repeating instructions in every user message
+
+### User Messages
+- Front-load the most important information
+- Use structured formats (JSON, XML) for complex inputs
+- Reference previous context instead of repeating it
+
+### Few-Shot Examples
+- 2-3 examples usually suffice
+- Choose diverse, representative examples
+- Format examples exactly like expected output
+
+### Prompt Templates
+- Create reusable templates for common tasks
+- Use placeholders for variable content
+- Test templates with edge cases`,
+    context: `## Context Management Tips
+
+### Long Conversations
+- Summarize every 5-10 messages
+- Keep only relevant message history
+- Use a "memory" system prompt for key facts
+
+### RAG (Retrieval-Augmented Generation)
+- Retrieve only the most relevant chunks
+- Limit context to 3-5 relevant documents
+- Order by relevance, most relevant first
+
+### Code Context
+- Include only relevant files/functions
+- Use file paths as references instead of full content
+- Summarize unchanged files
+
+### Multi-Agent Patterns
+- Split context across specialized agents
+- Each agent handles specific sub-tasks
+- Reduces per-agent context size`,
+    cost: `## Cost Optimization Tips
+
+### Model Selection
+- Use Haiku for simple tasks (5x cheaper than Sonnet)
+- Reserve Opus for complex reasoning
+- Route based on task complexity
+
+### Caching
+- Cache common prompts and responses
+- Use prompt caching for repeated prefixes
+- Anthropic prompt caching: 90% discount on cached tokens
+
+### Batch Processing
+- Use Batch API for non-urgent requests (50% discount)
+- Group similar requests together
+- Process during off-peak hours
+
+### Output Optimization
+- Set max_tokens appropriately
+- Request concise responses when possible
+- Output tokens cost 5x more than input`,
+    performance: `## Performance Optimization Tips
+
+### Latency Reduction
+- Use streaming for better perceived performance
+- Pre-compute and cache common responses
+- Minimize round-trips with comprehensive prompts
+
+### Throughput
+- Use async/parallel requests when possible
+- Implement request queuing for rate limits
+- Monitor and respect API limits
+
+### Reliability
+- Implement exponential backoff for retries
+- Handle streaming errors gracefully
+- Cache responses for idempotent requests
+
+### Context Window
+- Stay under 50% of max context for best performance
+- Performance degrades significantly above 80%
+- Consider chunking for very long documents`,
+};
+export async function optimizationTips(args, _config) {
+    const { focus } = inputSchema.parse(args);
+    const tips = TIPS[focus];
+    const result = `${tips}
+
+---
+*Tips from CtxOpt - Context Engineering Optimizer*
+*Learn more at https://ctxopt.dev*`;
+    return {
+        content: [{ type: "text", text: result }],
+    };
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Tools Registry
+ *
+ * Central registry for all MCP tools with unified execution.
+ */
+import type { ToolResult } from "../middleware/types.js";
+import type { MiddlewareChain } from "../middleware/chain.js";
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (args: unknown) => Promise<ToolExecuteResult>;
+}
+export interface ToolExecuteResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export declare class ToolRegistry {
+    private tools;
+    private middlewareChain;
+    private changeCallbacks;
+    /**
+     * Set the middleware chain to use for tool execution
+     */
+    setMiddlewareChain(chain: MiddlewareChain): void;
+    /**
+     * Register callback for tool list changes
+     */
+    onToolsChanged(callback: () => void): void;
+    /**
+     * Emit tool list change notification
+     */
+    private emitChange;
+    /**
+     * Register a tool
+     */
+    register(tool: ToolDefinition): this;
+    /**
+     * Unregister a tool
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get a tool by name
+     */
+    get(name: string): ToolDefinition | undefined;
+    /**
+     * List all registered tools
+     */
+    list(): ToolDefinition[];
+    /**
+     * Get tool definitions for MCP ListTools response
+     */
+    getToolDefinitions(): Array<{
+        name: string;
+        description: string;
+        inputSchema: Record<string, unknown>;
+    }>;
+    /**
+     * Execute a tool with middleware chain
+     */
+    execute(name: string, args: unknown): Promise<ToolResult>;
+}
+/**
+ * Create a new tool registry instance
+ */
+export declare function createToolRegistry(): ToolRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/tools/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAe,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA0C;IACvD,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,eAAe,CAAyB;IAEhD;;OAEG;IACH,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAIhD;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAI1C;;OAEG;IACH,OAAO,CAAC,UAAU;IAUlB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAMpC;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAQjC;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C;;OAEG;IACH,IAAI,IAAI,cAAc,EAAE;IAIxB;;OAEG;IACH,kBAAkB,IAAI,KAAK,CAAC;QAC1B,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACtC,CAAC;IAQF;;OAEG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;CA6FhE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAEjD"}

package/dist/tools/registry.js

@@ -0,0 +1,169 @@
+/**
+ * Tools Registry
+ *
+ * Central registry for all MCP tools with unified execution.
+ */
+import { countTokens } from "../utils/token-counter.js";
+export class ToolRegistry {
+    tools = new Map();
+    middlewareChain = null;
+    changeCallbacks = [];
+    /**
+     * Set the middleware chain to use for tool execution
+     */
+    setMiddlewareChain(chain) {
+        this.middlewareChain = chain;
+    }
+    /**
+     * Register callback for tool list changes
+     */
+    onToolsChanged(callback) {
+        this.changeCallbacks.push(callback);
+    }
+    /**
+     * Emit tool list change notification
+     */
+    emitChange() {
+        for (const cb of this.changeCallbacks) {
+            try {
+                cb();
+            }
+            catch {
+                // Ignore callback errors
+            }
+        }
+    }
+    /**
+     * Register a tool
+     */
+    register(tool) {
+        this.tools.set(tool.name, tool);
+        this.emitChange();
+        return this;
+    }
+    /**
+     * Unregister a tool
+     */
+    unregister(name) {
+        const result = this.tools.delete(name);
+        if (result) {
+            this.emitChange();
+        }
+        return result;
+    }
+    /**
+     * Get a tool by name
+     */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * List all registered tools
+     */
+    list() {
+        return Array.from(this.tools.values());
+    }
+    /**
+     * Get tool definitions for MCP ListTools response
+     */
+    getToolDefinitions() {
+        return this.list().map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }));
+    }
+    /**
+     * Execute a tool with middleware chain
+     */
+    async execute(name, args) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            return {
+                content: [{ type: "text", text: `Unknown tool: ${name}` }],
+                isError: true,
+                tokensIn: 0,
+                tokensOut: 0,
+                tokensSaved: 0,
+                wasFiltered: false,
+                metadata: {},
+            };
+        }
+        // Count input tokens using centralized counter
+        const inputText = JSON.stringify(args);
+        const tokensIn = countTokens(inputText);
+        // Create tool context with error tracking
+        const ctx = {
+            toolName: name,
+            arguments: args,
+            startTime: Date.now(),
+            metadata: {},
+            middlewareErrors: [],
+        };
+        try {
+            // Execute beforeTool middlewares
+            let currentCtx = ctx;
+            if (this.middlewareChain) {
+                currentCtx = await this.middlewareChain.executeBefore(ctx);
+                if (currentCtx === null) {
+                    // Middleware skipped execution
+                    return {
+                        content: [{ type: "text", text: "Tool execution skipped by middleware" }],
+                        isError: false,
+                        tokensIn,
+                        tokensOut: 0,
+                        tokensSaved: 0,
+                        wasFiltered: true,
+                        metadata: { skippedBy: "middleware" },
+                    };
+                }
+            }
+            // Execute tool
+            const executeResult = await tool.execute(currentCtx.arguments);
+            // Count output tokens using centralized counter
+            const outputText = executeResult.content.map((c) => c.text).join("\n");
+            const tokensOut = countTokens(outputText);
+            // Create result
+            let result = {
+                content: executeResult.content,
+                isError: executeResult.isError ?? false,
+                tokensIn,
+                tokensOut,
+                tokensSaved: 0,
+                wasFiltered: false,
+                metadata: {},
+            };
+            // Execute afterTool middlewares
+            if (this.middlewareChain) {
+                result = await this.middlewareChain.executeAfter(currentCtx, result);
+            }
+            return result;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            // Try to handle error with middleware
+            if (this.middlewareChain) {
+                const handledResult = await this.middlewareChain.executeOnError(ctx, err);
+                if (handledResult) {
+                    return handledResult;
+                }
+            }
+            // Return error result
+            return {
+                content: [{ type: "text", text: `Error executing ${name}: ${err.message}` }],
+                isError: true,
+                tokensIn,
+                tokensOut: 0,
+                tokensSaved: 0,
+                wasFiltered: false,
+                metadata: { error: err.message },
+            };
+        }
+    }
+}
+/**
+ * Create a new tool registry instance
+ */
+export function createToolRegistry() {
+    return new ToolRegistry();
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Semantic Compress Tool
+ *
+ * Intelligently compress content by extracting the most important segments
+ * using TF-IDF scoring, position weighting, and keyword detection.
+ *
+ * Phase 2: Rule-based implementation (no ML models)
+ */
+import type { ToolDefinition } from "./registry.js";
+/**
+ * JSON Schema for MCP tool registration
+ */
+export declare const semanticCompressSchema: {
+    type: "object";
+    properties: {
+        content: {
+            type: string;
+        };
+        targetRatio: {
+            type: string;
+        };
+    };
+    required: string[];
+};
+/**
+ * Execute semantic compression
+ */
+export declare function executeSemanticCompress(args: unknown): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+/**
+ * Tool definition for MCP registration
+ */
+export declare const semanticCompressTool: ToolDefinition;
+//# sourceMappingURL=semantic-compress.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-compress.d.ts","sourceRoot":"","sources":["../../src/tools/semantic-compress.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAMpD;;GAEG;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;CAOlC,CAAC;AAmCF;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAgEhF;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,cAKlC,CAAC"}

package/dist/tools/semantic-compress.js

@@ -0,0 +1,113 @@
+/**
+ * Semantic Compress Tool
+ *
+ * Intelligently compress content by extracting the most important segments
+ * using TF-IDF scoring, position weighting, and keyword detection.
+ *
+ * Phase 2: Rule-based implementation (no ML models)
+ */
+import { z } from "zod";
+import { semanticCompressor, } from "../compressors/semantic.js";
+/**
+ * JSON Schema for MCP tool registration
+ */
+// Minimal schema - model has only one value, preservePatterns rarely used
+export const semanticCompressSchema = {
+    type: "object",
+    properties: {
+        content: { type: "string" },
+        targetRatio: { type: "number" },
+    },
+    required: ["content"],
+};
+/**
+ * Zod schema for runtime input validation
+ */
+const inputSchema = z.object({
+    content: z.string().min(1, "Content is required"),
+    targetRatio: z.number().min(0.1).max(0.9).optional().default(0.5),
+    preservePatterns: z.array(z.string()).optional(),
+    model: z.enum(["fast"]).optional().default("fast"),
+});
+/**
+ * Format the compression result - minimal header to save tokens
+ */
+function formatOutput(result, _technique) {
+    const savingsPercent = result.originalTokens > 0
+        ? Math.round((result.savings / result.originalTokens) * 100)
+        : 0;
+    const header = `[semantic] ${result.originalTokens}→${result.compressedTokens} tokens (-${savingsPercent}%)`;
+    return `${header}\n${result.compressed}`;
+}
+/**
+ * Execute semantic compression
+ */
+export async function executeSemanticCompress(args) {
+    // Validate input
+    const parseResult = inputSchema.safeParse(args);
+    if (!parseResult.success) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Invalid input: ${parseResult.error.errors.map((e) => e.message).join(", ")}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const input = parseResult.data;
+    // Convert preserve patterns to RegExp
+    let preservePatterns;
+    if (input.preservePatterns) {
+        try {
+            preservePatterns = input.preservePatterns.map((p) => new RegExp(p, "i"));
+        }
+        catch (e) {
+            const error = e;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid regex pattern: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    // Run semantic compression
+    const result = semanticCompressor.compress(input.content, {
+        targetRatio: input.targetRatio,
+        preservePatterns,
+        detail: "normal",
+    });
+    // Build output
+    const output = {
+        compressed: result.compressed,
+        originalTokens: result.stats.originalTokens,
+        compressedTokens: result.stats.compressedTokens,
+        savings: result.stats.originalTokens - result.stats.compressedTokens,
+        preservedSegments: result.preservedSegments ?? [],
+    };
+    // Update session state with tokens saved
+    if (output.savings > 0) {
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: formatOutput(output, result.stats.technique),
+            },
+        ],
+    };
+}
+/**
+ * Tool definition for MCP registration
+ */
+export const semanticCompressTool = {
+    name: "semantic_compress",
+    description: "TF-IDF compression. Keeps important segments by relevance scoring.",
+    inputSchema: semanticCompressSchema,
+    execute: executeSemanticCompress,
+};

package/dist/tools/semantic-compress.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Semantic Compress Tool Tests
+ */
+export {};
+//# sourceMappingURL=semantic-compress.test.d.ts.map

package/dist/tools/semantic-compress.test.d.ts.map

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