midnight-mcp 0.1.9 → 0.1.11

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/constants.js

@@ -78,6 +78,14 @@ export const REPO_ALIASES = {
     starter: { owner: "MeshJS", repo: "midnight-starter-template" },
     midnames: { owner: "midnames", repo: "core" },
     did: { owner: "midnames", repo: "core" },
+    // Sea Battle Hackathon Winners (Feb 2025)
+    "naval-battle": { owner: "ErickRomeroDev", repo: "naval-battle-game_v2" },
+    "edda-labs": { owner: "ErickRomeroDev", repo: "naval-battle-game_v2" },
+    "sea-battle-hackathon": {
+        owner: "eddex",
+        repo: "midnight-sea-battle-hackathon",
+    },
+    shipyspace: { owner: "eddex", repo: "midnight-sea-battle-hackathon" },
 };
 export const EXAMPLES = [
     {
@@ -124,5 +132,51 @@ export const EXAMPLES = [
             "Advanced state management",
         ],
     },
+    // Sea Battle Hackathon Winners (Feb 2025)
+    {
+        name: "Sea Battle (Brick Towers)",
+        repository: "bricktowers/midnight-seabattle",
+        description: "1st place hackathon winner. Fully playable battleship game with token staking (100 shielded tBTC). Features ZK-protected ship placements and moves.",
+        category: "game",
+        complexity: "advanced",
+        mainFile: "contract/src/seabattle.compact",
+        features: [
+            "ZK game mechanics",
+            "Shielded token staking",
+            "Turn-based gameplay",
+            "Private state management",
+            "Lace wallet integration",
+        ],
+    },
+    {
+        name: "Naval Battle (Edda Labs)",
+        repository: "ErickRomeroDev/naval-battle-game_v2",
+        description: "2nd place hackathon winner. Clean implementation with 4 ZK circuits: join game, commit grid, start game, make move. Modern drag-and-drop UI.",
+        category: "game",
+        complexity: "intermediate",
+        mainFile: "contract/src/naval.compact",
+        features: [
+            "4 ZK circuits",
+            "Drag-and-drop UI",
+            "Real-time updates",
+            "Clean circuit design",
+            "Open-source docs",
+        ],
+    },
+    {
+        name: "Sea Battle (ShipySpace)",
+        repository: "eddex/midnight-sea-battle-hackathon",
+        description: "3rd place hackathon winner. Great beginner-friendly example showing core game mechanics without centralized server. Good first ZK project reference.",
+        category: "game",
+        complexity: "beginner",
+        mainFile: "contract/src/game.compact",
+        features: [
+            "No centralized server",
+            "Deploy/join/resume games",
+            "Basic ZK patterns",
+            "Beginner friendly",
+            "Clear player interactions",
+        ],
+    },
 ];
 //# sourceMappingURL=constants.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