midnight-mcp 0.0.9 → 0.1.1

package/README.md

@@ -26,7 +26,7 @@ Add to your `claude_desktop_config.json`:
 ```
 
 <details>
-<summary><strong>📍 Config file locations</strong></summary>
+<summary><strong>Config file locations</strong></summary>
 
 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
@@ -36,6 +36,13 @@ Add to your `claude_desktop_config.json`:
 
 ### Cursor
 
+**Click the button to auto install the MCP for Cursor**
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=midnight&config=eyJjb21tYW5kIjoibnB4IC15IG1pZG5pZ2h0LW1jcCJ9)
+
+---
+**Manual setup instructions are below if you need them:**
+
 Add to Cursor's MCP settings (Settings → MCP → Add Server):
 
 ```json
@@ -62,6 +69,8 @@ Or add to `.cursor/mcp.json` in your project:
 }
 ```
 
+
+
 ### Windsurf
 
 Add to `~/.codeium/windsurf/mcp_config.json`:
@@ -87,11 +96,11 @@ Restart your editor after adding the config. All features work out of the box—
 
 By default, the MCP uses a **hosted API** for semantic search:
 
-- ✅ **Zero configuration** — just install and use
-- ✅ **Semantic search** works immediately
-- ✅ **No API keys** needed
+- **Zero configuration** — just install and use
+- **Semantic search** works immediately
+- **No API keys** needed
 
-> **📊 Quality Metrics**: To ensure the MCP stays accurate as Midnight's codebase evolves rapidly, we collect anonymous usage metrics (query counts, relevance scores) to monitor search quality. No query content or personal data is stored. This helps us identify when re-indexing is needed and improve results over time.
+> **Quality Metrics**: To ensure the MCP stays accurate as Midnight's codebase evolves rapidly, we collect anonymous usage metrics (query counts, relevance scores) to monitor search quality. No query content or personal data is stored. This helps us identify when re-indexing is needed and improve results over time.
 
 ### Local Mode (Optional)
 
@@ -123,26 +132,42 @@ Add `"GITHUB_TOKEN": "ghp_..."` for higher GitHub API rate limits (60 → 5000 r
 
 ## Features
 
-### Tools (16)
-
-| Tool                              | Description                             |
-| --------------------------------- | --------------------------------------- |
-| `midnight-search-compact`         | Search Compact contract code            |
-| `midnight-search-typescript`      | Search TypeScript SDK                   |
-| `midnight-search-docs`            | Search documentation                    |
-| `midnight-analyze-contract`       | Analyze contract structure and security |
-| `midnight-explain-circuit`        | Explain circuits in plain language      |
-| `midnight-get-file`               | Get files from Midnight repos           |
-| `midnight-list-examples`          | List example contracts                  |
-| `midnight-get-latest-updates`     | Recent repo changes                     |
-| `midnight-get-version-info`       | Get version and release info            |
-| `midnight-check-breaking-changes` | Check for breaking changes              |
-| `midnight-get-migration-guide`    | Migration guides between versions       |
-| `midnight-get-file-at-version`    | Get file at specific version            |
-| `midnight-compare-syntax`         | Compare files between versions          |
-| `midnight-get-latest-syntax`      | Latest syntax reference                 |
-| `midnight-health-check`           | Check server health status              |
-| `midnight-get-status`             | Get rate limits and cache stats         |
+### Tools (19)
+
+| Tool                              | Description                                 |
+| --------------------------------- | ------------------------------------------- |
+| `midnight-search-compact`         | Search Compact contract code                |
+| `midnight-search-typescript`      | Search TypeScript SDK                       |
+| `midnight-search-docs`            | Search documentation                        |
+| `midnight-analyze-contract`       | Analyze contract structure and security     |
+| `midnight-explain-circuit`        | Explain circuits in plain language          |
+| `midnight-get-file`               | Get files from Midnight repos               |
+| `midnight-list-examples`          | List example contracts                      |
+| `midnight-get-latest-updates`     | Recent repo changes                         |
+| `midnight-get-version-info`       | Get version and release info                |
+| `midnight-check-breaking-changes` | Check for breaking changes                  |
+| `midnight-get-migration-guide`    | Migration guides between versions           |
+| `midnight-get-file-at-version`    | Get file at specific version                |
+| `midnight-compare-syntax`         | Compare files between versions              |
+| `midnight-get-latest-syntax`      | Latest syntax reference                     |
+| `midnight-health-check`           | Check server health status                  |
+| `midnight-get-status`             | Get rate limits and cache stats             |
+| `midnight-generate-contract`      | AI-generate contracts from natural language |
+| `midnight-review-contract`        | AI-powered security review of contracts     |
+| `midnight-document-contract`      | AI-generate documentation for contracts     |
+
+> **Note:** The AI-powered tools require a client with [MCP Sampling](https://spec.modelcontextprotocol.io/specification/client/sampling/) support (e.g., Claude Desktop). Without sampling, these tools will return a helpful message instead.
+
+### Resource Templates (4)
+
+Dynamic access to any resource using URI templates:
+
+| Template                                | Description                    |
+| --------------------------------------- | ------------------------------ |
+| `midnight://code/{owner}/{repo}/{path}` | Any code file from any repo    |
+| `midnight://docs/{section}/{topic}`     | Documentation by section/topic |
+| `midnight://examples/{category}/{name}` | Example contracts by category  |
+| `midnight://schema/{type}`              | JSON schemas (AST, tx, proofs) |
 
 ### Resources (20)
 
@@ -192,7 +217,9 @@ The hosted API runs on Cloudflare Workers + Vectorize. See [api/README.md](./api
 
 ### Search Quality
 
-The API uses several techniques to improve search relevance:
+The API indexes **25 Midnight repositories** including core infrastructure, SDK, examples, ZK libraries, and developer tools.
+
+Search quality techniques:
 
 - **Optimized chunking** — 1000-char chunks with 200-char overlap for precise, contextual results
 - **Hybrid search** — Combines vector similarity with keyword boosting (up to 20% boost for exact matches)

package/dist/server.d.ts

@@ -1,8 +1,21 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+/**
+ * Clear all subscriptions (useful for server restart/testing)
+ */
+export declare function clearSubscriptions(): void;
 /**
  * Create and configure the MCP server
  */
 export declare function createServer(): Server;
+/**
+ * Notify subscribers when a resource changes
+ * Call this when re-indexing or when docs are updated
+ */
+export declare function notifyResourceUpdate(server: Server, uri: string): void;
+/**
+ * Get the list of active subscriptions
+ */
+export declare function getActiveSubscriptions(): string[];
 /**
  * Initialize the server and vector store
  */

package/dist/server.js

@@ -1,24 +1,67 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourceTemplatesRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { logger, formatErrorResponse } from "./utils/index.js";
 import { vectorStore } from "./db/index.js";
 import { allTools } from "./tools/index.js";
 import { allResources, getDocumentation, getCode, getSchema, } from "./resources/index.js";
 import { promptDefinitions, generatePrompt } from "./prompts/index.js";
+import { registerSamplingCallback } from "./services/index.js";
 // Server information
 const SERVER_INFO = {
     name: "midnight-mcp",
     version: "1.0.0",
     description: "MCP Server for Midnight Blockchain Development",
 };
+// Resource subscriptions tracking
+const resourceSubscriptions = new Set();
+/**
+ * Clear all subscriptions (useful for server restart/testing)
+ */
+export function clearSubscriptions() {
+    resourceSubscriptions.clear();
+    logger.debug("Subscriptions cleared");
+}
+// Resource templates for parameterized resources (RFC 6570 URI Templates)
+const resourceTemplates = [
+    {
+        uriTemplate: "midnight://code/{owner}/{repo}/{path}",
+        name: "Repository Code",
+        title: "📄 Repository Code Files",
+        description: "Access code files from any Midnight repository by specifying owner, repo, and file path",
+        mimeType: "text/plain",
+    },
+    {
+        uriTemplate: "midnight://docs/{section}/{topic}",
+        name: "Documentation",
+        title: "📚 Documentation Sections",
+        description: "Access documentation by section (guides, api, concepts) and topic",
+        mimeType: "text/markdown",
+    },
+    {
+        uriTemplate: "midnight://examples/{category}/{name}",
+        name: "Example Contracts",
+        title: "📝 Example Contracts",
+        description: "Access example contracts by category (counter, bboard, token, voting) and name",
+        mimeType: "text/x-compact",
+    },
+    {
+        uriTemplate: "midnight://schema/{type}",
+        name: "Schema Definitions",
+        title: "🔧 Schema Definitions",
+        description: "Access JSON schemas for contract AST, transactions, and proofs",
+        mimeType: "application/json",
+    },
+];
 /**
  * Create and configure the MCP server
  */
 export function createServer() {
     const server = new Server(SERVER_INFO, {
         capabilities: {
-            tools: {},
+            tools: {
+                listChanged: true,
+            },
             resources: {
                 subscribe: true,
                 listChanged: true,
@@ -34,13 +77,17 @@ export function createServer() {
     registerResourceHandlers(server);
     // Register prompt handlers
     registerPromptHandlers(server);
+    // Register subscription handlers
+    registerSubscriptionHandlers(server);
+    // Setup sampling callback if available
+    setupSampling(server);
     return server;
 }
 /**
  * Register tool handlers
  */
 function registerToolHandlers(server) {
-    // List available tools
+    // List available tools with annotations and output schemas
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         logger.debug("Listing tools");
         return {
@@ -48,6 +95,10 @@ function registerToolHandlers(server) {
                 name: tool.name,
                 description: tool.description,
                 inputSchema: tool.inputSchema,
+                // Include output schema if defined
+                ...(tool.outputSchema && { outputSchema: tool.outputSchema }),
+                // Include annotations if defined
+                ...(tool.annotations && { annotations: tool.annotations }),
             })),
         };
     });
@@ -117,6 +168,19 @@ function registerResourceHandlers(server) {
             })),
         };
     });
+    // List resource templates (RFC 6570 URI Templates)
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+        logger.debug("Listing resource templates");
+        return {
+            resourceTemplates: resourceTemplates.map((template) => ({
+                uriTemplate: template.uriTemplate,
+                name: template.name,
+                title: template.title,
+                description: template.description,
+                mimeType: template.mimeType,
+            })),
+        };
+    });
     // Read resource content
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         const { uri } = request.params;
@@ -221,6 +285,107 @@ function registerPromptHandlers(server) {
         };
     });
 }
+/**
+ * Register resource subscription handlers
+ */
+function registerSubscriptionHandlers(server) {
+    // Handle subscribe requests
+    server.setRequestHandler(SubscribeRequestSchema, async (request) => {
+        const { uri } = request.params;
+        logger.info(`Subscribing to resource: ${uri}`);
+        // Validate that the URI is a valid resource
+        const validPrefixes = [
+            "midnight://docs/",
+            "midnight://code/",
+            "midnight://schema/",
+        ];
+        const isValid = validPrefixes.some((prefix) => uri.startsWith(prefix));
+        if (!isValid) {
+            logger.warn(`Invalid subscription URI: ${uri}`);
+            throw new Error(`Invalid subscription URI: ${uri}. Valid prefixes: ${validPrefixes.join(", ")}`);
+        }
+        resourceSubscriptions.add(uri);
+        logger.debug(`Active subscriptions: ${resourceSubscriptions.size}`);
+        return {};
+    });
+    // Handle unsubscribe requests
+    server.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
+        const { uri } = request.params;
+        logger.info(`Unsubscribing from resource: ${uri}`);
+        resourceSubscriptions.delete(uri);
+        logger.debug(`Active subscriptions: ${resourceSubscriptions.size}`);
+        return {};
+    });
+}
+/**
+ * Notify subscribers when a resource changes
+ * Call this when re-indexing or when docs are updated
+ */
+export function notifyResourceUpdate(server, uri) {
+    if (resourceSubscriptions.has(uri)) {
+        logger.info(`Notifying subscribers of update: ${uri}`);
+        // Send notification via the server
+        server.notification({
+            method: "notifications/resources/updated",
+            params: { uri },
+        });
+    }
+}
+/**
+ * Get the list of active subscriptions
+ */
+export function getActiveSubscriptions() {
+    return Array.from(resourceSubscriptions);
+}
+/**
+ * Setup sampling capability
+ * Registers a callback that allows the server to request LLM completions
+ */
+function setupSampling(server) {
+    // Create a sampling callback that uses the server's request method
+    const samplingCallback = async (request) => {
+        logger.debug("Requesting sampling from client", {
+            messageCount: request.messages.length,
+            maxTokens: request.maxTokens,
+        });
+        try {
+            // Request completion from the client
+            const response = await server.request({
+                method: "sampling/createMessage",
+                params: {
+                    messages: request.messages,
+                    systemPrompt: request.systemPrompt,
+                    maxTokens: request.maxTokens || 2048,
+                    temperature: request.temperature,
+                    modelPreferences: request.modelPreferences,
+                },
+            }, 
+            // Use a schema that matches the expected response
+            {
+                parse: (data) => {
+                    const response = data;
+                    // Basic validation of expected response structure
+                    if (!response || typeof response !== "object") {
+                        throw new Error("Invalid sampling response: expected object");
+                    }
+                    if (!response.content || typeof response.content !== "object") {
+                        throw new Error("Invalid sampling response: missing content");
+                    }
+                    return response;
+                },
+                _def: { typeName: "SamplingResponse" },
+            });
+            return response;
+        }
+        catch (error) {
+            logger.error("Sampling request failed", { error: String(error) });
+            throw error;
+        }
+    };
+    // Register the callback
+    registerSamplingCallback(samplingCallback);
+    logger.info("Sampling capability configured");
+}
 /**
  * Initialize the server and vector store
  */

package/dist/services/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Services index
+ * Export all service modules
+ */
+export { isSamplingAvailable, registerSamplingCallback, requestCompletion, generateContract, reviewContract, generateDocumentation, } from "./sampling.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/services/index.js

@@ -0,0 +1,6 @@
+/**
+ * Services index
+ * Export all service modules
+ */
+export { isSamplingAvailable, registerSamplingCallback, requestCompletion, generateContract, reviewContract, generateDocumentation, } from "./sampling.js";
+//# sourceMappingURL=index.js.map

package/dist/services/sampling.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 type { SamplingRequest, SamplingResponse, ModelPreferences } from "../types/index.js";
+type SamplingCallback = (request: SamplingRequest) => Promise<SamplingResponse>;
+/**
+ * Check if sampling is available
+ */
+export declare function isSamplingAvailable(): boolean;
+/**
+ * Register the sampling callback from the client
+ * This is called during server initialization when client supports sampling
+ */
+export declare function registerSamplingCallback(callback: SamplingCallback): void;
+/**
+ * Request a completion from the LLM via the client
+ */
+export declare function requestCompletion(messages: {
+    role: "user" | "assistant";
+    content: string;
+}[], options?: {
+    systemPrompt?: string;
+    maxTokens?: number;
+    temperature?: number;
+    modelPreferences?: ModelPreferences;
+}): Promise<string>;
+/**
+ * Generate a Compact contract based on requirements
+ */
+export declare function generateContract(requirements: string, options?: {
+    baseExample?: string;
+    contractType?: "counter" | "token" | "voting" | "custom";
+}): Promise<{
+    code: string;
+    explanation: string;
+    warnings: string[];
+}>;
+/**
+ * Review contract code and suggest improvements
+ */
+export declare function reviewContract(code: string): Promise<{
+    summary: string;
+    issues: Array<{
+        severity: "error" | "warning" | "info";
+        line?: number;
+        message: string;
+        suggestion?: string;
+    }>;
+    improvedCode?: string;
+}>;
+/**
+ * Generate documentation for a contract
+ */
+export declare function generateDocumentation(code: string, format?: "markdown" | "jsdoc"): Promise<string>;
+export {};
+//# sourceMappingURL=sampling.d.ts.map