midnight-mcp 0.0.2 → 0.0.5

package/README.md

@@ -17,29 +17,21 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-Restart Claude Desktop. You can now use analysis tools, prompts, and access resources.
-
-> **Note:** Search features won't work well without the full setup below.
+Restart Claude Desktop. All features work out of the box—no API keys or setup required.
 
 ---
 
-## Full Setup (for search)
-
-To enable semantic search across Midnight contracts and docs:
-
-### 1. Start ChromaDB
-
-ChromaDB is a local vector database—no account needed, just Docker:
+## How It Works
 
-```bash
-docker run -d -p 8000:8000 chromadb/chroma
-```
+By default, the MCP uses a **hosted API** for semantic search:
 
-### 2. Get an OpenAI API key
+- ✅ **Zero configuration** — just install and use
+- ✅ **Semantic search** works immediately
+- ✅ **No API keys** needed
 
-Needed for generating embeddings. Get one at [platform.openai.com/api-keys](https://platform.openai.com/api-keys).
+### Local Mode (Optional)
 
-### 3. Update your config
+Run everything locally for privacy or offline use:
 
 ```json
 {
@@ -48,6 +40,7 @@ Needed for generating embeddings. Get one at [platform.openai.com/api-keys](http
       "command": "npx",
       "args": ["-y", "midnight-mcp"],
       "env": {
+        "MIDNIGHT_LOCAL": "true",
         "OPENAI_API_KEY": "sk-...",
         "CHROMA_URL": "http://localhost:8000"
       }
@@ -56,28 +49,38 @@ Needed for generating embeddings. Get one at [platform.openai.com/api-keys](http
 }
 ```
 
-### Optional: GitHub token
+Local mode requires ChromaDB (`docker run -d -p 8000:8000 chromadb/chroma`) and an OpenAI API key.
 
-Add `"GITHUB_TOKEN": "ghp_..."` to increase API rate limits from 60 to 5000 requests/hour.
-
----
+### GitHub Token (Optional)
 
-## What's Included
+Add `"GITHUB_TOKEN": "ghp_..."` for higher GitHub API rate limits (60 → 5000 requests/hour).
 
-### Tools
-
-| 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                     |
+---
 
-### Resources
+## 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         |
+
+### Resources (20)
 
 - `midnight://docs/*` — Documentation (Compact reference, SDK API, ZK concepts)
 - `midnight://code/*` — Examples, patterns, and templates
@@ -85,16 +88,17 @@ Add `"GITHUB_TOKEN": "ghp_..."` to increase API rate limits from 60 to 5000 requ
 
 ### Prompts
 
-- `midnight:create-contract` — Create new contracts
-- `midnight:review-contract` — Security review
-- `midnight:explain-concept` — Learn Midnight concepts
-- `midnight:debug-contract` — Debug issues
+- `midnight-create-contract` — Create new contracts
+- `midnight-review-contract` — Security review
+- `midnight-explain-concept` — Learn Midnight concepts
+- `midnight-compare-approaches` — Compare implementation approaches
+- `midnight-debug-contract` — Debug issues
 
 ---
 
 ## Developer Setup
 
-For contributors who want to modify or extend the MCP server.
+For contributors:
 
 ```bash
 git clone https://github.com/Olanetsoft/midnight-mcp.git
@@ -104,26 +108,23 @@ npm run build
 npm test
 ```
 
-### Index Midnight repos (for search)
+### Testing with Local API
+
+To test against a local API server instead of production:
 
 ```bash
-docker run -d -p 8000:8000 chromadb/chroma
-npm run index
+# Terminal 1: Start local API
+cd api
+npm install
+npm run dev  # Starts at http://localhost:8787
+
+# Terminal 2: Run MCP with local API
+MIDNIGHT_API_URL=http://localhost:8787 npm start
 ```
 
-### Project Structure
+### API Backend
 
-```
-src/
-├── index.ts          # Entry point
-├── server.ts         # MCP server handlers
-├── tools/            # Search, analysis, repository tools
-├── resources/        # Docs, code, schema providers
-├── prompts/          # Prompt templates
-├── pipeline/         # GitHub sync & parsing
-├── db/               # ChromaDB integration
-└── utils/            # Config & logging
-```
+The hosted API runs on Cloudflare Workers + Vectorize. See [api/README.md](./api/README.md) for deployment and development instructions.
 
 ## License
 

package/dist/pipeline/github.d.ts

@@ -1,4 +1,4 @@
-import { RepositoryConfig } from "../utils/index.js";
+import { RepositoryConfig, getRateLimitStatus } from "../utils/index.js";
 export interface GitHubFile {
     path: string;
     content: string;
@@ -62,6 +62,23 @@ export declare class GitHubClient {
         repository: string;
         url: string;
     }>>;
+    /**
+     * Get current rate limit status from GitHub API
+     */
+    getRateLimit(): Promise<{
+        limit: number;
+        remaining: number;
+        reset: Date;
+        used: number;
+    }>;
+    /**
+     * Check if it's safe to make API requests
+     */
+    checkRateLimit(): {
+        proceed: boolean;
+        reason?: string;
+        status: ReturnType<typeof getRateLimitStatus>;
+    };
 }
 export declare const githubClient: GitHubClient;
 //# sourceMappingURL=github.d.ts.map

package/dist/pipeline/github.js

@@ -1,5 +1,87 @@
 import { Octokit } from "octokit";
-import { config, logger } from "../utils/index.js";
+import { config, logger, updateRateLimit, shouldProceedWithRequest, getRateLimitStatus, } from "../utils/index.js";
+// Retry configuration
+const RETRY_CONFIG = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 10000,
+};
+/**
+ * Retry wrapper with exponential backoff
+ */
+async function withRetry(operation, operationName) {
+    let lastError = null;
+    for (let attempt = 1; attempt <= RETRY_CONFIG.maxRetries; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            const isRetryable = isRetryableError(error);
+            if (!isRetryable || attempt === RETRY_CONFIG.maxRetries) {
+                logger.error(`${operationName} failed after ${attempt} attempt(s)`, {
+                    error: String(error),
+                    attempt,
+                });
+                throw enhanceError(error, operationName);
+            }
+            const delay = Math.min(RETRY_CONFIG.baseDelayMs * Math.pow(2, attempt - 1), RETRY_CONFIG.maxDelayMs);
+            logger.warn(`${operationName} failed, retrying in ${delay}ms...`, {
+                attempt,
+                error: String(error),
+            });
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}
+/**
+ * Check if an error is retryable
+ */
+function isRetryableError(error) {
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        // Retry on network errors, rate limits, and server errors
+        return (message.includes("network") ||
+            message.includes("timeout") ||
+            message.includes("econnreset") ||
+            message.includes("rate limit") ||
+            message.includes("403") ||
+            message.includes("500") ||
+            message.includes("502") ||
+            message.includes("503") ||
+            message.includes("504"));
+    }
+    return false;
+}
+/**
+ * Enhance error with more context
+ */
+function enhanceError(error, operation) {
+    const originalMessage = error instanceof Error ? error.message : String(error);
+    // Provide user-friendly error messages
+    if (originalMessage.includes("rate limit") ||
+        originalMessage.includes("403")) {
+        return new Error(`GitHub API rate limit exceeded during ${operation}. ` +
+            `Add a GITHUB_TOKEN to your config to increase limits from 60 to 5000 requests/hour.`);
+    }
+    if (originalMessage.includes("404")) {
+        return new Error(`Resource not found during ${operation}. ` +
+            `Check that the repository/file exists and is accessible.`);
+    }
+    if (originalMessage.includes("timeout") ||
+        originalMessage.includes("network")) {
+        return new Error(`Network error during ${operation}. ` +
+            `Check your internet connection and try again.`);
+    }
+    return new Error(`${operation} failed: ${originalMessage}`);
+}
+/**
+ * Sleep for a given number of milliseconds
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 class SimpleCache {
     cache = new Map();
     ttlMs;
@@ -47,15 +129,8 @@ export class GitHubClient {
             return cached;
         }
         try {
-            const { data: repoData } = await this.octokit.rest.repos.get({
-                owner,
-                repo,
-            });
-            const { data: commits } = await this.octokit.rest.repos.listCommits({
-                owner,
-                repo,
-                per_page: 1,
-            });
+            const { data: repoData } = await withRetry(() => this.octokit.rest.repos.get({ owner, repo }), `getRepositoryInfo(${owner}/${repo})`);
+            const { data: commits } = await withRetry(() => this.octokit.rest.repos.listCommits({ owner, repo, per_page: 1 }), `getCommits(${owner}/${repo})`);
             const lastCommit = commits[0]
                 ? {
                     sha: commits[0].sha,
@@ -93,12 +168,7 @@ export class GitHubClient {
             return cached;
         }
         try {
-            const { data } = await this.octokit.rest.repos.getContent({
-                owner,
-                repo,
-                path,
-                ref,
-            });
+            const { data } = await withRetry(() => this.octokit.rest.repos.getContent({ owner, repo, path, ref }), `getFileContent(${owner}/${repo}/${path})`);
             if (Array.isArray(data) || data.type !== "file") {
                 return null;
             }
@@ -133,17 +203,17 @@ export class GitHubClient {
             return cached;
         }
         try {
-            const { data: refData } = await this.octokit.rest.git.getRef({
+            const { data: refData } = await withRetry(() => this.octokit.rest.git.getRef({
                 owner,
                 repo,
                 ref: `heads/${ref || "main"}`,
-            });
-            const { data: treeData } = await this.octokit.rest.git.getTree({
+            }), `getRef(${owner}/${repo})`);
+            const { data: treeData } = await withRetry(() => this.octokit.rest.git.getTree({
                 owner,
                 repo,
                 tree_sha: refData.object.sha,
                 recursive: "true",
-            });
+            }), `getTree(${owner}/${repo})`);
             const result = treeData.tree
                 .filter((item) => item.type === "blob" && item.path)
                 .map((item) => item.path);
@@ -282,6 +352,48 @@ export class GitHubClient {
             return [];
         }
     }
+    /**
+     * Get current rate limit status from GitHub API
+     */
+    async getRateLimit() {
+        try {
+            const { data } = await this.octokit.rest.rateLimit.get();
+            const rateLimit = {
+                limit: data.rate.limit,
+                remaining: data.rate.remaining,
+                reset: new Date(data.rate.reset * 1000),
+                used: data.rate.used,
+            };
+            // Update the global rate limit tracker
+            updateRateLimit(rateLimit);
+            return rateLimit;
+        }
+        catch (error) {
+            logger.warn("Failed to get rate limit", { error: String(error) });
+            // Return defaults if we can't get rate limit
+            return {
+                limit: 60,
+                remaining: 60,
+                reset: new Date(Date.now() + 3600000),
+                used: 0,
+            };
+        }
+    }
+    /**
+     * Check if it's safe to make API requests
+     */
+    checkRateLimit() {
+        const check = shouldProceedWithRequest();
+        const status = getRateLimitStatus();
+        if (!check.proceed) {
+            logger.warn("Rate limit check failed", { reason: check.reason });
+        }
+        return {
+            proceed: check.proceed,
+            reason: check.reason,
+            status,
+        };
+    }
 }
 export const githubClient = new GitHubClient();
 //# sourceMappingURL=github.js.map

package/dist/server.js

@@ -1,7 +1,7 @@
 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 { logger } from "./utils/index.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";
@@ -57,11 +57,19 @@ function registerToolHandlers(server) {
         logger.info(`Tool called: ${name}`, { args });
         const tool = allTools.find((t) => t.name === name);
         if (!tool) {
+            const availableTools = allTools
+                .map((t) => t.name)
+                .slice(0, 5)
+                .join(", ");
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Unknown tool: ${name}`,
+                        text: JSON.stringify({
+                            error: `Unknown tool: ${name}`,
+                            suggestion: `Available tools include: ${availableTools}...`,
+                            hint: "Use ListTools to see all available tools",
+                        }, null, 2),
                     },
                 ],
                 isError: true,
@@ -80,11 +88,12 @@ function registerToolHandlers(server) {
         }
         catch (error) {
             logger.error(`Tool error: ${name}`, { error: String(error) });
+            const errorResponse = formatErrorResponse(error, `tool:${name}`);
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Error executing ${name}: ${error}`,
+                        text: JSON.stringify(errorResponse, null, 2),
                     },
                 ],
                 isError: true,
@@ -129,12 +138,24 @@ function registerResourceHandlers(server) {
                 mimeType = "application/json";
             }
             if (!content) {
+                const resourceTypes = [
+                    "midnight://docs/",
+                    "midnight://code/",
+                    "midnight://schema/",
+                ];
+                const validPrefix = resourceTypes.find((p) => uri.startsWith(p));
                 return {
                     contents: [
                         {
                             uri,
-                            mimeType: "text/plain",
-                            text: `Resource not found: ${uri}`,
+                            mimeType: "application/json",
+                            text: JSON.stringify({
+                                error: `Resource not found: ${uri}`,
+                                suggestion: validPrefix
+                                    ? `Check the resource path after '${validPrefix}'`
+                                    : `Valid resource prefixes: ${resourceTypes.join(", ")}`,
+                                hint: "Use ListResources to see all available resources",
+                            }, null, 2),
                         },
                     ],
                 };
@@ -151,12 +172,13 @@ function registerResourceHandlers(server) {
         }
         catch (error) {
             logger.error(`Resource error: ${uri}`, { error: String(error) });
+            const errorResponse = formatErrorResponse(error, `resource:${uri}`);
             return {
                 contents: [
                     {
                         uri,
-                        mimeType: "text/plain",
-                        text: `Error reading resource: ${error}`,
+                        mimeType: "application/json",
+                        text: JSON.stringify(errorResponse, null, 2),
                     },
                 ],
             };

package/dist/tools/health.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Health check and diagnostic tools for MCP server
+ */
+import { z } from "zod";
+export declare const HealthCheckInputSchema: z.ZodObject<{
+    detailed: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    detailed: boolean;
+}, {
+    detailed?: boolean | undefined;
+}>;
+export declare const GetStatusInputSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export type HealthCheckInput = z.infer<typeof HealthCheckInputSchema>;
+export type GetStatusInput = z.infer<typeof GetStatusInputSchema>;
+/**
+ * Perform health check on the MCP server
+ */
+export declare function healthCheck(input: HealthCheckInput): Promise<{
+    rateLimit: string;
+    cacheStats: {
+        search: import("../utils/cache.js").CacheStats;
+        file: import("../utils/cache.js").CacheStats;
+        metadata: import("../utils/cache.js").CacheStats;
+    };
+    status: "healthy" | "degraded" | "unhealthy";
+    timestamp: string;
+    version: string;
+    uptime: number;
+    checks: {
+        name: string;
+        status: "pass" | "warn" | "fail";
+        message?: string;
+        latency?: number;
+    }[];
+} | {
+    rateLimit: string;
+    status: "healthy" | "degraded" | "unhealthy";
+    version: string;
+    timestamp: string;
+    uptime: number;
+    checks: {
+        name: string;
+        status: "pass";
+    }[];
+}>;
+/**
+ * Get current server status and statistics
+ */
+export declare function getStatus(_input: GetStatusInput): Promise<{
+    server: string;
+    status: string;
+    timestamp: string;
+    rateLimit: {
+        remaining: number;
+        limit: number;
+        percentUsed: number;
+        status: string;
+        message: string;
+    };
+    cache: {
+        search: import("../utils/cache.js").CacheStats;
+        file: import("../utils/cache.js").CacheStats;
+        metadata: import("../utils/cache.js").CacheStats;
+    };
+}>;
+export declare const healthTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            detailed: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
+        };
+    };
+    handler: typeof healthCheck;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            detailed?: undefined;
+        };
+    };
+    handler: typeof getStatus;
+})[];
+//# sourceMappingURL=health.d.ts.map

package/dist/tools/health.js

@@ -0,0 +1,91 @@
+/**
+ * Health check and diagnostic tools for MCP server
+ */
+import { z } from "zod";
+import { getHealthStatus, getQuickHealthStatus, getRateLimitStatus, formatRateLimitStatus, } from "../utils/index.js";
+import { searchCache, fileCache, metadataCache } from "../utils/cache.js";
+// Schema definitions
+export const HealthCheckInputSchema = z.object({
+    detailed: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Include detailed checks (slower but more comprehensive)"),
+});
+export const GetStatusInputSchema = z.object({});
+/**
+ * Perform health check on the MCP server
+ */
+export async function healthCheck(input) {
+    if (input.detailed) {
+        const status = await getHealthStatus();
+        return {
+            ...status,
+            rateLimit: formatRateLimitStatus(),
+            cacheStats: {
+                search: searchCache.getStats(),
+                file: fileCache.getStats(),
+                metadata: metadataCache.getStats(),
+            },
+        };
+    }
+    return {
+        ...getQuickHealthStatus(),
+        rateLimit: formatRateLimitStatus(),
+    };
+}
+/**
+ * Get current server status and statistics
+ */
+export async function getStatus(_input) {
+    const rateLimitStatus = getRateLimitStatus();
+    return {
+        server: "midnight-mcp",
+        status: "running",
+        timestamp: new Date().toISOString(),
+        rateLimit: {
+            remaining: rateLimitStatus.remaining,
+            limit: rateLimitStatus.limit,
+            percentUsed: rateLimitStatus.percentUsed,
+            status: rateLimitStatus.isLimited
+                ? "limited"
+                : rateLimitStatus.isWarning
+                    ? "warning"
+                    : "ok",
+            message: rateLimitStatus.message,
+        },
+        cache: {
+            search: searchCache.getStats(),
+            file: fileCache.getStats(),
+            metadata: metadataCache.getStats(),
+        },
+    };
+}
+// Tool definitions for MCP server
+export const healthTools = [
+    {
+        name: "midnight-health-check",
+        description: "Check the health status of the Midnight MCP server. Returns server status, API connectivity, and resource availability.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                detailed: {
+                    type: "boolean",
+                    description: "Include detailed checks including GitHub API and vector store status (slower)",
+                    default: false,
+                },
+            },
+        },
+        handler: healthCheck,
+    },
+    {
+        name: "midnight-get-status",
+        description: "Get current server status including rate limits and cache statistics. Quick status check without external API calls.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+        handler: getStatus,
+    },
+];
+//# sourceMappingURL=health.js.map