midnight-mcp 0.1.8 → 0.1.10

package/README.md

@@ -10,113 +10,89 @@ MCP server that gives AI assistants access to Midnight blockchain—search contr
 
 ## Quick Start
 
-### Claude Desktop
-
-Add to your `claude_desktop_config.json`:
+**Claude Desktop** — Add to `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
-    "midnight": {
-      "command": "npx",
-      "args": ["-y", "midnight-mcp"]
-    }
+    "midnight": { "command": "npx", "args": ["-y", "midnight-mcp"] }
   }
 }
 ```
 
-<details>
-<summary><strong>Config file locations</strong></summary>
-
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-- **Linux**: `~/.config/Claude/claude_desktop_config.json`
-
-</details>
-
-### Cursor
-
-**Click the button to auto install the MCP for Cursor**
+**Cursor** — One-click install:
 
 [![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:**
+<details>
+<summary><strong>Other Editors (Windsurf, VS Code Copilot, Manual Setup)</strong></summary>
 
-Add to Cursor's MCP settings (Settings → MCP → Add Server):
+**Windsurf** — Add to `~/.codeium/windsurf/mcp_config.json`:
 
 ```json
 {
   "mcpServers": {
-    "midnight": {
-      "command": "npx",
-      "args": ["-y", "midnight-mcp"]
-    }
+    "midnight": { "command": "npx", "args": ["-y", "midnight-mcp"] }
   }
 }
 ```
 
-Or add to `.cursor/mcp.json` in your project:
+**VS Code Copilot** — Add to `.vscode/mcp.json` or use Command Palette: `MCP: Add Server` → "command (stdio)" → `npx -y midnight-mcp`
 
 ```json
 {
   "mcpServers": {
-    "midnight": {
-      "command": "npx",
-      "args": ["-y", "midnight-mcp"]
-    }
+    "midnight": { "command": "npx", "args": ["-y", "midnight-mcp"] }
   }
 }
 ```
 
-### Windsurf
-
-Add to `~/.codeium/windsurf/mcp_config.json`:
+**Cursor Manual** — Settings → MCP → Add Server, or add to `.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
-    "midnight": {
-      "command": "npx",
-      "args": ["-y", "midnight-mcp"]
-    }
+    "midnight": { "command": "npx", "args": ["-y", "midnight-mcp"] }
   }
 }
 ```
 
-### VS Code Copilot
+**Config file locations (Claude Desktop):**
 
-Add to your VS Code settings (`.vscode/mcp.json` in your workspace or user settings):
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
 
-```json
-{
-  "mcpServers": {
-    "midnight": {
-      "command": "npx",
-      "args": ["-y", "midnight-mcp"]
-    }
-  }
-}
-```
+</details>
 
-Or via Command Palette: `MCP: Add Server` → select "command (stdio)" → enter `npx -y midnight-mcp`
+Restart your editor after adding the config. **No API keys required.**
+
+> **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.
 
 ---
 
-Restart your editor after adding the config. All features work out of the box—no API keys or setup required.
+## Features
 
----
+**23 Tools** — Search, analyze, version tracking, AI generation, compound operations
 
-## How It Works
+| Category      | Tools                                                                                                                                                                                   |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Search        | `midnight-search-compact`, `midnight-search-typescript`, `midnight-search-docs`                                                                                                         |
+| 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` _(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`                                                                         |
 
-By default, the MCP uses a **hosted API** for semantic search:
+> **Tip:** Use compound tools (`midnight-upgrade-check`, `midnight-get-repo-context`) for efficient multi-step operations in a single call.
 
-- **Zero configuration** — just install and use
-- **Semantic search** works immediately
-- **No API keys** needed
+**9 Embedded Resources** — Quick references available offline: Compact syntax, SDK API, OpenZeppelin contracts, tokenomics, wallet integration, common errors
 
-> **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.
+**5 Prompts** — `create-contract`, `review-contract`, `explain-concept`, `compare-approaches`, `debug-contract`
+
+<details>
+<summary><strong>Advanced Configuration</strong></summary>
 
 ### Local Mode (Optional)
 
@@ -138,171 +114,58 @@ Run everything locally for privacy or offline use:
 }
 ```
 
-Local mode requires ChromaDB (`docker run -d -p 8000:8000 chromadb/chroma`) and an OpenAI API key.
+Requires ChromaDB (`docker run -d -p 8000:8000 chromadb/chroma`) and OpenAI API key.
 
 ### GitHub Token (Optional)
 
 Add `"GITHUB_TOKEN": "ghp_..."` for higher GitHub API rate limits (60 → 5000 requests/hour).
 
+</details>
+
 ---
 
-## Features
+## Indexed Repositories
+
+The API indexes **22+ Midnight repositories**:
 
-### 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) |
-
-### Embedded Resources (9)
-
-Curated documentation that's always available without network calls:
-
-| URI                                     | Description                             |
-| --------------------------------------- | --------------------------------------- |
-| `midnight://docs/compact-reference`     | Compact syntax quick reference          |
-| `midnight://docs/sdk-api`               | TypeScript SDK API reference            |
-| `midnight://docs/openzeppelin`          | OpenZeppelin Compact contracts overview |
-| `midnight://docs/openzeppelin/token`    | FungibleToken standard                  |
-| `midnight://docs/openzeppelin/access`   | Access control patterns                 |
-| `midnight://docs/openzeppelin/security` | Security patterns (Pausable)            |
-| `midnight://docs/tokenomics`            | NIGHT/DUST tokenomics summary           |
-| `midnight://docs/wallet-integration`    | DApp Connector API guide                |
-| `midnight://docs/common-errors`         | Common errors & troubleshooting         |
-
-> **Note:** For comprehensive docs (glossary, Zswap, Kachina, etc.), use the `midnight-search-docs` tool which queries the full indexed documentation.
-
-### Prompts (5)
-
-- `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
+| Category          | Repositories                                                                                                                                       |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Core              | `compact`, `midnight-js`, `midnight-wallet`, `midnight-docs`                                                                                       |
+| Examples          | `example-counter`, `example-bboard`, `example-dex`, `create-mn-app`                                                                                |
+| Infrastructure    | `midnight-indexer`, `midnight-node-docker`, `midnight-dapp-connector-api`                                                                          |
+| Partner Libraries | `OpenZeppelin/compact-contracts`, `OpenZeppelin/midnight-apps`                                                                                     |
+| Official Partners | `bricktowers/midnight-seabattle`, `bricktowers/midnight-identity`, `bricktowers/midnight-rwa`, `MeshJS/midnight-starter-template`, `midnames/core` |
 
 ---
 
 ## Developer Setup
 
-For contributors:
-
 ```bash
-git clone https://github.com/Olanetsoft/midnight-mcp.git
-cd midnight-mcp
-npm install
-npm run build
-npm test
+git clone https://github.com/Olanetsoft/midnight-mcp.git && cd midnight-mcp
+npm install && npm run build && npm test
 ```
 
-### Testing with Local API
+<details>
+<summary><strong>API Backend & Local Development</strong></summary>
+
+The hosted API runs on Cloudflare Workers + Vectorize. See [api/README.md](./api/README.md).
 
-To test against a local API server instead of production:
+**Testing with Local API:**
 
 ```bash
 # Terminal 1: Start local API
-cd api
-npm install
-npm run dev  # Starts at http://localhost:8787
+cd api && npm install && npm run dev
 
 # Terminal 2: Run MCP with local API
 MIDNIGHT_API_URL=http://localhost:8787 npm start
 ```
 
-### API Backend
-
-The hosted API runs on Cloudflare Workers + Vectorize. See [api/README.md](./api/README.md) for deployment and development instructions.
-
-### Search Quality
-
-The API indexes **16 Midnight repositories** including core infrastructure, SDK, examples, and developer tools:
-
-| Repository                       | Description                                    |
-| -------------------------------- | ---------------------------------------------- |
-| `compact`                        | Compact language compiler and standard library |
-| `midnight-js`                    | TypeScript SDK                                 |
-| `midnight-docs`                  | Official documentation                         |
-| `example-counter`                | Simple counter DApp example                    |
-| `example-bboard`                 | Bulletin board DApp example                    |
-| `example-dex`                    | DEX DApp example                               |
-| `create-mn-app`                  | Project scaffolding CLI                        |
-| `midnight-wallet`                | Wallet implementation                          |
-| `midnight-indexer`               | Blockchain indexer                             |
-| `midnight-node-docker`           | Node Docker setup                              |
-| `midnight-dapp-connector-api`    | Wallet connector API                           |
-| `compact-tree-sitter`            | Syntax highlighting support                    |
-| `setup-compact-action`           | GitHub Action for CI/CD                        |
-| `midnight-awesome-dapps`         | Curated DApp list                              |
-| `contributor-hub`                | Contributor resources                          |
-| `OpenZeppelin/compact-contracts` | OpenZeppelin Compact library                   |
-
-Search quality techniques:
+</details>
 
-- **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)
-- **Incremental indexing** — Daily updates via tarball download + batch embeddings (~5 min)
+## Links
 
-View live metrics at the [Dashboard](https://midnight-mcp-api.midnightmcp.workers.dev/dashboard).
+- [Midnight Docs](https://docs.midnight.network) • [MCP Spec](https://modelcontextprotocol.io) • [Midnight GitHub](https://github.com/midnightntwrk)
 
 ## License
 
 MIT
-
-## Changelog
-
-### v0.1.7
-
-- Added `setup-compact-action` repository to indexed sources
-- New aliases: `setup-compact`, `compact-action`, `tree-sitter`
-
-### v0.1.6
-
-- Fixed bug where tools crashed with "Cannot read properties of undefined" when repo param was omitted
-
-### v0.1.5
-
-- Added `common-errors` embedded resource with verified troubleshooting guide
-- Added comprehensive search tool tests
-- Refactored to follow MCP best practices (tools over embedded knowledge)
-
-### v0.1.4
-
-- Initial stable release with 19 tools, 9 embedded resources, 5 prompts
-- Hosted API with zero-config semantic search
-- Support for Claude Desktop, Cursor, and Windsurf
-
-## Links
-
-- [Midnight Docs](https://docs.midnight.network)
-- [MCP Spec](https://modelcontextprotocol.io)
-- [Midnight GitHub](https://github.com/midnightntwrk)

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