midnight-mcp 0.0.4 → 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
+## How It Works
 
-ChromaDB is a local vector database—no account needed, just Docker:
+By default, the MCP uses a **hosted API** for semantic search:
 
-```bash
-docker run -d -p 8000:8000 chromadb/chroma
-```
+- ✅ **Zero configuration** — just install and use
+- ✅ **Semantic search** works immediately
+- ✅ **No API keys** needed
 
-### 2. Get an OpenAI API key
+### Local Mode (Optional)
 
-Needed for generating embeddings. Get one at [platform.openai.com/api-keys](https://platform.openai.com/api-keys).
-
-### 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,15 +49,17 @@ 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.
+
+### GitHub Token (Optional)
 
-Add `"GITHUB_TOKEN": "ghp_..."` to increase API rate limits from 60 to 5000 requests/hour.
+Add `"GITHUB_TOKEN": "ghp_..."` for higher GitHub API rate limits (60 → 5000 requests/hour).
 
 ---
 
-## What's Included
+## Features
 
-### Tools (14 total)
+### Tools (16)
 
 | Tool                              | Description                             |
 | --------------------------------- | --------------------------------------- |
@@ -82,10 +77,12 @@ Add `"GITHUB_TOKEN": "ghp_..."` to increase API rate limits from 60 to 5000 requ
 | `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 total)
+### Resources (20)
 
-- `midnight://docs/*` — Documentation (Compact reference, SDK API, ZK concepts, OpenZeppelin patterns)
+- `midnight://docs/*` — Documentation (Compact reference, SDK API, ZK concepts)
 - `midnight://code/*` — Examples, patterns, and templates
 - `midnight://schema/*` — AST, transaction, and proof schemas
 
@@ -94,27 +91,14 @@ Add `"GITHUB_TOKEN": "ghp_..."` to increase API rate limits from 60 to 5000 requ
 - `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
 
 ---
 
-## How Environment Variables Work
-
-The npm package contains no secrets. **You provide your own credentials** via the `env` block in your config:
-
-| Variable         | Required | Without It                             | With It              |
-| ---------------- | -------- | -------------------------------------- | -------------------- |
-| `GITHUB_TOKEN`   | No       | 60 API calls/hour, may hit rate limits | 5,000 calls/hour     |
-| `OPENAI_API_KEY` | No       | Keyword search only (no embeddings)    | Semantic search      |
-| `CHROMA_URL`     | No       | In-memory search, no persistence       | Persistent vector DB |
-
-Your tokens stay on your machine and are only used to access services on your behalf.
-
----
-
 ## 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
@@ -124,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/tools/search.d.ts

@@ -50,11 +50,11 @@ export declare const SearchDocsInputSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     query: string;
     limit: number;
-    category: "guides" | "api" | "concepts" | "all";
+    category: "all" | "guides" | "api" | "concepts";
 }, {
     query: string;
     limit?: number | undefined;
-    category?: "guides" | "api" | "concepts" | "all" | undefined;
+    category?: "all" | "guides" | "api" | "concepts" | undefined;
 }>;
 export type SearchCompactInput = z.infer<typeof SearchCompactInputSchema>;
 export type SearchTypeScriptInput = z.infer<typeof SearchTypeScriptInputSchema>;

package/dist/tools/search.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { vectorStore } from "../db/index.js";
-import { logger, validateQuery, validateNumber, searchCache, createCacheKey, } from "../utils/index.js";
+import { logger, validateQuery, validateNumber, searchCache, createCacheKey, isHostedMode, searchCompactHosted, searchTypeScriptHosted, searchDocsHosted, } from "../utils/index.js";
 // Schema definitions for tool inputs
 export const SearchCompactInputSchema = z.object({
     query: z.string().describe("Natural language search query for Compact code"),
@@ -62,7 +62,7 @@ export async function searchCompact(input) {
     const limit = limitValidation.value;
     logger.debug("Searching Compact code", {
         query: sanitizedQuery,
-        originalQuery: input.query,
+        mode: isHostedMode() ? "hosted" : "local",
     });
     // Check cache first
     const cacheKey = createCacheKey("compact", sanitizedQuery, limit, input.filter?.repository);
@@ -71,6 +71,26 @@ export async function searchCompact(input) {
         logger.debug("Search cache hit", { cacheKey });
         return cached;
     }
+    // Use hosted API if in hosted mode
+    if (isHostedMode()) {
+        try {
+            const response = await searchCompactHosted(sanitizedQuery, limit);
+            searchCache.set(cacheKey, response);
+            return {
+                ...response,
+                ...(queryValidation.warnings.length > 0 && {
+                    warnings: queryValidation.warnings,
+                }),
+            };
+        }
+        catch (error) {
+            logger.warn("Hosted API search failed, falling back to local", {
+                error: String(error),
+            });
+            // Fall through to local search
+        }
+    }
+    // Local search (fallback or when in local mode)
     const filter = {
         language: "compact",
         ...input.filter,
@@ -118,7 +138,10 @@ export async function searchTypeScript(input) {
     });
     const sanitizedQuery = queryValidation.sanitized;
     const limit = limitValidation.value;
-    logger.debug("Searching TypeScript code", { query: sanitizedQuery });
+    logger.debug("Searching TypeScript code", {
+        query: sanitizedQuery,
+        mode: isHostedMode() ? "hosted" : "local",
+    });
     // Check cache
     const cacheKey = createCacheKey("typescript", sanitizedQuery, limit, input.includeTypes, input.includeExamples);
     const cached = searchCache.get(cacheKey);
@@ -126,6 +149,26 @@ export async function searchTypeScript(input) {
         logger.debug("Search cache hit", { cacheKey });
         return cached;
     }
+    // Use hosted API if in hosted mode
+    if (isHostedMode()) {
+        try {
+            const response = await searchTypeScriptHosted(sanitizedQuery, limit, input.includeTypes);
+            searchCache.set(cacheKey, response);
+            return {
+                ...response,
+                ...(queryValidation.warnings.length > 0 && {
+                    warnings: queryValidation.warnings,
+                }),
+            };
+        }
+        catch (error) {
+            logger.warn("Hosted API search failed, falling back to local", {
+                error: String(error),
+            });
+            // Fall through to local search
+        }
+    }
+    // Local search (fallback or when in local mode)
     const filter = {
         language: "typescript",
     };
@@ -177,7 +220,10 @@ export async function searchDocs(input) {
     });
     const sanitizedQuery = queryValidation.sanitized;
     const limit = limitValidation.value;
-    logger.debug("Searching documentation", { query: sanitizedQuery });
+    logger.debug("Searching documentation", {
+        query: sanitizedQuery,
+        mode: isHostedMode() ? "hosted" : "local",
+    });
     // Check cache
     const cacheKey = createCacheKey("docs", sanitizedQuery, limit, input.category);
     const cached = searchCache.get(cacheKey);
@@ -185,6 +231,26 @@ export async function searchDocs(input) {
         logger.debug("Search cache hit", { cacheKey });
         return cached;
     }
+    // Use hosted API if in hosted mode
+    if (isHostedMode()) {
+        try {
+            const response = await searchDocsHosted(sanitizedQuery, limit, input.category);
+            searchCache.set(cacheKey, response);
+            return {
+                ...response,
+                ...(queryValidation.warnings.length > 0 && {
+                    warnings: queryValidation.warnings,
+                }),
+            };
+        }
+        catch (error) {
+            logger.warn("Hosted API search failed, falling back to local", {
+                error: String(error),
+            });
+            // Fall through to local search
+        }
+    }
+    // Local search (fallback or when in local mode)
     const filter = {
         language: "markdown",
     };

package/dist/utils/config.d.ts

@@ -1,10 +1,9 @@
 import { z } from "zod";
 declare const ConfigSchema: z.ZodObject<{
+    mode: z.ZodDefault<z.ZodEnum<["hosted", "local"]>>;
+    hostedApiUrl: z.ZodDefault<z.ZodString>;
     githubToken: z.ZodOptional<z.ZodString>;
     chromaUrl: z.ZodDefault<z.ZodString>;
-    qdrantUrl: z.ZodOptional<z.ZodString>;
-    pineconeApiKey: z.ZodOptional<z.ZodString>;
-    pineconeIndex: z.ZodOptional<z.ZodString>;
     openaiApiKey: z.ZodOptional<z.ZodString>;
     embeddingModel: z.ZodDefault<z.ZodString>;
     logLevel: z.ZodDefault<z.ZodEnum<["debug", "info", "warn", "error"]>>;
@@ -13,6 +12,8 @@ declare const ConfigSchema: z.ZodObject<{
     dataDir: z.ZodDefault<z.ZodString>;
     cacheDir: z.ZodDefault<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    mode: "hosted" | "local";
+    hostedApiUrl: string;
     chromaUrl: string;
     embeddingModel: string;
     logLevel: "debug" | "info" | "warn" | "error";
@@ -21,16 +22,12 @@ declare const ConfigSchema: z.ZodObject<{
     dataDir: string;
     cacheDir: string;
     githubToken?: string | undefined;
-    qdrantUrl?: string | undefined;
-    pineconeApiKey?: string | undefined;
-    pineconeIndex?: string | undefined;
     openaiApiKey?: string | undefined;
 }, {
+    mode?: "hosted" | "local" | undefined;
+    hostedApiUrl?: string | undefined;
     githubToken?: string | undefined;
     chromaUrl?: string | undefined;
-    qdrantUrl?: string | undefined;
-    pineconeApiKey?: string | undefined;
-    pineconeIndex?: string | undefined;
     openaiApiKey?: string | undefined;
     embeddingModel?: string | undefined;
     logLevel?: "debug" | "info" | "warn" | "error" | undefined;
@@ -41,6 +38,8 @@ declare const ConfigSchema: z.ZodObject<{
 }>;
 export type Config = z.infer<typeof ConfigSchema>;
 export declare const config: {
+    mode: "hosted" | "local";
+    hostedApiUrl: string;
     chromaUrl: string;
     embeddingModel: string;
     logLevel: "debug" | "info" | "warn" | "error";
@@ -49,11 +48,16 @@ export declare const config: {
     dataDir: string;
     cacheDir: string;
     githubToken?: string | undefined;
-    qdrantUrl?: string | undefined;
-    pineconeApiKey?: string | undefined;
-    pineconeIndex?: string | undefined;
     openaiApiKey?: string | undefined;
 };
+/**
+ * Check if running in hosted mode (default)
+ */
+export declare function isHostedMode(): boolean;
+/**
+ * Check if running in local mode
+ */
+export declare function isLocalMode(): boolean;
 export interface RepositoryConfig {
     owner: string;
     repo: string;

package/dist/utils/config.js

@@ -2,14 +2,17 @@ import { z } from "zod";
 import dotenv from "dotenv";
 dotenv.config();
 const ConfigSchema = z.object({
+    // Mode: 'hosted' (default) or 'local'
+    mode: z.enum(["hosted", "local"]).default("hosted"),
+    // Hosted API URL (used when mode is 'hosted')
+    hostedApiUrl: z
+        .string()
+        .default("https://midnight-mcp-api.midnightmcp.workers.dev"),
     // GitHub
     githubToken: z.string().optional(),
-    // Vector Database
+    // Vector Database (only needed for local mode)
     chromaUrl: z.string().default("http://localhost:8000"),
-    qdrantUrl: z.string().optional(),
-    pineconeApiKey: z.string().optional(),
-    pineconeIndex: z.string().optional(),
-    // Embeddings
+    // Embeddings (only needed for local mode)
     openaiApiKey: z.string().optional(),
     embeddingModel: z.string().default("text-embedding-3-small"),
     // Server
@@ -21,12 +24,14 @@ const ConfigSchema = z.object({
     cacheDir: z.string().default("./cache"),
 });
 function loadConfig() {
+    // Determine mode: local if MIDNIGHT_LOCAL=true or if OPENAI_API_KEY is set
+    const isLocalMode = process.env.MIDNIGHT_LOCAL === "true" ||
+        (process.env.OPENAI_API_KEY && process.env.CHROMA_URL);
     const rawConfig = {
+        mode: isLocalMode ? "local" : "hosted",
+        hostedApiUrl: process.env.MIDNIGHT_API_URL,
         githubToken: process.env.GITHUB_TOKEN,
         chromaUrl: process.env.CHROMA_URL,
-        qdrantUrl: process.env.QDRANT_URL,
-        pineconeApiKey: process.env.PINECONE_API_KEY,
-        pineconeIndex: process.env.PINECONE_INDEX,
         openaiApiKey: process.env.OPENAI_API_KEY,
         embeddingModel: process.env.EMBEDDING_MODEL,
         logLevel: process.env.LOG_LEVEL,
@@ -42,6 +47,18 @@ function loadConfig() {
     return ConfigSchema.parse(cleanConfig);
 }
 export const config = loadConfig();
+/**
+ * Check if running in hosted mode (default)
+ */
+export function isHostedMode() {
+    return config.mode === "hosted";
+}
+/**
+ * Check if running in local mode
+ */
+export function isLocalMode() {
+    return config.mode === "local";
+}
 export const DEFAULT_REPOSITORIES = [
     // Core Language & SDK
     {

package/dist/utils/hosted-api.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Client for the hosted Midnight MCP API
+ * Used when running in hosted mode (default)
+ */
+export interface HostedSearchResult {
+    code?: string;
+    content?: string;
+    relevanceScore: number;
+    source: {
+        repository: string;
+        filePath: string;
+        lines?: string;
+        section?: string;
+    };
+    codeType?: string;
+    name?: string;
+    isExported?: boolean;
+}
+export interface HostedSearchResponse {
+    results: HostedSearchResult[];
+    totalResults: number;
+    query: string;
+    category?: string;
+    warnings?: string[];
+}
+export interface HostedSearchFilter {
+    language?: string;
+    repository?: string;
+}
+/**
+ * Search Compact code via hosted API
+ */
+export declare function searchCompactHosted(query: string, limit?: number): Promise<HostedSearchResponse>;
+/**
+ * Search TypeScript code via hosted API
+ */
+export declare function searchTypeScriptHosted(query: string, limit?: number, includeTypes?: boolean): Promise<HostedSearchResponse>;
+/**
+ * Search documentation via hosted API
+ */
+export declare function searchDocsHosted(query: string, limit?: number, category?: string): Promise<HostedSearchResponse>;
+/**
+ * Generic search via hosted API
+ */
+export declare function searchHosted(query: string, limit?: number, filter?: HostedSearchFilter): Promise<HostedSearchResponse>;
+/**
+ * Check if the hosted API is available
+ */
+export declare function checkHostedApiHealth(): Promise<{
+    available: boolean;
+    documentsIndexed?: number;
+    error?: string;
+}>;
+/**
+ * Get hosted API stats
+ */
+export declare function getHostedApiStats(): Promise<{
+    documentsIndexed: number;
+    repositories: number;
+}>;
+//# sourceMappingURL=hosted-api.d.ts.map

package/dist/utils/hosted-api.js

@@ -0,0 +1,106 @@
+/**
+ * Client for the hosted Midnight MCP API
+ * Used when running in hosted mode (default)
+ */
+import { config, logger } from "./index.js";
+const API_TIMEOUT = 10000; // 10 seconds
+/**
+ * Make a request to the hosted API
+ */
+async function apiRequest(endpoint, options = {}) {
+    const url = `${config.hostedApiUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), API_TIMEOUT);
+    try {
+        const response = await fetch(url, {
+            ...options,
+            signal: controller.signal,
+            headers: {
+                "Content-Type": "application/json",
+                "User-Agent": "midnight-mcp",
+                ...options.headers,
+            },
+        });
+        if (!response.ok) {
+            const errorData = (await response
+                .json()
+                .catch(() => ({ error: "Unknown error" })));
+            throw new Error(errorData.error || `API error: ${response.status}`);
+        }
+        return (await response.json());
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error("API request timed out. The hosted service may be unavailable.");
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Search Compact code via hosted API
+ */
+export async function searchCompactHosted(query, limit = 10) {
+    logger.debug("Searching Compact code via hosted API", { query });
+    return apiRequest("/v1/search/compact", {
+        method: "POST",
+        body: JSON.stringify({ query, limit }),
+    });
+}
+/**
+ * Search TypeScript code via hosted API
+ */
+export async function searchTypeScriptHosted(query, limit = 10, includeTypes = true) {
+    logger.debug("Searching TypeScript code via hosted API", { query });
+    return apiRequest("/v1/search/typescript", {
+        method: "POST",
+        body: JSON.stringify({ query, limit, includeTypes }),
+    });
+}
+/**
+ * Search documentation via hosted API
+ */
+export async function searchDocsHosted(query, limit = 10, category = "all") {
+    logger.debug("Searching documentation via hosted API", { query });
+    return apiRequest("/v1/search/docs", {
+        method: "POST",
+        body: JSON.stringify({ query, limit, category }),
+    });
+}
+/**
+ * Generic search via hosted API
+ */
+export async function searchHosted(query, limit = 10, filter) {
+    logger.debug("Searching via hosted API", { query, filter });
+    return apiRequest("/v1/search", {
+        method: "POST",
+        body: JSON.stringify({ query, limit, filter }),
+    });
+}
+/**
+ * Check if the hosted API is available
+ */
+export async function checkHostedApiHealth() {
+    try {
+        const response = await apiRequest("/health");
+        return {
+            available: response.status === "healthy",
+            documentsIndexed: response.vectorStore?.documentsIndexed,
+        };
+    }
+    catch (error) {
+        return {
+            available: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Get hosted API stats
+ */
+export async function getHostedApiStats() {
+    return apiRequest("/v1/stats");
+}
+//# sourceMappingURL=hosted-api.js.map

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-export { config } from "./config.js";
+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";
@@ -11,4 +11,6 @@ export { updateRateLimitFromHeaders, updateRateLimit, getRateLimitStatus, should
 export type { RateLimitInfo, RateLimitStatus } from "./rate-limit.js";
 export { Cache, createCacheKey, searchCache, fileCache, metadataCache, pruneAllCaches, } from "./cache.js";
 export type { CacheOptions, CacheEntry, CacheStats } from "./cache.js";
+export { searchCompactHosted, searchTypeScriptHosted, searchDocsHosted, searchHosted, checkHostedApiHealth, getHostedApiStats, } from "./hosted-api.js";
+export type { HostedSearchResult, HostedSearchResponse, HostedSearchFilter, } from "./hosted-api.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -1,4 +1,4 @@
-export { config } from "./config.js";
+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";
@@ -10,4 +10,6 @@ export { getHealthStatus, getQuickHealthStatus } from "./health.js";
 export { updateRateLimitFromHeaders, updateRateLimit, getRateLimitStatus, shouldProceedWithRequest, getTimeUntilReset, formatRateLimitStatus, decrementRemaining, } from "./rate-limit.js";
 // Caching utilities
 export { Cache, createCacheKey, searchCache, fileCache, metadataCache, pruneAllCaches, } from "./cache.js";
+// Hosted API client
+export { searchCompactHosted, searchTypeScriptHosted, searchDocsHosted, searchHosted, checkHostedApiHealth, getHostedApiStats, } from "./hosted-api.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "midnight-mcp",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Model Context Protocol Server for Midnight Blockchain Development",
   "type": "module",
   "main": "dist/index.js",
@@ -11,7 +11,6 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsx watch src/index.ts",
-    "index": "tsx src/scripts/index-repos.ts",
     "test": "vitest",
     "test:coverage": "vitest --coverage",
     "lint": "eslint src/**/*.ts",