midnight-mcp 0.1.28 → 0.1.30

package/README.md

@@ -10,99 +10,153 @@ MCP server that gives AI assistants access to Midnight blockchain—search contr
 
 ## Quick Start
 
-**Claude Desktop** — Add to `claude_desktop_config.json`:
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
-    "midnight": { "command": "npx", "args": ["-y", "midnight-mcp@latest"] }
+    "midnight": {
+      "command": "npx",
+      "args": ["-y", "midnight-mcp@latest"]
+    }
   }
 }
 ```
 
-> **💡 Tip:** Using `@latest` ensures you always get the newest version with all features. If tools seem missing, run `rm -rf ~/.npm/_npx` and restart Claude Desktop.
->
-> **🔄 Auto-Update Detection:** The server automatically checks for updates and prompts the AI to help you update if you're running an older version.
+**Config file locations:**
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
 
-**Cursor** — One-click install:
+### Cursor
 
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=midnight&config=eyJjb21tYW5kIjoibnB4IC15IG1pZG5pZ2h0LW1jcCJ9)
+One-click install:
 
-<details>
-<summary><strong>Other Editors (Windsurf, VS Code Copilot, Manual Setup)</strong></summary>
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=midnight&config=eyJjb21tYW5kIjoibnB4IC15IG1pZG5pZ2h0LW1jcEBsYXRlc3QifQ==)
 
-**Windsurf** — Add to `~/.codeium/windsurf/mcp_config.json`:
+Or manually add to `.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
-    "midnight": { "command": "npx", "args": ["-y", "midnight-mcp@latest"] }
+    "midnight": {
+      "command": "npx",
+      "args": ["-y", "midnight-mcp@latest"]
+    }
   }
 }
 ```
 
-**VS Code Copilot** — Add to `.vscode/mcp.json` or use Command Palette: `MCP: Add Server` → "command (stdio)" → `npx -y midnight-mcp@latest`
+### VS Code Copilot
 
-```json
-{
-  "mcpServers": {
-    "midnight": { "command": "npx", "args": ["-y", "midnight-mcp@latest"] }
-  }
-}
-```
+Add to `.vscode/mcp.json` or use Command Palette: `MCP: Add Server` → "command (stdio)" → `npx -y midnight-mcp@latest`
 
-**Cursor Manual** — Settings → MCP → Add Server, or add to `.cursor/mcp.json`:
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
 
 ```json
 {
   "mcpServers": {
-    "midnight": { "command": "npx", "args": ["-y", "midnight-mcp@latest"] }
+    "midnight": {
+      "command": "npx",
+      "args": ["-y", "midnight-mcp@latest"]
+    }
   }
 }
 ```
 
-**Config file locations (Claude Desktop):**
+**No API keys required.** Restart your editor after adding the config.
 
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-- Linux: `~/.config/Claude/claude_desktop_config.json`
+### Automatic Updates
 
-</details>
+Using `midnight-mcp@latest` ensures you always get the newest version. If you have an older config without `@latest`, update it:
 
-Restart your editor after adding the config. **No API keys required.**
+```diff
+- "args": ["-y", "midnight-mcp"]
++ "args": ["-y", "midnight-mcp@latest"]
+```
 
-> **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.
+Or clear the npx cache to force an update:
+
+```bash
+npx clear-npx-cache
+```
 
 ---
 
-## Features
+## What's Included
+
+### 25 Tools
 
-**26 Tools** — Search, analyze, validate, version tracking, AI generation, compound operations
+| Category          | Tools                                                                                                                             | Description                                      |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| **Search**        | `search-compact`, `search-typescript`, `search-docs`                                                                              | Semantic search across Midnight codebase         |
+| **Analysis**      | `analyze-contract`, `explain-circuit`, `extract-contract-structure`                                                               | Static analysis and pattern detection            |
+| **Repository**    | `get-file`, `list-examples`, `get-latest-updates`                                                                                 | Access files and examples                        |
+| **Versioning**    | `get-version-info`, `check-breaking-changes`, `get-migration-guide`, `get-file-at-version`, `compare-syntax`, `get-latest-syntax` | Version tracking and migration                   |
+| **AI Generation** | `generate-contract`, `review-contract`, `document-contract`                                                                       | AI-powered code generation _(requires sampling)_ |
+| **Compound**      | `upgrade-check`, `get-repo-context`                                                                                               | Multi-step operations _(saves 50-70% tokens)_    |
+| **Health**        | `health-check`, `get-status`, `check-version`                                                                                     | Server status and version checking               |
+| **Discovery**     | `list-tool-categories`, `list-category-tools`                                                                                     | Explore available tools                          |
 
-| Category       | Tools                                                                                                                                                                                   |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Search         | `midnight-search-compact`, `midnight-search-typescript`, `midnight-search-docs`                                                                                                         |
-| Analysis       | `midnight-analyze-contract`, `midnight-explain-circuit`                                                                                                                                 |
-| **Validation** | `midnight-validate-contract` ⭐, `midnight-extract-contract-structure`                                                                                                                  |
-| 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)_                                                                                                           |
-| Health         | `midnight-health-check`, `midnight-get-status`, `midnight-check-version` 🔄                                                                                                             |
-| Discovery      | `midnight-list-tool-categories`, `midnight-list-category-tools`                                                                                                                         |
+All tools are prefixed with `midnight-` (e.g., `midnight-search-compact`).
 
-> **⭐ Key Tool:** `midnight-validate-contract` compiles code using the **real Compact compiler** - essential for verifying contracts actually work before deployment.
->
-> **🔄 New:** `midnight-check-version` tells you if you're running the latest version with update instructions.
+### MCP Capabilities
 
-**9 Embedded Resources** — Quick references available offline: Compact syntax, SDK API, OpenZeppelin contracts, tokenomics, wallet integration, common errors
+| Capability      | Feature                                         |
+| --------------- | ----------------------------------------------- |
+| **Tools**       | 25 tools with `listChanged` notifications       |
+| **Resources**   | 9 embedded resources with subscription support  |
+| **Prompts**     | 5 workflow prompts                              |
+| **Logging**     | Client-controllable log level                   |
+| **Completions** | Autocomplete for prompt arguments               |
+| **Progress**    | Real-time progress for compound tools           |
+| **Sampling**    | AI-powered generation (when client supports it) |
 
-**5 Prompts** — `create-contract`, `review-contract`, `explain-concept`, `compare-approaches`, `debug-contract`
+### 9 Embedded Resources
 
-<details>
-<summary><strong>Advanced Configuration</strong></summary>
+Quick references available offline:
 
-### Local Mode (Optional)
+- Compact syntax guide
+- SDK API reference
+- OpenZeppelin contracts
+- Tokenomics overview
+- Wallet integration
+- Common errors & solutions
+
+### 5 Prompts
+
+- `create-contract` — Generate new contracts
+- `review-contract` — Security and code review
+- `explain-concept` — Learn Midnight concepts
+- `compare-approaches` — Compare implementation patterns
+- `debug-contract` — Troubleshoot issues
+
+---
+
+## Indexed Repositories
+
+The API indexes **39 Midnight repositories**:
+
+| Category              | Repositories                                                                                                                                                           |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Core**              | `compact`, `midnight-js`, `midnight-wallet`, `midnight-docs`, `midnight-node`, `midnight-indexer`, `midnight-ledger`, `midnight-zk`                                    |
+| **Examples**          | `example-counter`, `example-bboard`, `example-dex`, `create-mn-app`                                                                                                    |
+| **Infrastructure**    | `midnight-node-docker`, `midnight-dapp-connector-api`, `compact-tree-sitter`, `setup-compact-action`                                                                   |
+| **Partner Libraries** | `OpenZeppelin/compact-contracts`, `OpenZeppelin/midnight-apps` (LunarSwap)                                                                                             |
+| **Official Partners** | `bricktowers/midnight-seabattle`, `bricktowers/midnight-identity`, `bricktowers/midnight-rwa`, `MeshJS/midnight-starter-template`, `midnames/core`                     |
+| **Core Partner**      | `PaimaStudios/midnight-game-2`, `PaimaStudios/midnight-wasm-prover`, `PaimaStudios/midnight-batcher`, `PaimaStudios/midnight-impact-rps-example`                       |
+| **Hackathon Winners** | Sea Battle: `ErickRomeroDev/naval-battle-game_v2`, `eddex/midnight-sea-battle-hackathon` • Mini DApp: `statera-protocol`, `nel349/midnight-bank`, `Imdavyking/zkbadge` |
+
+---
+
+## Advanced Configuration
+
+### Local Mode
 
 Run everything locally for privacy or offline use:
 
@@ -124,28 +178,10 @@ Run everything locally for privacy or offline use:
 
 Requires ChromaDB (`docker run -d -p 8000:8000 chromadb/chroma`) and OpenAI API key.
 
-### GitHub Token (Optional)
+### GitHub Token
 
 Add `"GITHUB_TOKEN": "ghp_..."` for higher GitHub API rate limits (60 → 5000 requests/hour).
 
-</details>
-
----
-
-## Indexed Repositories
-
-The API indexes **39 Midnight repositories**:
-
-| Category          | Repositories                                                                                                                                                           |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Core              | `compact`, `midnight-js`, `midnight-wallet`, `midnight-docs`, `midnight-node`, `midnight-indexer`, `midnight-ledger`, `midnight-zk`                                    |
-| Examples          | `example-counter`, `example-bboard`, `example-dex`, `create-mn-app`                                                                                                    |
-| Infrastructure    | `midnight-node-docker`, `midnight-dapp-connector-api`, `compact-tree-sitter`, `setup-compact-action`                                                                   |
-| Partner Libraries | `OpenZeppelin/compact-contracts`, `OpenZeppelin/midnight-apps` (LunarSwap)                                                                                             |
-| Official Partners | `bricktowers/midnight-seabattle`, `bricktowers/midnight-identity`, `bricktowers/midnight-rwa`, `MeshJS/midnight-starter-template`, `midnames/core`                     |
-| Core Partner      | `PaimaStudios/midnight-game-2`, `PaimaStudios/midnight-wasm-prover`, `PaimaStudios/midnight-batcher`, `PaimaStudios/midnight-impact-rps-example`                       |
-| Hackathon Winners | Sea Battle: `ErickRomeroDev/naval-battle-game_v2`, `eddex/midnight-sea-battle-hackathon` • Mini DApp: `statera-protocol`, `nel349/midnight-bank`, `Imdavyking/zkbadge` |
-
 ---
 
 ## Developer Setup
@@ -155,26 +191,15 @@ git clone https://github.com/Olanetsoft/midnight-mcp.git && cd midnight-mcp
 npm install && npm run build && npm test
 ```
 
-<details>
-<summary><strong>API Backend & Local Development</strong></summary>
+The hosted API runs on Cloudflare Workers + Vectorize. See [api/README.md](./api/README.md) for backend details.
 
-The hosted API runs on Cloudflare Workers + Vectorize. See [api/README.md](./api/README.md).
-
-**Testing with Local API:**
-
-```bash
-# Terminal 1: Start local API
-cd api && npm install && npm run dev
-
-# Terminal 2: Run MCP with local API
-MIDNIGHT_API_URL=http://localhost:8787 npm start
-```
-
-</details>
+---
 
 ## Links
 
-- [Midnight Docs](https://docs.midnight.network) • [MCP Spec](https://modelcontextprotocol.io) • [Midnight GitHub](https://github.com/midnightntwrk)
+- [Midnight Docs](https://docs.midnight.network)
+- [MCP Spec](https://modelcontextprotocol.io)
+- [Midnight GitHub](https://github.com/midnightntwrk)
 
 ## License
 

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { LoggingLevel } from "@modelcontextprotocol/sdk/types.js";
 /**
  * Get update warning if outdated (to include in responses)
  */
@@ -8,8 +9,15 @@ export declare function getUpdateWarning(): string | null;
  */
 export declare function clearSubscriptions(): void;
 /**
- * Create and configure the MCP server
+ * Send a log message to the MCP client
+ * This allows clients to see server logs for debugging
  */
+export declare function sendLogToClient(level: LoggingLevel, loggerName: string, data: unknown): void;
+/**
+ * Send a progress notification to the MCP client
+ * Used for long-running operations like compound tools
+ */
+export declare function sendProgressNotification(progressToken: string | number, progress: number, total?: number, message?: string): void;
 export declare function createServer(): Server;
 /**
  * Notify subscribers when a resource changes

package/dist/server.js

@@ -1,14 +1,14 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourceTemplatesRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { logger, formatErrorResponse } from "./utils/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourceTemplatesRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, SetLevelRequestSchema, CompleteRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { logger, formatErrorResponse, setMCPLogCallback, } 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 - version should match package.json
-const CURRENT_VERSION = "0.1.27";
+const CURRENT_VERSION = "0.1.30";
 const SERVER_INFO = {
     name: "midnight-mcp",
     version: CURRENT_VERSION,
@@ -97,6 +97,67 @@ const resourceTemplates = [
 /**
  * Create and configure the MCP server
  */
+// Current MCP logging level (controlled by client)
+let mcpLogLevel = "info";
+// Server instance for sending notifications
+let serverInstance = null;
+/**
+ * Send a log message to the MCP client
+ * This allows clients to see server logs for debugging
+ */
+export function sendLogToClient(level, loggerName, data) {
+    if (!serverInstance)
+        return;
+    // Map levels to numeric values for comparison
+    const levelValues = {
+        debug: 0,
+        info: 1,
+        notice: 2,
+        warning: 3,
+        error: 4,
+        critical: 5,
+        alert: 6,
+        emergency: 7,
+    };
+    // Only send if level meets threshold
+    if (levelValues[level] < levelValues[mcpLogLevel])
+        return;
+    try {
+        serverInstance.notification({
+            method: "notifications/message",
+            params: {
+                level,
+                logger: loggerName,
+                data,
+            },
+        });
+    }
+    catch {
+        // Ignore notification errors
+    }
+}
+/**
+ * Send a progress notification to the MCP client
+ * Used for long-running operations like compound tools
+ */
+export function sendProgressNotification(progressToken, progress, total, message) {
+    if (!serverInstance)
+        return;
+    try {
+        serverInstance.notification({
+            method: "notifications/progress",
+            params: {
+                progressToken,
+                progress,
+                ...(total !== undefined && { total }),
+                ...(message && { message }),
+            },
+        });
+    }
+    catch {
+        // Ignore notification errors
+    }
+}
 export function createServer() {
     const server = new Server(SERVER_INFO, {
         capabilities: {
@@ -110,8 +171,16 @@ export function createServer() {
             prompts: {
                 listChanged: true,
             },
+            logging: {},
+            completions: {},
         },
     });
+    // Store server instance for logging notifications
+    serverInstance = server;
+    // Wire up MCP logging - send logger output to client
+    setMCPLogCallback((level, loggerName, data) => {
+        sendLogToClient(level, loggerName, data);
+    });
     // Register tool handlers
     registerToolHandlers(server);
     // Register resource handlers
@@ -120,10 +189,114 @@ export function createServer() {
     registerPromptHandlers(server);
     // Register subscription handlers
     registerSubscriptionHandlers(server);
+    // Register logging handler
+    registerLoggingHandler(server);
+    // Register completions handler
+    registerCompletionsHandler(server);
     // Setup sampling callback if available
     setupSampling(server);
     return server;
 }
+/**
+ * Register logging handler for MCP logging capability
+ */
+function registerLoggingHandler(server) {
+    server.setRequestHandler(SetLevelRequestSchema, async (request) => {
+        const { level } = request.params;
+        mcpLogLevel = level;
+        logger.info(`MCP log level set to: ${level}`);
+        sendLogToClient("info", "midnight-mcp", {
+            message: `Log level changed to ${level}`,
+        });
+        return {};
+    });
+}
+// Completion suggestions for prompt arguments
+const COMPLETION_VALUES = {
+    "midnight:create-contract": {
+        contractType: [
+            "token",
+            "voting",
+            "credential",
+            "auction",
+            "escrow",
+            "custom",
+        ],
+        privacyLevel: ["full", "partial", "public"],
+        complexity: ["beginner", "intermediate", "advanced"],
+    },
+    "midnight:review-contract": {
+        focusAreas: [
+            "security",
+            "performance",
+            "privacy",
+            "readability",
+            "gas-optimization",
+        ],
+    },
+    "midnight:explain-concept": {
+        concept: [
+            "zk-proofs",
+            "circuits",
+            "witnesses",
+            "ledger",
+            "state-management",
+            "privacy-model",
+            "token-transfers",
+            "merkle-trees",
+        ],
+        level: ["beginner", "intermediate", "advanced"],
+    },
+    "midnight:compare-approaches": {
+        approaches: [
+            "token-standards",
+            "state-management",
+            "privacy-patterns",
+            "circuit-design",
+        ],
+    },
+    "midnight:debug-contract": {
+        errorType: [
+            "compilation",
+            "runtime",
+            "logic",
+            "privacy-leak",
+            "state-corruption",
+        ],
+    },
+};
+/**
+ * Register completions handler for argument autocompletion
+ */
+function registerCompletionsHandler(server) {
+    server.setRequestHandler(CompleteRequestSchema, async (request) => {
+        const { ref, argument } = request.params;
+        if (ref.type !== "ref/prompt") {
+            return { completion: { values: [], hasMore: false } };
+        }
+        const promptName = ref.name;
+        const argName = argument.name;
+        const currentValue = argument.value?.toLowerCase() || "";
+        // Get completion values for this prompt/argument
+        const promptCompletions = COMPLETION_VALUES[promptName];
+        if (!promptCompletions) {
+            return { completion: { values: [], hasMore: false } };
+        }
+        const argValues = promptCompletions[argName];
+        if (!argValues) {
+            return { completion: { values: [], hasMore: false } };
+        }
+        // Filter by current input
+        const filtered = argValues.filter((v) => v.toLowerCase().includes(currentValue));
+        return {
+            completion: {
+                values: filtered.slice(0, 20),
+                total: filtered.length,
+                hasMore: filtered.length > 20,
+            },
+        };
+    });
+}
 /**
  * Register tool handlers
  */
@@ -177,9 +350,9 @@ function registerToolHandlers(server) {
                     "🚨 ACTION REQUIRED": {
                         message: `You are using an OUTDATED version of midnight-mcp (v${CURRENT_VERSION}). Latest is v${versionCheckResult.latestVersion}.`,
                         missingFeatures: [
-                            "midnight-validate-contract - Compile with REAL Compact compiler",
-                            "midnight-extract-contract-structure - 10 pre-compilation checks",
-                            "Pre-compilation error detection (disclose, sealed fields, etc.)",
+                            "Latest tool improvements and bug fixes",
+                            "midnight-extract-contract-structure - Static pattern analysis",
+                            "Improved error detection and contract analysis",
                         ],
                         userInstructions: {
                             step1: "Tell the user: 'Your Midnight MCP is outdated. Let me help you update it.'",
@@ -187,7 +360,7 @@ function registerToolHandlers(server) {
                             step3: "Ask them to restart Claude Desktop completely (Cmd+Q / Alt+F4)",
                             step4: "Or suggest updating config to use: midnight-mcp@latest",
                         },
-                        importance: "WITHOUT updating, contract validation will NOT work correctly. You cannot verify if contracts compile.",
+                        importance: "Update to get the latest features and improvements. Older versions may have bugs or missing functionality.",
                     },
                     result,
                 };
@@ -207,6 +380,9 @@ function registerToolHandlers(server) {
                         text: JSON.stringify(result, null, 2),
                     },
                 ],
+                // Include structured content for machine-readable responses
+                // This allows clients to parse results without JSON.parse()
+                structuredContent: result,
             };
         }
         catch (error) {

package/dist/tools/meta.js

@@ -61,14 +61,6 @@ const CATEGORY_INFO = {
             "One-shot operations",
         ],
     },
-    validation: {
-        description: "Pre-compilation contract validation using the Compact compiler",
-        useCases: [
-            "Validate contract syntax",
-            "Catch errors before deployment",
-            "Get detailed error diagnostics",
-        ],
-    },
 };
 const listCategoriesOutputSchema = {
     type: "object",
@@ -231,7 +223,7 @@ function generateCategorySuggestion(category) {
 export const metaTools = [
     {
         name: "midnight-list-tool-categories",
-        description: "📋 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 26 tools into 8 logical groups.",
+        description: "📋 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 25 tools into 7 logical groups.",
         inputSchema: {
             type: "object",
             properties: {
@@ -267,7 +259,6 @@ export const metaTools = [
                         "generation",
                         "health",
                         "compound",
-                        "validation",
                     ],
                     description: "Category to list tools for",
                 },

package/dist/tools/repository/handlers.d.ts

@@ -3,7 +3,7 @@
  * Business logic for repository-related MCP tools
  */
 import type { GetFileInput, ListExamplesInput, GetLatestUpdatesInput, GetVersionInfoInput, CheckBreakingChangesInput, GetMigrationGuideInput, GetFileAtVersionInput, CompareSyntaxInput, GetLatestSyntaxInput, UpgradeCheckInput, FullRepoContextInput } from "./schemas.js";
-export { validateContract, extractContractStructure } from "./validation.js";
+export { extractContractStructure } from "./validation.js";
 /**
  * Resolve repository name alias to owner/repo
  */
@@ -191,7 +191,11 @@ export declare function getLatestSyntax(input: GetLatestSyntaxInput): Promise<{
  * Combines: getVersionInfo + checkBreakingChanges + getMigrationGuide
  * Reduces 3 tool calls to 1, saving ~60% tokens
  */
-export declare function upgradeCheck(input: UpgradeCheckInput): Promise<{
+export declare function upgradeCheck(input: UpgradeCheckInput & {
+    _meta?: {
+        progressToken?: string | number;
+    };
+}): Promise<{
     repository: string;
     currentVersion: string;
     version: {
@@ -219,7 +223,11 @@ export declare function upgradeCheck(input: UpgradeCheckInput): Promise<{
  * Combines: getVersionInfo + getLatestSyntax + listExamples (filtered)
  * Provides everything needed to start working with a repo
  */
-export declare function getFullRepoContext(input: FullRepoContextInput): Promise<{
+export declare function getFullRepoContext(input: FullRepoContextInput & {
+    _meta?: {
+        progressToken?: string | number;
+    };
+}): Promise<{
     repository: string;
     quickStart: {
         version: string;