📋 DISCOVERY TOOL: List available tool categories for progressive exploration. Use this FIRST to understand what capabilities are available, then drill into specific categories with midnight-list-category-tools. Reduces cognitive load by organizing 28 tools into 7 logical groups.

📋 DISCOVERY TOOL: List tools within a specific category. Use after midnight-list-tool-categories to see detailed tool information for a category of interest. Supports progressive disclosure pattern.

🎯 SMART DISCOVERY: Describe what you want to do in natural language, and get tool recommendations.

EXAMPLES: • "I want to find example voting contracts" → midnight-search-compact • "Check if my version is outdated" → midnight-upgrade-check • "Analyze my contract for security issues" → midnight-analyze-contract • "I'm new to Midnight and want to get started" → midnight-get-repo-context

This tool matches your intent against known patterns and suggests the most appropriate tools with confidence levels.

USAGE GUIDANCE: • Call once with your intent - no need to call repeatedly • More specific intents get better matches • Use the primaryRecommendation for the best match

Semantic search across Compact smart contract code and patterns. Use this to find circuit definitions, witness functions, ledger declarations, and best practices for Midnight smart contracts.

USAGE GUIDANCE: • Call at most 2 times per question - if first search doesn't help, try different keywords • For comprehensive results, combine with midnight-search-docs • Use specific terms like "ledger", "circuit", "witness" for better matches

Search TypeScript SDK code, types, and API implementations. Use this to find how to use the Midnight JavaScript SDK, type definitions, and integration patterns.

USAGE GUIDANCE: • Call at most 2 times per question - refine keywords rather than repeating • For contract code, use midnight-search-compact instead • Include "type" or "interface" in query for type definitions

Full-text search across official Midnight documentation. Use this to find guides, API documentation, and conceptual explanations about Midnight blockchain and the Compact language.

USAGE GUIDANCE: • Call at most 2 times per question - use different keywords if first search fails • For code examples, combine with midnight-search-compact or midnight-search-typescript • Use category filter to narrow results (guides, api, concepts)

🌐 LIVE FETCH: Retrieve latest documentation directly from docs.midnight.network (SSG-enabled).

Unlike midnight-search-docs which uses pre-indexed content, this tool fetches LIVE documentation pages in real-time. Use when you need: • The absolute latest content (just updated docs) • A specific page you know the path to • Full page content rather than search snippets

COMMON PATHS: • /develop/faq - Frequently asked questions • /getting-started/installation - Installation guide • /getting-started/create-mn-app - Create an MN app • /compact - Compact language reference • /develop/tutorial/building - Build guide • /develop/reference/midnight-api - API documentation • /learn/what-is-midnight - What is Midnight • /blog - Dev diaries

USAGE GUIDANCE: • Use extractSection to get only a specific heading (e.g., "Developer questions") • Prefer midnight-search-docs for discovery, use this for known pages • Content is truncated at 15KB for token efficiency

⚠️ STATIC ANALYSIS ONLY - Analyze contract structure and patterns. 🚫 THIS DOES NOT COMPILE THE CONTRACT. Cannot catch: sealed field rules, disclose() requirements, semantic errors. 👉 Use 'midnight-extract-contract-structure' for pre-compilation checks.

Use this for: understanding structure, security pattern analysis, recommendations. NEVER claim a contract 'works' or 'compiles' based on this tool alone.

USAGE GUIDANCE: • Call once per contract - results are deterministic • For security review, also use midnight-review-contract (requires sampling) • Run before making changes, not repeatedly during iteration

Explain what a specific Compact circuit does in plain language, including its zero-knowledge proof implications and privacy considerations.

USAGE GUIDANCE: • Call once per circuit - explanations are deterministic • Provide complete circuit code including parameters and body • For full contract analysis, use midnight-analyze-contract first

🔧 REAL COMPILATION - Compile Compact code using the hosted compiler service.

Unlike static analysis tools, this ACTUALLY COMPILES the contract and returns real compiler errors.

Use this to: • Validate that generated code compiles before showing to users • Get actual compiler error messages with line numbers • Check if a contract is syntactically and semantically correct

Options: • skipZk=true (default): Fast syntax validation only (~1-2s) • fullCompile=true: Full compilation with ZK circuit generation (~10-30s)

FALLBACK BEHAVIOR: • If the compiler service is unavailable, automatically falls back to static analysis • Check 'validationType' in response: 'compiler' = real compilation, 'static-analysis-fallback' = fallback mode • Fallback provides structure/security analysis but may miss semantic errors

USAGE GUIDANCE: • Call after generating or modifying Compact code • Use skipZk=true for quick validation during development • Use fullCompile=true for final validation before deployment

Retrieve a specific file from Midnight repositories. Use repository aliases like 'compact', 'midnight-js', 'counter', or 'bboard' for convenience.

USAGE GUIDANCE: • Use midnight-list-examples first if you're unsure which file to get • For searching across files, use midnight-search-* tools instead • Use 'ref' parameter to get specific versions (branch, tag, or commit) • Use startLine/endLine to request specific sections of large files • Files >50KB are truncated (first 25KB + last 25KB preserved)

List available Midnight example contracts and DApps with descriptions, complexity ratings, and key features.

Retrieve recent changes and commits across Midnight repositories. Useful for staying up-to-date with the latest developments.

Get the latest version, release notes, and recent breaking changes for a Midnight repository. Use this to ensure you're working with the latest implementation.

Check if there are breaking changes between your current version and the latest release. Essential before upgrading dependencies.

Get a detailed migration guide for upgrading between versions, including all breaking changes, deprecations, and recommended steps.

Get the exact content of a file at a specific version. CRITICAL: Use this to ensure code recommendations match the user's version. Always prefer this over get-file when version accuracy matters.

Compare a file between two versions to see what changed. Use this before recommending code patterns to ensure they work with the user's version.

🚨 CALL THIS BEFORE GENERATING ANY COMPACT CODE! Get the authoritative Compact syntax reference. Prevents hallucination by providing:

• Correct syntax patterns (Compact is NOT TypeScript!)

• commonMistakes array with wrong→correct mappings

• Type casting rules (Uint→Bytes needs two casts)

• disclose() requirements for circuit params

• Map.lookup()/Set.member() ARE available in circuits

ALWAYS check this reference before writing Compact contracts.

🚀 COMPOUND TOOL: Complete upgrade analysis in ONE call. Combines version check + breaking changes + migration guide. Use this instead of calling midnight-get-version-info, midnight-check-breaking-changes, and midnight-get-migration-guide separately. Saves ~60% tokens.

🚀 COMPOUND TOOL: Get everything needed to start working with a repository in ONE call. Combines version info + syntax reference + relevant examples. Use this at the start of a coding session instead of multiple individual calls. Saves ~50% tokens.

Extract and analyze Compact contract structure (circuits, witnesses, ledger). CRITICAL CHECKS: deprecated 'ledger { }' block syntax, 'Void' return type (should be []), old pragma format, unexported enums, deprecated Cell wrapper. Also detects: module-level const, stdlib name collisions, division operator, Counter.value access, missing disclose() calls, potential overflow. Use BEFORE generating contracts to catch syntax errors. Note: Static analysis only - catches common patterns but not semantic errors.

Check the health status of the Midnight MCP server. Returns server status, API connectivity, and resource availability.

Get current server status including rate limits and cache statistics. Quick status check without external API calls.

🔄 Check if you're running the latest version of midnight-mcp. Compares your installed version against npm registry and provides update instructions if outdated. Use this if tools seem missing or you want to ensure you have the latest features.

⚠️ DEPRECATED: Auto-update is NOT possible because AI agents run in sandboxed environments without access to local filesystems. Instead, tell users to manually update their config to use midnight-mcp@latest, then run: rm -rf ~/.npm/_npx && restart their editor. This tool only returns config file paths for reference.

📋 Get detailed, platform-specific instructions for updating Midnight MCP to the latest version. Provides step-by-step guidance including config file locations, commands to run, and troubleshooting tips. Use this when a user needs help updating or is having issues with outdated versions.

🔮 AI-POWERED CONTRACT GENERATION

Generates Compact smart contracts from natural language requirements. Uses the client's LLM through MCP sampling to create contracts.

REQUIREMENTS FORMAT:

• Describe what the contract should do

• Specify state variables needed

• Define access control requirements

• List the operations/circuits needed

CONTRACT TYPES: • counter - Simple counter with increment/decrement • token - Token with transfers and balances • voting - Voting/governance mechanisms • custom - Free-form custom contract

EXAMPLE USAGE: "Create a token contract with private balances, mint/burn capabilities for admin, and transfer functionality between users"

⚠️ REQUIRES: Client with sampling capability (e.g., Claude Desktop)

🔍 AI-POWERED CONTRACT REVIEW

Performs security review and analysis of Compact smart contracts. Uses the client's LLM to identify issues and suggest improvements.

CHECKS PERFORMED: • Security vulnerabilities • Privacy concerns (shielded state handling) • Logic errors • Best practice violations • Performance issues

OUTPUT INCLUDES: • Summary of contract quality • List of issues with severity levels • Suggested fixes for each issue • Improved code version if applicable

⚠️ REQUIRES: Client with sampling capability (e.g., Claude Desktop)

📝 AI-POWERED DOCUMENTATION GENERATION

Generates comprehensive documentation for Compact smart contracts. Uses the client's LLM to create detailed, human-readable docs.

FORMATS: • markdown - Full Markdown documentation with examples • jsdoc - JSDoc-style inline comments

MARKDOWN INCLUDES: • Contract overview and purpose • State variables with privacy annotations • Circuit function documentation • Witness function documentation • Usage examples • Security considerations

⚠️ REQUIRES: Client with sampling capability (e.g., Claude Desktop)