midnight-mcp 0.0.9 → 0.1.1

package/dist/services/sampling.js

@@ -0,0 +1,277 @@
+/**
+ * Sampling service for agentic workflows
+ *
+ * Enables the MCP server to request LLM completions from the client,
+ * allowing for sophisticated multi-step workflows like:
+ * - Auto-generating contracts from examples
+ * - Code review with suggested fixes
+ * - Documentation generation
+ */
+import { logger } from "../utils/index.js";
+// Store for the sampling callback
+let samplingCallback = null;
+/**
+ * Check if sampling is available
+ */
+export function isSamplingAvailable() {
+    return samplingCallback !== null;
+}
+/**
+ * Register the sampling callback from the client
+ * This is called during server initialization when client supports sampling
+ */
+export function registerSamplingCallback(callback) {
+    samplingCallback = callback;
+    logger.info("Sampling capability registered");
+}
+/**
+ * Request a completion from the LLM via the client
+ */
+export async function requestCompletion(messages, options = {}) {
+    if (!samplingCallback) {
+        throw new Error("Sampling not available - client does not support this capability");
+    }
+    const request = {
+        messages: messages.map((m) => ({
+            role: m.role,
+            content: { type: "text", text: m.content },
+        })),
+        systemPrompt: options.systemPrompt,
+        maxTokens: options.maxTokens ?? 2048,
+        temperature: options.temperature ?? 0.7,
+        modelPreferences: options.modelPreferences ?? {
+            hints: [{ name: "claude-3-sonnet" }, { name: "gpt-4" }],
+            intelligencePriority: 0.8,
+            speedPriority: 0.5,
+        },
+    };
+    logger.debug("Requesting LLM completion", {
+        messageCount: messages.length,
+        maxTokens: request.maxTokens,
+    });
+    const response = await samplingCallback(request);
+    if (response.content.type !== "text") {
+        throw new Error("Unexpected response content type");
+    }
+    return response.content.text;
+}
+/**
+ * Generate a Compact contract based on requirements
+ */
+export async function generateContract(requirements, options = {}) {
+    if (!isSamplingAvailable()) {
+        return {
+            code: "",
+            explanation: "Sampling not available - this feature requires a client that supports the sampling capability (like Claude Desktop)",
+            warnings: ["Feature unavailable without sampling support"],
+        };
+    }
+    const systemPrompt = `You are an expert Compact smart contract developer for the Midnight blockchain.
+Your task is to generate secure, well-documented Compact contracts based on user requirements.
+
+Key Compact concepts:
+- \`ledger { }\` - Defines on-chain state (public and private)
+- \`@private\` - Marks state as private/shielded
+- \`export circuit\` - Public functions that generate ZK proofs
+- \`witness\` - Off-chain computation functions
+- \`assert()\` - Creates ZK constraints
+- \`Counter\`, \`Map<K,V>\`, \`Set<T>\` - Built-in collection types
+- \`Field\`, \`Boolean\`, \`Uint<N>\`, \`Bytes<N>\` - Primitive types
+
+Always include:
+1. Proper imports (include "std")
+2. Clear ledger state definitions
+3. Access control where appropriate
+4. Comprehensive inline comments
+
+Return ONLY the Compact code, no explanations.`;
+    const userPrompt = options.baseExample
+        ? `Based on this example contract:
+\`\`\`compact
+${options.baseExample}
+\`\`\`
+
+Generate a new contract with these requirements:
+${requirements}`
+        : `Generate a Compact smart contract with these requirements:
+${requirements}
+
+Contract type: ${options.contractType || "custom"}`;
+    try {
+        const code = await requestCompletion([{ role: "user", content: userPrompt }], {
+            systemPrompt,
+            maxTokens: 4096,
+            temperature: 0.3, // Lower temperature for code generation
+            modelPreferences: {
+                hints: [{ name: "claude-3-sonnet" }],
+                intelligencePriority: 0.9,
+                speedPriority: 0.3,
+            },
+        });
+        // Extract code from markdown if wrapped
+        const extractedCode = code.includes("```")
+            ? code
+                .replace(/```compact?\n?/g, "")
+                .replace(/```/g, "")
+                .trim()
+            : code.trim();
+        // Generate explanation
+        const explanation = await requestCompletion([
+            {
+                role: "user",
+                content: `Briefly explain what this Compact contract does (2-3 sentences):
+\`\`\`compact
+${extractedCode}
+\`\`\``,
+            },
+        ], {
+            systemPrompt: "You are a Compact contract documentation expert. Be concise.",
+            maxTokens: 256,
+            temperature: 0.5,
+        });
+        return {
+            code: extractedCode,
+            explanation: explanation.trim(),
+            warnings: [],
+        };
+    }
+    catch (error) {
+        logger.error("Contract generation failed", { error: String(error) });
+        return {
+            code: "",
+            explanation: `Contract generation failed: ${String(error)}`,
+            warnings: ["Generation failed - check logs for details"],
+        };
+    }
+}
+/**
+ * Review contract code and suggest improvements
+ */
+export async function reviewContract(code) {
+    if (!isSamplingAvailable()) {
+        return {
+            summary: "Code review requires sampling capability",
+            issues: [
+                {
+                    severity: "info",
+                    message: "This feature requires a client that supports the sampling capability",
+                },
+            ],
+        };
+    }
+    const systemPrompt = `You are a Compact smart contract security auditor.
+Review the provided contract for:
+1. Security vulnerabilities
+2. Privacy concerns (improper handling of shielded state)
+3. Logic errors
+4. Best practice violations
+5. Gas/performance issues
+
+Respond in JSON format:
+{
+  "summary": "Brief summary of the contract and overall quality",
+  "issues": [
+    {
+      "severity": "error|warning|info",
+      "line": optional_line_number,
+      "message": "Description of the issue",
+      "suggestion": "How to fix it"
+    }
+  ],
+  "improvedCode": "Full improved contract code if changes are needed"
+}`;
+    try {
+        const response = await requestCompletion([
+            {
+                role: "user",
+                content: `Review this Compact contract:\n\`\`\`compact\n${code}\n\`\`\``,
+            },
+        ], {
+            systemPrompt,
+            maxTokens: 4096,
+            temperature: 0.2,
+        });
+        // Parse JSON response with error handling
+        const jsonMatch = response.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+            try {
+                const parsed = JSON.parse(jsonMatch[0]);
+                // Validate expected structure
+                return {
+                    summary: typeof parsed.summary === "string"
+                        ? parsed.summary
+                        : "Review complete",
+                    issues: Array.isArray(parsed.issues) ? parsed.issues : [],
+                    improvedCode: typeof parsed.improvedCode === "string"
+                        ? parsed.improvedCode
+                        : undefined,
+                };
+            }
+            catch (parseError) {
+                logger.warn("Failed to parse JSON from LLM response", {
+                    error: String(parseError),
+                });
+                return {
+                    summary: response,
+                    issues: [],
+                };
+            }
+        }
+        return {
+            summary: response,
+            issues: [],
+        };
+    }
+    catch (error) {
+        logger.error("Contract review failed", { error: String(error) });
+        return {
+            summary: `Review failed: ${String(error)}`,
+            issues: [
+                {
+                    severity: "error",
+                    message: "Review failed - check logs for details",
+                },
+            ],
+        };
+    }
+}
+/**
+ * Generate documentation for a contract
+ */
+export async function generateDocumentation(code, format = "markdown") {
+    if (!isSamplingAvailable()) {
+        return "Documentation generation requires sampling capability";
+    }
+    const systemPrompt = format === "markdown"
+        ? `Generate comprehensive Markdown documentation for this Compact contract.
+Include:
+- Overview and purpose
+- State variables (with privacy annotations)
+- Circuit functions with parameters and effects
+- Witness functions
+- Usage examples
+- Security considerations`
+        : `Generate JSDoc-style documentation comments for this Compact contract.
+Add documentation comments above each:
+- Ledger field
+- Circuit function
+- Witness function
+- Type definition`;
+    try {
+        return await requestCompletion([
+            {
+                role: "user",
+                content: `Generate ${format} documentation for:\n\`\`\`compact\n${code}\n\`\`\``,
+            },
+        ], {
+            systemPrompt,
+            maxTokens: 4096,
+            temperature: 0.5,
+        });
+    }
+    catch (error) {
+        logger.error("Documentation generation failed", { error: String(error) });
+        return `Documentation generation failed: ${String(error)}`;
+    }
+}
+//# sourceMappingURL=sampling.js.map

package/dist/tools/analyze.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { ExtendedToolDefinition } from "../types/index.js";
 export declare const AnalyzeContractInputSchema: z.ZodObject<{
     code: z.ZodString;
     checkSecurity: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
@@ -100,41 +101,6 @@ export declare function explainCircuit(input: ExplainCircuitInput): Promise<{
     error?: undefined;
     suggestion?: undefined;
 }>;
-export declare const analyzeTools: ({
-    name: string;
-    description: string;
-    inputSchema: {
-        type: "object";
-        properties: {
-            code: {
-                type: string;
-                description: string;
-            };
-            checkSecurity: {
-                type: string;
-                description: string;
-            };
-            circuitCode?: undefined;
-        };
-        required: string[];
-    };
-    handler: typeof analyzeContract;
-} | {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: "object";
-        properties: {
-            circuitCode: {
-                type: string;
-                description: string;
-            };
-            code?: undefined;
-            checkSecurity?: undefined;
-        };
-        required: string[];
-    };
-    handler: typeof explainCircuit;
-})[];
+export declare const analyzeTools: ExtendedToolDefinition[];
 export {};
 //# sourceMappingURL=analyze.d.ts.map

package/dist/tools/analyze.js

@@ -230,6 +230,149 @@ function getPrivacyConsiderations(circuit) {
     }
     return considerations;
 }
+// Output schemas for analysis tools - aligned with actual function return types
+const analyzeContractOutputSchema = {
+    type: "object",
+    properties: {
+        summary: {
+            type: "object",
+            description: "Summary statistics of the contract",
+            properties: {
+                hasLedger: { type: "boolean" },
+                hasCircuits: { type: "boolean" },
+                hasWitnesses: { type: "boolean" },
+                totalLines: { type: "number" },
+                publicCircuits: { type: "number" },
+                privateCircuits: { type: "number" },
+                publicState: { type: "number" },
+                privateState: { type: "number" },
+            },
+        },
+        structure: {
+            type: "object",
+            description: "Contract structure breakdown",
+            properties: {
+                imports: { type: "array", items: { type: "string" } },
+                exports: { type: "array", items: { type: "string" } },
+                ledger: {
+                    type: "array",
+                    description: "Ledger state fields",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            type: { type: "string" },
+                            isPrivate: { type: "boolean" },
+                        },
+                    },
+                },
+                circuits: {
+                    type: "array",
+                    description: "Circuit definitions",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            isPublic: { type: "boolean" },
+                            parameters: { type: "array", items: { type: "object" } },
+                            returnType: { type: "string" },
+                        },
+                    },
+                },
+                witnesses: {
+                    type: "array",
+                    description: "Witness functions",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            parameters: { type: "array", items: { type: "object" } },
+                            returnType: { type: "string" },
+                        },
+                    },
+                },
+                types: {
+                    type: "array",
+                    description: "Type definitions",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            definition: { type: "string" },
+                        },
+                    },
+                },
+            },
+        },
+        securityFindings: {
+            type: "array",
+            description: "Security analysis findings",
+            items: {
+                type: "object",
+                properties: {
+                    severity: {
+                        type: "string",
+                        enum: ["info", "warning", "error"],
+                    },
+                    message: { type: "string" },
+                    suggestion: { type: "string" },
+                },
+            },
+        },
+        recommendations: {
+            type: "array",
+            items: { type: "string" },
+            description: "Recommendations for improvement",
+        },
+    },
+    required: ["summary", "structure", "securityFindings", "recommendations"],
+    description: "Detailed contract analysis with security findings",
+};
+const explainCircuitOutputSchema = {
+    type: "object",
+    properties: {
+        circuitName: { type: "string", description: "Circuit name" },
+        isPublic: { type: "boolean", description: "Whether it's exported" },
+        parameters: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    name: { type: "string" },
+                    type: { type: "string" },
+                },
+            },
+            description: "Circuit parameters",
+        },
+        returnType: { type: "string", description: "Return type" },
+        explanation: {
+            type: "string",
+            description: "Plain language explanation",
+        },
+        operations: {
+            type: "array",
+            items: { type: "string" },
+            description: "Operations performed by the circuit",
+        },
+        zkImplications: {
+            type: "array",
+            items: { type: "string" },
+            description: "Zero-knowledge proof implications",
+        },
+        privacyConsiderations: {
+            type: "array",
+            items: { type: "string" },
+            description: "Privacy-related considerations",
+        },
+    },
+    required: [
+        "circuitName",
+        "explanation",
+        "zkImplications",
+        "privacyConsiderations",
+    ],
+    description: "Detailed circuit explanation with privacy analysis",
+};
 // Tool definitions for MCP
 export const analyzeTools = [
     {
@@ -249,6 +392,12 @@ export const analyzeTools = [
             },
             required: ["code"],
         },
+        outputSchema: analyzeContractOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            title: "Analyze Compact Contract",
+        },
         handler: analyzeContract,
     },
     {
@@ -264,6 +413,12 @@ export const analyzeTools = [
             },
             required: ["circuitCode"],
         },
+        outputSchema: explainCircuitOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            title: "Explain Circuit",
+        },
         handler: explainCircuit,
     },
 ];

package/dist/tools/generation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Contract generation tool using sampling capability
+ *
+ * Enables AI-assisted generation and review of Compact smart contracts
+ */
+import type { ExtendedToolDefinition } from "../types/index.js";
+export declare const generationTools: ExtendedToolDefinition[];
+export declare const generationHandlers: Record<string, (args: any) => Promise<any>>;
+//# sourceMappingURL=generation.d.ts.map