midnight-mcp 0.1.9 → 0.1.10

package/README.md

@@ -73,7 +73,7 @@ Restart your editor after adding the config. **No API keys required.**
 
 ## Features
 
-**19 Tools** — Search, analyze, version tracking, AI generation
+**23 Tools** — Search, analyze, version tracking, AI generation, compound operations
 
 | Category      | Tools                                                                                                                                                                                   |
 | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -81,8 +81,11 @@ Restart your editor after adding the config. **No API keys required.**
 | Analysis      | `midnight-analyze-contract`, `midnight-explain-circuit`                                                                                                                                 |
 | Repository    | `midnight-get-file`, `midnight-list-examples`, `midnight-get-latest-updates`                                                                                                            |
 | Versioning    | `midnight-get-version-info`, `midnight-check-breaking-changes`, `midnight-get-migration-guide`, `midnight-get-file-at-version`, `midnight-compare-syntax`, `midnight-get-latest-syntax` |
-| AI Generation | `midnight-generate-contract`, `midnight-review-contract`, `midnight-document-contract`                                                                                                  |
-| Status        | `midnight-health-check`, `midnight-get-status`                                                                                                                                          |
+| AI Generation | `midnight-generate-contract`, `midnight-review-contract`, `midnight-document-contract` _(requires sampling)_                                                                            |
+| Compound      | `midnight-upgrade-check`, `midnight-get-repo-context` _(saves 50-70% tokens)_                                                                                                           |
+| Discovery     | `midnight-list-tool-categories`, `midnight-list-category-tools`, `midnight-health-check`, `midnight-get-status`                                                                         |
+
+> **Tip:** Use compound tools (`midnight-upgrade-check`, `midnight-get-repo-context`) for efficient multi-step operations in a single call.
 
 **9 Embedded Resources** — Quick references available offline: Compact syntax, SDK API, OpenZeppelin contracts, tokenomics, wallet integration, common errors
 

package/dist/tools/analyze.js

@@ -397,6 +397,7 @@ export const analyzeTools = [
             readOnlyHint: true,
             idempotentHint: true,
             title: "Analyze Compact Contract",
+            category: "analyze",
         },
         handler: analyzeContract,
     },
@@ -418,6 +419,7 @@ export const analyzeTools = [
             readOnlyHint: true,
             idempotentHint: true,
             title: "Explain Circuit",
+            category: "analyze",
         },
         handler: explainCircuit,
     },

package/dist/tools/generation.js

@@ -182,6 +182,7 @@ EXAMPLE USAGE:
             idempotentHint: false,
             openWorldHint: true,
             longRunningHint: true,
+            category: "generation",
         },
         handler: handleGenerateContract,
     },
@@ -223,6 +224,7 @@ OUTPUT INCLUDES:
             idempotentHint: true,
             openWorldHint: true,
             longRunningHint: true,
+            category: "generation",
         },
         handler: handleReviewContract,
     },
@@ -268,6 +270,7 @@ MARKDOWN INCLUDES:
             idempotentHint: true,
             openWorldHint: true,
             longRunningHint: true,
+            category: "generation",
         },
         handler: handleDocumentContract,
     },

package/dist/tools/health.js

@@ -140,6 +140,7 @@ export const healthTools = [
             readOnlyHint: true,
             idempotentHint: true,
             title: "Health Check",
+            category: "health",
         },
         handler: healthCheck,
     },
@@ -155,6 +156,7 @@ export const healthTools = [
             readOnlyHint: true,
             idempotentHint: true,
             title: "Get Server Status",
+            category: "health",
         },
         handler: getStatus,
     },

package/dist/tools/index.d.ts

@@ -7,6 +7,7 @@ export type { GetFileInput, ListExamplesInput, GetLatestUpdatesInput, } from "./
 export { healthTools, healthCheck, getStatus } from "./health.js";
 export type { HealthCheckInput, GetStatusInput } from "./health.js";
 export { generationTools, generationHandlers } from "./generation.js";
+export { metaTools, listToolCategories, listCategoryTools } from "./meta.js";
 export type { ExtendedToolDefinition, ToolAnnotations, OutputSchema, } from "../types/index.js";
 import type { ExtendedToolDefinition } from "../types/index.js";
 export declare const allTools: ExtendedToolDefinition[];

package/dist/tools/index.js

@@ -3,13 +3,16 @@ export { analyzeTools, analyzeContract, explainCircuit } from "./analyze.js";
 export { repositoryTools, getFile, listExamples, getLatestUpdates, } from "./repository.js";
 export { healthTools, healthCheck, getStatus } from "./health.js";
 export { generationTools, generationHandlers } from "./generation.js";
+export { metaTools, listToolCategories, listCategoryTools } from "./meta.js";
 // Combined tool list for MCP server
 import { searchTools } from "./search.js";
 import { analyzeTools } from "./analyze.js";
 import { repositoryTools } from "./repository.js";
 import { healthTools } from "./health.js";
 import { generationTools } from "./generation.js";
+import { metaTools } from "./meta.js";
 export const allTools = [
+    ...metaTools, // Discovery tools first for visibility
     ...searchTools,
     ...analyzeTools,
     ...repositoryTools,

package/dist/tools/meta.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Meta-tools for progressive disclosure and tool discovery
+ * These tools help AI agents efficiently discover and use available capabilities
+ */
+import type { ExtendedToolDefinition, OutputSchema, ToolCategory } from "../types/index.js";
+interface ListCategoriesInput {
+    includeToolCounts?: boolean;
+}
+interface ListCategoryToolsInput {
+    category: ToolCategory;
+    includeSchemas?: boolean;
+}
+/**
+ * List available tool categories
+ * Use this first to understand what's available before drilling into specific tools
+ */
+export declare function listToolCategories(_input: ListCategoriesInput): Promise<{
+    categories: {
+        name: string;
+        description: string;
+        toolCount: number;
+        useCases: string[];
+    }[];
+    totalTools: number;
+    recommendation: string;
+    tip: string;
+}>;
+/**
+ * List tools within a specific category
+ * Progressive disclosure: drill into a category to see its tools
+ */
+export declare function listCategoryTools(input: ListCategoryToolsInput): Promise<{
+    error: string;
+    availableCategories: string[];
+    suggestion: string;
+    category?: undefined;
+    description?: undefined;
+    tools?: undefined;
+} | {
+    category: ToolCategory;
+    description: string;
+    tools: {
+        inputSchema?: {
+            type: "object";
+            properties: Record<string, unknown>;
+            required?: string[];
+        } | undefined;
+        outputSchema?: OutputSchema | undefined;
+        name: string;
+        description: string;
+        title: string;
+        isCompound: boolean;
+        requiresSampling: boolean | undefined;
+    }[];
+    suggestion: string;
+    error?: undefined;
+    availableCategories?: undefined;
+}>;
+export declare const metaTools: ExtendedToolDefinition[];
+export {};
+//# sourceMappingURL=meta.d.ts.map

package/dist/tools/meta.js

@@ -0,0 +1,281 @@
+/**
+ * Meta-tools for progressive disclosure and tool discovery
+ * These tools help AI agents efficiently discover and use available capabilities
+ */
+// Import all tool arrays to build the index
+import { searchTools } from "./search.js";
+import { analyzeTools } from "./analyze.js";
+import { repositoryTools } from "./repository.js";
+import { healthTools } from "./health.js";
+import { generationTools } from "./generation.js";
+// ============================================================================
+// Tool Category Descriptions
+// ============================================================================
+const CATEGORY_INFO = {
+    search: {
+        description: "Semantic search across Midnight codebase - find code by meaning, not keywords",
+        useCases: [
+            "Find example implementations",
+            "Search for patterns",
+            "Discover relevant code",
+        ],
+    },
+    analyze: {
+        description: "Static analysis of Compact contracts - security, structure, patterns",
+        useCases: [
+            "Security audit",
+            "Code review",
+            "Understand contract structure",
+        ],
+    },
+    repository: {
+        description: "Access repository files, examples, and recent updates",
+        useCases: [
+            "Get specific files",
+            "List examples",
+            "Track repository changes",
+        ],
+    },
+    versioning: {
+        description: "Version management, breaking changes, and migration assistance",
+        useCases: [
+            "Check for updates",
+            "Plan upgrades",
+            "Compare versions",
+            "Get migration guides",
+        ],
+    },
+    generation: {
+        description: "AI-powered code generation, review, and documentation (requires sampling)",
+        useCases: ["Generate contracts", "Review code", "Generate documentation"],
+    },
+    health: {
+        description: "Server health checks and status monitoring",
+        useCases: ["Check API status", "Monitor rate limits", "Debug connectivity"],
+    },
+    compound: {
+        description: "Multi-step operations in a single call - saves tokens and reduces latency",
+        useCases: [
+            "Full upgrade analysis",
+            "Get complete repo context",
+            "One-shot operations",
+        ],
+    },
+};
+const listCategoriesOutputSchema = {
+    type: "object",
+    properties: {
+        categories: {
+            type: "array",
+            description: "Available tool categories",
+            items: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Category identifier" },
+                    description: {
+                        type: "string",
+                        description: "What the category does",
+                    },
+                    toolCount: { type: "number", description: "Number of tools" },
+                    useCases: {
+                        type: "array",
+                        description: "When to use this category",
+                        items: { type: "string" },
+                    },
+                },
+            },
+        },
+        totalTools: { type: "number", description: "Total tool count" },
+        recommendation: {
+            type: "string",
+            description: "Suggested starting point",
+        },
+    },
+    required: ["categories", "totalTools"],
+    description: "Tool categories for progressive discovery",
+};
+const listCategoryToolsOutputSchema = {
+    type: "object",
+    properties: {
+        category: { type: "string", description: "Category name" },
+        tools: {
+            type: "array",
+            description: "Tools in this category",
+            items: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Tool name" },
+                    description: { type: "string", description: "What the tool does" },
+                    title: { type: "string", description: "Human-readable title" },
+                    isCompound: {
+                        type: "boolean",
+                        description: "Whether this is a compound tool",
+                    },
+                    requiresSampling: {
+                        type: "boolean",
+                        description: "Requires client sampling capability",
+                    },
+                },
+            },
+        },
+        suggestion: { type: "string", description: "Usage suggestion" },
+    },
+    required: ["category", "tools"],
+    description: "Tools within a specific category",
+};
+// ============================================================================
+// Handler Functions
+// ============================================================================
+// Build tool index by category
+function getToolsByCategory() {
+    const allTools = [
+        ...searchTools,
+        ...analyzeTools,
+        ...repositoryTools,
+        ...healthTools,
+        ...generationTools,
+    ];
+    const byCategory = new Map();
+    for (const tool of allTools) {
+        const category = tool.annotations?.category || "repository";
+        if (!byCategory.has(category)) {
+            byCategory.set(category, []);
+        }
+        byCategory.get(category).push(tool);
+    }
+    return byCategory;
+}
+/**
+ * List available tool categories
+ * Use this first to understand what's available before drilling into specific tools
+ */
+export async function listToolCategories(_input) {
+    const toolsByCategory = getToolsByCategory();
+    const categories = Object.entries(CATEGORY_INFO).map(([name, info]) => ({
+        name,
+        description: info.description,
+        toolCount: toolsByCategory.get(name)?.length || 0,
+        useCases: info.useCases,
+    }));
+    // Filter out empty categories
+    const nonEmptyCategories = categories.filter((c) => c.toolCount > 0);
+    const totalTools = nonEmptyCategories.reduce((sum, c) => sum + c.toolCount, 0);
+    return {
+        categories: nonEmptyCategories,
+        totalTools,
+        recommendation: "Start with 'compound' category for efficient multi-step operations, or 'search' to find relevant code.",
+        tip: "Use midnight-list-category-tools to see tools within a specific category.",
+    };
+}
+/**
+ * List tools within a specific category
+ * Progressive disclosure: drill into a category to see its tools
+ */
+export async function listCategoryTools(input) {
+    const toolsByCategory = getToolsByCategory();
+    const tools = toolsByCategory.get(input.category) || [];
+    if (tools.length === 0) {
+        return {
+            error: `Unknown or empty category: ${input.category}`,
+            availableCategories: Object.keys(CATEGORY_INFO),
+            suggestion: "Use midnight-list-tool-categories to see available categories.",
+        };
+    }
+    const categoryInfo = CATEGORY_INFO[input.category];
+    return {
+        category: input.category,
+        description: categoryInfo.description,
+        tools: tools.map((t) => ({
+            name: t.name,
+            description: t.description.split("\n")[0], // First line only
+            title: t.annotations?.title || t.name,
+            isCompound: t.annotations?.category === "compound",
+            requiresSampling: t.annotations?.longRunningHint &&
+                t.annotations?.category === "generation",
+            ...(input.includeSchemas && {
+                inputSchema: t.inputSchema,
+                outputSchema: t.outputSchema,
+            }),
+        })),
+        suggestion: generateCategorySuggestion(input.category),
+    };
+}
+function generateCategorySuggestion(category) {
+    switch (category) {
+        case "compound":
+            return "🚀 Compound tools save 50-70% tokens. Use midnight-upgrade-check or midnight-get-repo-context for efficient operations.";
+        case "search":
+            return "💡 Search tools use semantic matching - describe what you want in natural language.";
+        case "generation":
+            return "⚠️ Generation tools require sampling capability. They use the client's LLM for AI-powered operations.";
+        case "versioning":
+            return "📦 For version checks, prefer midnight-upgrade-check (compound) over individual version tools.";
+        case "analyze":
+            return "🔍 Analyze tools work on Compact code. Provide the contract source code directly.";
+        default:
+            return `Use these tools for ${CATEGORY_INFO[category]?.useCases[0] || "related operations"}.`;
+    }
+}
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+export const metaTools = [
+    {
+        name: "midnight-list-tool-categories",
+        description: "📋 DISCOVERY TOOL: List available tool categories for progressive exploration. Use this FIRST to understand what capabilities are available, then drill into specific categories with midnight-list-category-tools. Reduces cognitive load by organizing 21 tools into 7 logical groups.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                includeToolCounts: {
+                    type: "boolean",
+                    description: "Include number of tools per category (default: true)",
+                },
+            },
+            required: [],
+        },
+        outputSchema: listCategoriesOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            title: "📋 List Tool Categories",
+            category: "health",
+        },
+        handler: listToolCategories,
+    },
+    {
+        name: "midnight-list-category-tools",
+        description: "📋 DISCOVERY TOOL: List tools within a specific category. Use after midnight-list-tool-categories to see detailed tool information for a category of interest. Supports progressive disclosure pattern.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                category: {
+                    type: "string",
+                    enum: [
+                        "search",
+                        "analyze",
+                        "repository",
+                        "versioning",
+                        "generation",
+                        "health",
+                        "compound",
+                    ],
+                    description: "Category to list tools for",
+                },
+                includeSchemas: {
+                    type: "boolean",
+                    description: "Include input/output schemas (default: false)",
+                },
+            },
+            required: ["category"],
+        },
+        outputSchema: listCategoryToolsOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            title: "📋 List Category Tools",
+            category: "health",
+        },
+        handler: listCategoryTools,
+    },
+];
+//# sourceMappingURL=meta.js.map

package/dist/tools/repository/handlers.d.ts

@@ -2,7 +2,7 @@
  * Repository handler functions
  * Business logic for repository-related MCP tools
  */
-import type { GetFileInput, ListExamplesInput, GetLatestUpdatesInput, GetVersionInfoInput, CheckBreakingChangesInput, GetMigrationGuideInput, GetFileAtVersionInput, CompareSyntaxInput, GetLatestSyntaxInput } from "./schemas.js";
+import type { GetFileInput, ListExamplesInput, GetLatestUpdatesInput, GetVersionInfoInput, CheckBreakingChangesInput, GetMigrationGuideInput, GetFileAtVersionInput, CompareSyntaxInput, GetLatestSyntaxInput, UpgradeCheckInput, FullRepoContextInput } from "./schemas.js";
 /**
  * Resolve repository name alias to owner/repo
  */
@@ -15,22 +15,21 @@ export declare function resolveRepo(repoName?: string): {
  */
 export declare function getFile(input: GetFileInput): Promise<{
     error: string;
+    code: "UNKNOWN_REPOSITORY";
     suggestion: string;
-    repository?: undefined;
-    content?: undefined;
-    path?: undefined;
-    sha?: undefined;
-    size?: undefined;
-    url?: undefined;
+    correction: {
+        invalidValue: string;
+        validValues: string[];
+        parameterName: string;
+    };
 } | {
     error: string;
-    repository: string;
+    code: "RESOURCE_NOT_FOUND";
     suggestion: string;
-    content?: undefined;
-    path?: undefined;
-    sha?: undefined;
-    size?: undefined;
-    url?: undefined;
+    correction: {
+        suggestions?: string[] | undefined;
+        invalidPath: string;
+    };
 } | {
     content: string;
     path: string;
@@ -38,8 +37,6 @@ export declare function getFile(input: GetFileInput): Promise<{
     sha: string;
     size: number;
     url: string;
-    error?: undefined;
-    suggestion?: undefined;
 }>;
 /**
  * List available example contracts and DApps
@@ -177,4 +174,65 @@ export declare function getLatestSyntax(input: GetLatestSyntaxInput): Promise<{
     warning?: undefined;
     examplePaths?: undefined;
 }>;
+/**
+ * Compound tool: Full upgrade check
+ * Combines: getVersionInfo + checkBreakingChanges + getMigrationGuide
+ * Reduces 3 tool calls to 1, saving ~60% tokens
+ */
+export declare function upgradeCheck(input: UpgradeCheckInput): Promise<{
+    repository: string;
+    currentVersion: string;
+    version: {
+        latest: string;
+        latestStable: string;
+        publishedAt: string | null;
+        isOutdated: boolean;
+        versionsBehind: number;
+    };
+    breakingChanges: {
+        count: number;
+        hasBreakingChanges: boolean;
+        items: string[];
+    };
+    migration: {
+        steps: string[];
+        deprecations: string[];
+        newFeatures: string[];
+    } | null;
+    urgency: "none" | "low" | "medium" | "high" | "critical";
+    recommendation: string;
+}>;
+/**
+ * Compound tool: Full repository context
+ * Combines: getVersionInfo + getLatestSyntax + listExamples (filtered)
+ * Provides everything needed to start working with a repo
+ */
+export declare function getFullRepoContext(input: FullRepoContextInput): Promise<{
+    repository: string;
+    quickStart: {
+        version: string;
+        installCommand: string;
+        docsUrl: string;
+    };
+    version: {
+        current: string;
+        stable: string | null;
+        publishedAt: string | null;
+        recentReleases: {
+            tag: string;
+            date: string;
+        }[];
+    };
+    syntax: {
+        version: string;
+        files: string[];
+        primaryReference: string | null;
+    } | null;
+    examples: {
+        name: string;
+        description: string;
+        complexity: string;
+    }[];
+    note: string;
+}>;
 //# sourceMappingURL=handlers.d.ts.map

package/dist/tools/repository/handlers.js

@@ -4,7 +4,7 @@
  */
 import { githubClient } from "../../pipeline/index.js";
 import { releaseTracker } from "../../pipeline/releases.js";
-import { logger, DEFAULT_REPOSITORIES } from "../../utils/index.js";
+import { logger, DEFAULT_REPOSITORIES, SelfCorrectionHints, } from "../../utils/index.js";
 import { REPO_ALIASES, EXAMPLES } from "./constants.js";
 /**
  * Resolve repository name alias to owner/repo
@@ -36,18 +36,11 @@ export async function getFile(input) {
     logger.debug("Getting file", { repo: input.repo, path: input.path });
     const repoInfo = resolveRepo(input.repo);
     if (!repoInfo) {
-        return {
-            error: `Unknown repository: ${input.repo}`,
-            suggestion: `Valid repositories: ${Object.keys(REPO_ALIASES).join(", ")}`,
-        };
+        return SelfCorrectionHints.UNKNOWN_REPO(input.repo, Object.keys(REPO_ALIASES));
     }
     const file = await githubClient.getFileContent(repoInfo.owner, repoInfo.repo, input.path, input.ref);
     if (!file) {
-        return {
-            error: `File not found: ${input.path}`,
-            repository: `${repoInfo.owner}/${repoInfo.repo}`,
-            suggestion: "Check the file path and try again. Use midnight:list-examples to see available example files.",
-        };
+        return SelfCorrectionHints.FILE_NOT_FOUND(input.path, `${repoInfo.owner}/${repoInfo.repo}`);
     }
     return {
         content: file.content,
@@ -335,4 +328,185 @@ export async function getLatestSyntax(input) {
         note: `This is the authoritative syntax reference at version ${reference.version}. Use this to ensure contracts are compilable.`,
     };
 }
+// ============================================================================
+// COMPOUND TOOLS - Reduce multiple API calls to single operations
+// These tools combine related operations to minimize round-trips and token usage
+// ============================================================================
+/**
+ * Compound tool: Full upgrade check
+ * Combines: getVersionInfo + checkBreakingChanges + getMigrationGuide
+ * Reduces 3 tool calls to 1, saving ~60% tokens
+ */
+export async function upgradeCheck(input) {
+    const repoName = input?.repo || "compact";
+    const currentVersion = input.currentVersion;
+    logger.debug("Running compound upgrade check", {
+        repo: repoName,
+        currentVersion,
+    });
+    const resolved = resolveRepo(repoName);
+    if (!resolved) {
+        throw new Error(`Unknown repository: ${repoName}. Available: ${Object.keys(REPO_ALIASES).join(", ")}`);
+    }
+    // Fetch all data in parallel
+    const [versionInfo, outdatedInfo, breakingChanges] = await Promise.all([
+        releaseTracker.getVersionInfo(resolved.owner, resolved.repo),
+        releaseTracker.isOutdated(resolved.owner, resolved.repo, currentVersion),
+        releaseTracker.getBreakingChangesSince(resolved.owner, resolved.repo, currentVersion),
+    ]);
+    const latestVersion = versionInfo.latestStableRelease?.tag || versionInfo.latestRelease?.tag;
+    // Only fetch migration guide if there are breaking changes
+    let migrationGuide = null;
+    if (breakingChanges.length > 0 && latestVersion) {
+        migrationGuide = await releaseTracker.getMigrationGuide(resolved.owner, resolved.repo, currentVersion, latestVersion);
+    }
+    // Compute upgrade urgency
+    const urgency = computeUpgradeUrgency(outdatedInfo, breakingChanges.length);
+    return {
+        repository: `${resolved.owner}/${resolved.repo}`,
+        currentVersion,
+        // Version summary
+        version: {
+            latest: latestVersion || "No releases",
+            latestStable: versionInfo.latestStableRelease?.tag || "No stable releases",
+            publishedAt: versionInfo.latestRelease?.publishedAt || null,
+            isOutdated: outdatedInfo.isOutdated,
+            versionsBehind: outdatedInfo.versionsBehind,
+        },
+        // Breaking changes summary
+        breakingChanges: {
+            count: breakingChanges.length,
+            hasBreakingChanges: breakingChanges.length > 0,
+            items: breakingChanges.slice(0, 10), // Limit to avoid token bloat
+        },
+        // Migration guide (only if needed)
+        migration: migrationGuide
+            ? {
+                steps: migrationGuide.migrationSteps,
+                deprecations: migrationGuide.deprecations,
+                newFeatures: migrationGuide.newFeatures.slice(0, 5),
+            }
+            : null,
+        // Actionable recommendation
+        urgency,
+        recommendation: generateUpgradeRecommendation(urgency, breakingChanges.length, outdatedInfo),
+    };
+}
+/**
+ * Compound tool: Full repository context
+ * Combines: getVersionInfo + getLatestSyntax + listExamples (filtered)
+ * Provides everything needed to start working with a repo
+ */
+export async function getFullRepoContext(input) {
+    const repoName = input?.repo || "compact";
+    logger.debug("Getting full repo context", { repo: repoName });
+    const resolved = resolveRepo(repoName);
+    if (!resolved) {
+        throw new Error(`Unknown repository: ${repoName}. Available: ${Object.keys(REPO_ALIASES).join(", ")}`);
+    }
+    // Fetch version info
+    const versionInfo = await releaseTracker.getVersionInfo(resolved.owner, resolved.repo);
+    const version = versionInfo.latestStableRelease?.tag ||
+        versionInfo.latestRelease?.tag ||
+        "main";
+    // Conditionally fetch syntax reference
+    let syntaxRef = null;
+    if (input.includeSyntax !== false) {
+        syntaxRef = await releaseTracker.getLatestSyntaxReference(resolved.owner, resolved.repo);
+    }
+    // Get relevant examples for this repo
+    let examples = [];
+    if (input.includeExamples !== false) {
+        // Filter examples relevant to this repo type
+        const repoType = getRepoType(repoName);
+        examples = EXAMPLES.filter((ex) => repoType === "all" || ex.category === repoType || repoType === "compact")
+            .slice(0, 5)
+            .map((ex) => ({
+            name: ex.name,
+            description: ex.description,
+            complexity: ex.complexity,
+        }));
+    }
+    return {
+        repository: `${resolved.owner}/${resolved.repo}`,
+        // Quick start info
+        quickStart: {
+            version,
+            installCommand: getInstallCommand(repoName, version),
+            docsUrl: `https://github.com/${resolved.owner}/${resolved.repo}`,
+        },
+        // Version context
+        version: {
+            current: version,
+            stable: versionInfo.latestStableRelease?.tag || null,
+            publishedAt: versionInfo.latestRelease?.publishedAt || null,
+            recentReleases: versionInfo.recentReleases.slice(0, 3).map((r) => ({
+                tag: r.tag,
+                date: r.publishedAt.split("T")[0],
+            })),
+        },
+        // Syntax reference (condensed)
+        syntax: syntaxRef
+            ? {
+                version: syntaxRef.version,
+                files: syntaxRef.syntaxFiles.map((f) => f.path),
+                // Include first file content as primary reference
+                primaryReference: syntaxRef.syntaxFiles[0]?.content?.slice(0, 2000) || null,
+            }
+            : null,
+        // Relevant examples
+        examples,
+        note: `Use this context to write ${repoName} code at version ${version}. For detailed syntax, use midnight-get-latest-syntax.`,
+    };
+}
+// Helper functions for compound tools
+function computeUpgradeUrgency(outdatedInfo, breakingCount) {
+    if (!outdatedInfo.isOutdated)
+        return "none";
+    if (breakingCount === 0 && outdatedInfo.versionsBehind <= 2)
+        return "low";
+    if (breakingCount <= 2 && outdatedInfo.versionsBehind <= 5)
+        return "medium";
+    if (breakingCount <= 5)
+        return "high";
+    return "critical";
+}
+function generateUpgradeRecommendation(urgency, breakingCount, outdatedInfo) {
+    switch (urgency) {
+        case "none":
+            return "✅ You're on the latest version. No action needed.";
+        case "low":
+            return `📦 Minor update available (${outdatedInfo.versionsBehind} versions behind). Safe to upgrade at your convenience.`;
+        case "medium":
+            return `⚠️ Update recommended. ${breakingCount} breaking change(s) to review. Plan upgrade within 2 weeks.`;
+        case "high":
+            return `🔶 Important update. ${breakingCount} breaking changes require attention. Schedule upgrade soon.`;
+        case "critical":
+            return `🚨 Critical update needed! ${breakingCount} breaking changes and ${outdatedInfo.versionsBehind} versions behind. Upgrade immediately.`;
+        default:
+            return "Check the breaking changes and plan your upgrade.";
+    }
+}
+function getRepoType(repoName) {
+    const name = repoName.toLowerCase();
+    if (name.includes("counter"))
+        return "counter";
+    if (name.includes("bboard"))
+        return "bboard";
+    if (name.includes("token") || name.includes("dex"))
+        return "token";
+    if (name.includes("voting"))
+        return "voting";
+    return "all";
+}
+function getInstallCommand(repoName, version) {
+    const name = repoName.toLowerCase();
+    if (name === "compact" || name.includes("compact")) {
+        return `npx @aspect-sh/pnpm dlx @midnight-ntwrk/create-midnight-app@${version}`;
+    }
+    if (name === "midnight-js" || name.includes("js")) {
+        return `npm install @midnight-ntwrk/midnight-js@${version}`;
+    }
+    return `git clone https://github.com/midnight-ntwrk/${repoName}.git && cd ${repoName} && git checkout ${version}`;
+}
 //# sourceMappingURL=handlers.js.map

package/dist/tools/repository/schemas.d.ts

@@ -99,6 +99,29 @@ export declare const GetLatestSyntaxInputSchema: z.ZodObject<{
 }, {
     repo?: string | undefined;
 }>;
+export declare const UpgradeCheckInputSchema: z.ZodObject<{
+    repo: z.ZodDefault<z.ZodString>;
+    currentVersion: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    repo: string;
+    currentVersion: string;
+}, {
+    currentVersion: string;
+    repo?: string | undefined;
+}>;
+export declare const FullRepoContextInputSchema: z.ZodObject<{
+    repo: z.ZodString;
+    includeExamples: z.ZodDefault<z.ZodBoolean>;
+    includeSyntax: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    repo: string;
+    includeExamples: boolean;
+    includeSyntax: boolean;
+}, {
+    repo: string;
+    includeExamples?: boolean | undefined;
+    includeSyntax?: boolean | undefined;
+}>;
 export type GetFileInput = z.infer<typeof GetFileInputSchema>;
 export type ListExamplesInput = z.infer<typeof ListExamplesInputSchema>;
 export type GetLatestUpdatesInput = z.infer<typeof GetLatestUpdatesInputSchema>;
@@ -108,4 +131,6 @@ export type GetMigrationGuideInput = z.infer<typeof GetMigrationGuideInputSchema
 export type GetFileAtVersionInput = z.infer<typeof GetFileAtVersionInputSchema>;
 export type CompareSyntaxInput = z.infer<typeof CompareSyntaxInputSchema>;
 export type GetLatestSyntaxInput = z.infer<typeof GetLatestSyntaxInputSchema>;
+export type UpgradeCheckInput = z.infer<typeof UpgradeCheckInputSchema>;
+export type FullRepoContextInput = z.infer<typeof FullRepoContextInputSchema>;
 //# sourceMappingURL=schemas.d.ts.map

package/dist/tools/repository/schemas.js

@@ -70,4 +70,22 @@ export const GetLatestSyntaxInputSchema = z.object({
         .default("compact")
         .describe("Repository name (default: 'compact')"),
 });
+// Compound tool schemas - reduce multiple API calls to one
+export const UpgradeCheckInputSchema = z.object({
+    repo: z
+        .string()
+        .default("compact")
+        .describe("Repository name (default: 'compact')"),
+    currentVersion: z
+        .string()
+        .describe("Your current version (e.g., 'v0.14.0', '0.13.5')"),
+});
+export const FullRepoContextInputSchema = z.object({
+    repo: z.string().describe("Repository name (e.g., 'compact', 'midnight-js')"),
+    includeExamples: z
+        .boolean()
+        .default(true)
+        .describe("Include example code snippets"),
+    includeSyntax: z.boolean().default(true).describe("Include syntax reference"),
+});
 //# sourceMappingURL=schemas.js.map

package/dist/tools/repository/tools.js

@@ -2,7 +2,7 @@
  * Repository tool definitions
  * MCP tool registration for repository-related operations
  */
-import { getFile, listExamples, getLatestUpdates, getVersionInfo, checkBreakingChanges, getMigrationGuide, getFileAtVersion, compareSyntax, getLatestSyntax, } from "./handlers.js";
+import { getFile, listExamples, getLatestUpdates, getVersionInfo, checkBreakingChanges, getMigrationGuide, getFileAtVersion, compareSyntax, getLatestSyntax, upgradeCheck, getFullRepoContext, } from "./handlers.js";
 // Tool definitions for MCP
 export const repositoryTools = [
     {
@@ -30,6 +30,7 @@ export const repositoryTools = [
             readOnlyHint: true,
             openWorldHint: true,
             title: "Get Repository File",
+            category: "repository",
         },
         handler: getFile,
     },
@@ -51,6 +52,7 @@ export const repositoryTools = [
             readOnlyHint: true,
             idempotentHint: true,
             title: "List Example Contracts",
+            category: "repository",
         },
         handler: listExamples,
     },
@@ -76,6 +78,7 @@ export const repositoryTools = [
             readOnlyHint: true,
             openWorldHint: true,
             title: "Get Latest Updates",
+            category: "repository",
         },
         handler: getLatestUpdates,
     },
@@ -96,6 +99,7 @@ export const repositoryTools = [
             readOnlyHint: true,
             openWorldHint: true,
             title: "Get Version Info",
+            category: "versioning",
         },
         handler: getVersionInfo,
     },
@@ -120,6 +124,7 @@ export const repositoryTools = [
             readOnlyHint: true,
             openWorldHint: true,
             title: "Check Breaking Changes",
+            category: "versioning",
         },
         handler: checkBreakingChanges,
     },
@@ -148,6 +153,7 @@ export const repositoryTools = [
             readOnlyHint: true,
             openWorldHint: true,
             title: "Get Migration Guide",
+            category: "versioning",
         },
         handler: getMigrationGuide,
     },
@@ -177,6 +183,7 @@ export const repositoryTools = [
             idempotentHint: true,
             openWorldHint: true,
             title: "Get File at Version",
+            category: "versioning",
         },
         handler: getFileAtVersion,
     },
@@ -210,6 +217,7 @@ export const repositoryTools = [
             idempotentHint: true,
             openWorldHint: true,
             title: "Compare Syntax Between Versions",
+            category: "versioning",
         },
         handler: compareSyntax,
     },
@@ -230,8 +238,120 @@ export const repositoryTools = [
             readOnlyHint: true,
             openWorldHint: true,
             title: "Get Latest Syntax Reference",
+            category: "versioning",
         },
         handler: getLatestSyntax,
     },
+    // ============================================================================
+    // COMPOUND TOOLS - Multi-step operations in a single call
+    // These reduce token usage by 50-70% compared to calling individual tools
+    // ============================================================================
+    {
+        name: "midnight-upgrade-check",
+        description: "🚀 COMPOUND TOOL: Complete upgrade analysis in ONE call. Combines version check + breaking changes + migration guide. Use this instead of calling midnight-get-version-info, midnight-check-breaking-changes, and midnight-get-migration-guide separately. Saves ~60% tokens.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                repo: {
+                    type: "string",
+                    description: "Repository name (default: 'compact')",
+                },
+                currentVersion: {
+                    type: "string",
+                    description: "Your current version (e.g., 'v0.14.0', '0.13.5')",
+                },
+            },
+            required: ["currentVersion"],
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                repository: { type: "string", description: "Full repository path" },
+                currentVersion: {
+                    type: "string",
+                    description: "Version being checked",
+                },
+                version: {
+                    type: "object",
+                    description: "Version summary",
+                    properties: {
+                        latest: { type: "string" },
+                        latestStable: { type: "string" },
+                        isOutdated: { type: "boolean" },
+                        versionsBehind: { type: "number" },
+                    },
+                },
+                breakingChanges: {
+                    type: "object",
+                    description: "Breaking changes summary",
+                    properties: {
+                        count: { type: "number" },
+                        hasBreakingChanges: { type: "boolean" },
+                        items: { type: "array" },
+                    },
+                },
+                migration: { type: "object", description: "Migration guide if needed" },
+                urgency: {
+                    type: "string",
+                    description: "none|low|medium|high|critical",
+                },
+                recommendation: {
+                    type: "string",
+                    description: "Actionable recommendation",
+                },
+            },
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+            longRunningHint: true,
+            title: "⚡ Upgrade Check (Compound)",
+            category: "compound",
+        },
+        handler: upgradeCheck,
+    },
+    {
+        name: "midnight-get-repo-context",
+        description: "🚀 COMPOUND TOOL: Get everything needed to start working with a repository in ONE call. Combines version info + syntax reference + relevant examples. Use this at the start of a coding session instead of multiple individual calls. Saves ~50% tokens.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                repo: {
+                    type: "string",
+                    description: "Repository name (e.g., 'compact', 'midnight-js')",
+                },
+                includeExamples: {
+                    type: "boolean",
+                    description: "Include example code snippets (default: true)",
+                },
+                includeSyntax: {
+                    type: "boolean",
+                    description: "Include syntax reference (default: true)",
+                },
+            },
+            required: ["repo"],
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                repository: { type: "string", description: "Full repository path" },
+                quickStart: {
+                    type: "object",
+                    description: "Version and install command",
+                },
+                version: { type: "object", description: "Version details" },
+                syntax: { type: "object", description: "Syntax reference summary" },
+                examples: { type: "array", description: "Relevant examples" },
+            },
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+            longRunningHint: true,
+            title: "⚡ Get Repo Context (Compound)",
+            category: "compound",
+        },
+        handler: getFullRepoContext,
+    },
 ];
 //# sourceMappingURL=tools.js.map

package/dist/tools/search.js

@@ -57,6 +57,7 @@ const searchToolAnnotations = {
     readOnlyHint: true,
     idempotentHint: true,
     openWorldHint: true,
+    category: "search",
 };
 /**
  * Validate and prepare common search parameters

package/dist/types/mcp.d.ts

@@ -31,7 +31,27 @@ export interface ToolAnnotations {
      * Human-readable title for display in UIs
      */
     title?: string;
+    /**
+     * If true, this tool performs destructive or irreversible actions
+     * Clients should require human confirmation before execution
+     */
+    destructiveHint?: boolean;
+    /**
+     * If true, this tool requires explicit human confirmation
+     * before execution (e.g., financial transactions, deletions)
+     */
+    requiresConfirmation?: boolean;
+    /**
+     * Tool category for progressive disclosure
+     * Allows clients to group/filter tools by domain
+     */
+    category?: ToolCategory;
 }
+/**
+ * Tool categories for progressive disclosure
+ * Clients can initially show categories, then expand to individual tools
+ */
+export type ToolCategory = "search" | "analyze" | "repository" | "versioning" | "generation" | "health" | "compound";
 /**
  * JSON Schema for structured tool outputs
  * Enables better LLM parsing and IDE integration

package/dist/utils/errors.d.ts

@@ -25,6 +25,72 @@ export declare const ErrorCodes: {
     readonly PARSE_ERROR: "PARSE_ERROR";
     readonly CHROMADB_UNAVAILABLE: "CHROMADB_UNAVAILABLE";
     readonly OPENAI_UNAVAILABLE: "OPENAI_UNAVAILABLE";
+    readonly MISSING_PARAM: "MISSING_PARAMETER";
+    readonly INVALID_VERSION: "INVALID_VERSION";
+    readonly SAMPLING_UNAVAILABLE: "SAMPLING_UNAVAILABLE";
+};
+/**
+ * LLM-friendly error hints that help the model self-correct
+ * These are designed to give the AI enough context to retry with corrected input
+ */
+export declare const SelfCorrectionHints: {
+    UNKNOWN_REPO: (repo: string, validRepos: string[]) => {
+        error: string;
+        code: "UNKNOWN_REPOSITORY";
+        suggestion: string;
+        correction: {
+            invalidValue: string;
+            validValues: string[];
+            parameterName: string;
+        };
+    };
+    INVALID_VERSION: (version: string, example: string) => {
+        error: string;
+        code: "INVALID_VERSION";
+        suggestion: string;
+        correction: {
+            invalidValue: string;
+            expectedFormat: string;
+            example: string;
+        };
+    };
+    MISSING_REQUIRED_PARAM: (paramName: string, toolName: string) => {
+        error: string;
+        code: "MISSING_PARAMETER";
+        suggestion: string;
+        correction: {
+            missingParameter: string;
+            tool: string;
+        };
+    };
+    FILE_NOT_FOUND: (path: string, repo: string, similarPaths?: string[]) => {
+        error: string;
+        code: "RESOURCE_NOT_FOUND";
+        suggestion: string;
+        correction: {
+            suggestions?: string[] | undefined;
+            invalidPath: string;
+        };
+    };
+    SAMPLING_NOT_AVAILABLE: (toolName: string) => {
+        error: string;
+        code: "SAMPLING_UNAVAILABLE";
+        suggestion: string;
+        alternatives: {
+            "midnight-generate-contract": string;
+            "midnight-review-contract": string;
+            "midnight-document-contract": string;
+        };
+    };
+    RATE_LIMIT: (retryAfter?: number) => {
+        error: string;
+        code: "RATE_LIMIT_EXCEEDED";
+        suggestion: string;
+        correction: {
+            retryAfterSeconds?: number | undefined;
+            action: string;
+        };
+    };
 };
 /**
  * Create user-friendly error from various error types

package/dist/utils/errors.js

@@ -33,6 +33,76 @@ export const ErrorCodes = {
     PARSE_ERROR: "PARSE_ERROR",
     CHROMADB_UNAVAILABLE: "CHROMADB_UNAVAILABLE",
     OPENAI_UNAVAILABLE: "OPENAI_UNAVAILABLE",
+    MISSING_PARAM: "MISSING_PARAMETER",
+    INVALID_VERSION: "INVALID_VERSION",
+    SAMPLING_UNAVAILABLE: "SAMPLING_UNAVAILABLE",
+};
+/**
+ * LLM-friendly error hints that help the model self-correct
+ * These are designed to give the AI enough context to retry with corrected input
+ */
+export const SelfCorrectionHints = {
+    UNKNOWN_REPO: (repo, validRepos) => ({
+        error: `Unknown repository: '${repo}'`,
+        code: ErrorCodes.UNKNOWN_REPO,
+        suggestion: `Try one of these instead: ${validRepos.slice(0, 8).join(", ")}`,
+        correction: {
+            invalidValue: repo,
+            validValues: validRepos,
+            parameterName: "repo",
+        },
+    }),
+    INVALID_VERSION: (version, example) => ({
+        error: `Invalid version format: '${version}'`,
+        code: ErrorCodes.INVALID_VERSION,
+        suggestion: `Version should be like '${example}'. Check available versions with midnight-get-version-info first.`,
+        correction: {
+            invalidValue: version,
+            expectedFormat: "v1.0.0 or 0.14.0",
+            example,
+        },
+    }),
+    MISSING_REQUIRED_PARAM: (paramName, toolName) => ({
+        error: `Missing required parameter: '${paramName}'`,
+        code: ErrorCodes.MISSING_PARAM,
+        suggestion: `The '${paramName}' parameter is required for ${toolName}. Please provide it.`,
+        correction: {
+            missingParameter: paramName,
+            tool: toolName,
+        },
+    }),
+    FILE_NOT_FOUND: (path, repo, similarPaths) => ({
+        error: `File not found: '${path}' in ${repo}`,
+        code: ErrorCodes.NOT_FOUND,
+        suggestion: similarPaths?.length
+            ? `Did you mean: ${similarPaths.join(", ")}?`
+            : `Check the file path. Use midnight-get-file with a different path or list directory contents first.`,
+        correction: {
+            invalidPath: path,
+            ...(similarPaths && { suggestions: similarPaths }),
+        },
+    }),
+    SAMPLING_NOT_AVAILABLE: (toolName) => ({
+        error: `Sampling capability not available`,
+        code: ErrorCodes.SAMPLING_UNAVAILABLE,
+        suggestion: `${toolName} requires a client that supports sampling (e.g., Claude Desktop). Use a non-AI alternative or switch clients.`,
+        alternatives: {
+            "midnight-generate-contract": "Use midnight-search-compact to find similar contracts as templates",
+            "midnight-review-contract": "Use midnight-analyze-contract for static analysis",
+            "midnight-document-contract": "Manual documentation or inline comments",
+        },
+    }),
+    RATE_LIMIT: (retryAfter) => ({
+        error: "GitHub API rate limit exceeded",
+        code: ErrorCodes.RATE_LIMIT,
+        suggestion: retryAfter
+            ? `Wait ${retryAfter} seconds before retrying. Or add GITHUB_TOKEN for higher limits.`
+            : "Add GITHUB_TOKEN to increase from 60 to 5000 requests/hour.",
+        correction: {
+            action: "wait_and_retry",
+            ...(retryAfter && { retryAfterSeconds: retryAfter }),
+        },
+    }),
 };
 /**
  * Create user-friendly error from various error types

package/dist/utils/index.d.ts

@@ -2,7 +2,7 @@ export { config, isHostedMode, isLocalMode } from "./config.js";
 export type { Config, RepositoryConfig } from "./config.js";
 export { DEFAULT_REPOSITORIES } from "./config.js";
 export { logger } from "./logger.js";
-export { MCPError, ErrorCodes, createUserError, formatErrorResponse, withErrorHandling, } from "./errors.js";
+export { MCPError, ErrorCodes, createUserError, formatErrorResponse, withErrorHandling, SelfCorrectionHints, } from "./errors.js";
 export { validateQuery, validateRepository, validatePath, validateRef, validateNumber, validateToolArgs, sanitizeString, } from "./validation.js";
 export type { ValidationResult } from "./validation.js";
 export { getHealthStatus, getQuickHealthStatus } from "./health.js";

package/dist/utils/index.js

@@ -1,7 +1,7 @@
 export { config, isHostedMode, isLocalMode } from "./config.js";
 export { DEFAULT_REPOSITORIES } from "./config.js";
 export { logger } from "./logger.js";
-export { MCPError, ErrorCodes, createUserError, formatErrorResponse, withErrorHandling, } from "./errors.js";
+export { MCPError, ErrorCodes, createUserError, formatErrorResponse, withErrorHandling, SelfCorrectionHints, } from "./errors.js";
 // Validation utilities
 export { validateQuery, validateRepository, validatePath, validateRef, validateNumber, validateToolArgs, sanitizeString, } from "./validation.js";
 // Health check utilities

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "midnight-mcp",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Model Context Protocol Server for Midnight Blockchain Development",
   "type": "module",
   "main": "dist/index.js",