regen-koi-mcp 1.0.5 → 1.1.0

package/README.md

@@ -12,6 +12,8 @@ curl -fsSL https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/inst
 
 This automatically configures Claude Desktop and Claude Code CLI. Just restart and you're done! 🎉
 
+**Quick Test:** After restarting, open Claude and ask: _"What repositories are indexed in KOI?"_ to verify the tools are working.
+
 ---
 
 ### Option 1: NPM (Recommended - Auto-Updates)
@@ -45,6 +47,8 @@ Config file locations:
 
 Then restart Claude Desktop and you're done! 🎉
 
+**Quick Test:** Ask Claude: _"What repositories are indexed in KOI?"_ to verify the tools are working.
+
 **For existing git users**: See the migration section below for a simple one-line script to switch to npx.
 
 ---
@@ -112,6 +116,66 @@ This MCP server gives AI assistants access to Regen Network's comprehensive know
 
 **Note:** This MCP server connects to our hosted KOI API at `https://regen.gaiaai.xyz/api/koi` (behind HTTPS via Nginx), so you don't need to run any infrastructure locally.
 
+## 🎓 Quick Start: Example Queries
+
+Once you've installed the MCP server, try these queries in Claude to explore what's available:
+
+### 🔍 Discovery: What's Indexed?
+
+```
+"What repositories are indexed in the KOI knowledge base?"
+"What types of code entities exist?"
+"Show me statistics about what's in the knowledge base"
+```
+
+**What you'll get:** The system has indexed 5 repositories (regen-ledger, regen-web, koi-sensors, and more) with 26,768 code entities including Methods, Functions, Structs, and Interfaces.
+
+### 💻 Code Exploration: Find Specific Code
+
+```
+"Search for functions containing 'keeper' in regen-ledger"
+"Find all code related to MsgCreateBatch"
+"What Structs exist in the ecocredit module?"
+"Show me all Interface types in regen-ledger"
+"Search for retirement-related code"
+```
+
+**What you'll get:** Direct links to code entities with file paths and signatures. The graph contains Methods, Functions, Structs, and Interfaces extracted via tree-sitter AST parsing.
+
+### 📚 Documentation: Understanding the System
+
+```
+"Explain the ecocredit module architecture"
+"What's the tech stack for regen-web?"
+"Search GitHub docs for information about credit classes"
+"Get an overview of the regen-ledger repository"
+```
+
+**What you'll get:** Architectural explanations, technology choices, and relevant documentation from GitHub repositories.
+
+### 🔬 Advanced: Graph Traversal
+
+```
+"What functions call CreateBatch?"
+"What does the NewKeeper function call?"
+"Find orphaned code that's never called"
+"Show me the call graph for MsgRetire"
+```
+
+**What you'll get:** Call graph traversal showing function relationships (CALLS edges), orphan detection, and code dependency analysis.
+
+### 📊 Knowledge Base: Recent Activity
+
+```
+"Generate a weekly digest of Regen Network discussions"
+"Search for recent discussions about carbon credits from the past week"
+"Find documentation about basket creation from 2024"
+```
+
+**What you'll get:** Summaries of community discussions, forum posts, and activity with source citations.
+
+---
+
 ## 📦 Available Tools
 
 ### Knowledge Base Search
@@ -134,6 +198,87 @@ This MCP server gives AI assistants access to Regen Network's comprehensive know
 | `get_repo_overview` | Get structured overview of a Regen repository | `repository` (enum: regen-ledger, regen-web, regen-data-standards, regenie-corpus) |
 | `get_tech_stack` | Get technical stack information for Regen repositories | `repository` (optional, omit to show all repos) |
 
+---
+
+## 🤔 What Can I Ask? User Guide
+
+This table helps you understand which tool to use for different tasks. Just ask Claude in natural language - it will automatically use the right tool.
+
+| **When You Want To...**                                  | **Ask Claude**                                           | **Tool Used**            |
+|----------------------------------------------------------|----------------------------------------------------------|--------------------------|
+| **Discover what's indexed**                              |                                                          |                          |
+| See what repositories are available                      | "What repositories are indexed?"                         | `list_repos`             |
+| See what types of code entities exist                    | "What entity types are available?"                       | `list_entity_types`      |
+| Get comprehensive statistics                             | "Show me statistics about the knowledge base"            | `get_entity_stats`       |
+| **Find specific code**                                   |                                                          |                          |
+| Find all entities of a type                              | "Show me all Keepers in regen-ledger"                    | `find_by_type`           |
+| Search for entities by name                              | "Find entities related to MsgCreateBatch"                | `search_entities`        |
+| Find related code entities                               | "What's related to the ecocredit Keeper?"                | `related_entities`       |
+| **Understand relationships**                             |                                                          |                          |
+| Find which Keeper handles a Message                      | "Which Keeper handles MsgCreateBatch?"                   | `keeper_for_msg`         |
+| Find what Messages a Keeper handles                      | "What messages does the ecocredit Keeper handle?"        | `msgs_for_keeper`        |
+| Find what documentation mentions an entity               | "What docs mention MsgRetire?"                           | `docs_mentioning`        |
+| Find entities in a file                                  | "What entities are in keeper.go?"                        | `entities_in_doc`        |
+| **Navigate by modules**                                  |                                                          |                          |
+| List all modules                                         | "What modules exist in regen-ledger?"                    | `list_modules`           |
+| Get details about a module                               | "Tell me about the ecocredit module"                     | `get_module`             |
+| Search for modules                                       | "Find modules related to baskets"                        | `search_modules`         |
+| Find entities in a module                                | "What entities are in the ecocredit module?"             | `module_entities`        |
+| **Search documentation**                                 |                                                          |                          |
+| Search GitHub docs                                       | "Search for documentation about credit classes"          | `search_github_docs`     |
+| Get repository overview                                  | "Give me an overview of regen-web"                       | `get_repo_overview`      |
+| Understand tech stack                                    | "What's the tech stack for regen-ledger?"                | `get_tech_stack`         |
+| **Search everything (hybrid)**                           |                                                          |                          |
+| Semantic search across code and docs                     | "How does credit retirement work?"                       | `hybrid_search`          |
+| Advanced filtering by date                               | "Find discussions about tokens from last week"           | `search_knowledge`       |
+| **Get activity summaries**                               |                                                          |                          |
+| Generate weekly digest                                   | "Create a weekly digest of Regen activity"               | `generate_weekly_digest` |
+
+### Query Type Reference
+
+The `query_code_graph` tool supports these query types:
+
+#### Discovery
+- **`list_repos`** - Show all indexed repositories with entity counts
+- **`list_entity_types`** - Show all entity types (Function, Class, Keeper, Message, etc.) with counts
+- **`get_entity_stats`** - Comprehensive statistics: entities by type, language, repository
+- **`list_modules`** - Show all modules across repositories
+
+#### Entity Queries
+- **`find_by_type`** - Find all entities of a specific type (requires `entity_type` parameter)
+- **`search_entities`** - Search entities by name pattern (requires `entity_name` parameter)
+- **`related_entities`** - Find entities related to a given entity (requires `entity_name` parameter)
+
+#### Relationship Queries
+- **`keeper_for_msg`** - Find which Keeper handles a Message (requires `entity_name` parameter)
+- **`msgs_for_keeper`** - Find what Messages a Keeper handles (requires `entity_name` parameter)
+- **`docs_mentioning`** - Find documentation mentioning an entity (requires `entity_name` parameter)
+- **`entities_in_doc`** - Find entities defined in a document (requires `doc_path` parameter)
+
+#### Module Queries
+- **`get_module`** - Get details about a specific module (requires `module_name` parameter)
+- **`search_modules`** - Search modules by keyword (requires `entity_name` parameter)
+- **`module_entities`** - Get entities in a module (requires `module_name` parameter)
+- **`module_for_entity`** - Find which module contains an entity (requires `entity_name` parameter)
+
+### What's Currently Indexed
+
+**Repositories:** 5 total
+- `regen-ledger`: 18,619 entities (Go, Cosmos SDK modules)
+- `regen-web`: 3,164 entities (TypeScript/React frontend)
+- `koi-sensors`: 1,250 entities (Python data collection)
+- `regen-koi-mcp`: 688 entities (TypeScript MCP server)
+- `regen-data-standards`: 6 entities (JSON schemas)
+
+**Entity Types:** 10 types
+- Function, Class, Interface, Method, Type
+- Keeper, Message, Query, Event (Cosmos SDK specific)
+- Module, Repository
+
+**Total:** 23,728 code entities
+
+---
+
 ## 🏗️ Architecture
 
 This repo contains everything you need to run a complete KOI MCP setup:
@@ -184,16 +329,35 @@ Or manually add to config (`~/Library/Application Support/Claude/claude_desktop_
 
 ### Claude Code CLI
 
-**One-line install:**
+**Option 1: Use the automated installer (recommended)**
 ```bash
-claude mcp add regen-koi npx -y regen-koi-mcp@latest
+curl -fsSL https://raw.githubusercontent.com/gaiaaiagent/regen-koi-mcp/main/install.sh | bash
 ```
+This configures both Claude Desktop and Claude Code CLI with the correct environment variables.
 
-Then set environment variable:
+**Option 2: Manual installation**
+1. Add the MCP server:
 ```bash
-export KOI_API_ENDPOINT=https://regen.gaiaai.xyz/api/koi
+claude mcp add regen-koi npx -y regen-koi-mcp@latest
+```
+
+2. Configure the environment variable in your Claude Code settings file (`~/.claude/settings.json` or similar):
+```json
+{
+  "mcpServers": {
+    "regen-koi": {
+      "command": "npx",
+      "args": ["-y", "regen-koi-mcp@latest"],
+      "env": {
+        "KOI_API_ENDPOINT": "https://regen.gaiaai.xyz/api/koi"
+      }
+    }
+  }
+}
 ```
 
+**Verification:** After installation, restart Claude Code and ask: "What repositories are indexed?" to verify the tools are working.
+
 ---
 
 ### VS Code / VS Code Insiders
@@ -545,6 +709,27 @@ The setup connects to our hosted KOI API at `https://regen.gaiaai.xyz/api/koi`.
 ### "Command not found"
 Make sure Node.js is installed and in your PATH. The setup script uses `node` command.
 
+### "Connection error: localhost:8301" or "localhost:8910"
+
+**Cause:** Claude caches MCP configurations in `~/.claude.json`. If you previously ran a local dev server, it may have cached `localhost` URLs that override your current config.
+
+**Fix:**
+```bash
+# 1. Check for cached localhost configs
+grep -i "localhost.*8301\|localhost.*8910" ~/.claude.json
+
+# 2. Backup your config
+cp ~/.claude.json ~/.claude.json.backup
+
+# 3. Replace localhost with public API
+sed -i '' 's|http://localhost:8301/api/koi|https://regen.gaiaai.xyz/api/koi|g' ~/.claude.json
+sed -i '' 's|http://localhost:8910/api/koi|https://regen.gaiaai.xyz/api/koi|g' ~/.claude.json
+
+# 4. Restart Claude Code/Desktop
+```
+
+**Prevention:** Always use `https://regen.gaiaai.xyz/api/koi` in MCP configs unless you're actively developing the API server locally.
+
 ## 📚 Example Usage
 
 Once configured, you can ask Claude:

package/dist/cache.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Cache Module - LRU Caching for Query Results
+ *
+ * Provides in-memory caching with TTL for query results to reduce
+ * database load and improve response times.
+ */
+/**
+ * Query Cache class
+ */
+declare class QueryCache {
+    private caches;
+    constructor();
+    /**
+     * Get cache for a specific category
+     */
+    private getCache;
+    /**
+     * Get the category for a query type
+     */
+    private getCategory;
+    /**
+     * Get a cached result
+     */
+    get<T>(tool: string, queryType: string, params: Record<string, any>): T | undefined;
+    /**
+     * Set a cached result
+     */
+    set<T>(tool: string, queryType: string, params: Record<string, any>, value: T): void;
+    /**
+     * Check if a key exists in cache
+     */
+    has(tool: string, queryType: string, params: Record<string, any>): boolean;
+    /**
+     * Delete a specific cached result
+     */
+    delete(tool: string, queryType: string, params: Record<string, any>): void;
+    /**
+     * Clear all caches
+     */
+    clear(): void;
+    /**
+     * Clear a specific category's cache
+     */
+    clearCategory(category: string): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        totalSize: number;
+        byCategory: Record<string, {
+            size: number;
+            maxSize: number;
+        }>;
+    };
+}
+export declare const queryCache: QueryCache;
+/**
+ * Wrapper function to cache async query results
+ */
+export declare function cachedQuery<T>(tool: string, queryType: string, params: Record<string, any>, fetchFn: () => Promise<T>): Promise<T>;
+/**
+ * Check if a query type should be cached
+ */
+export declare function shouldCache(queryType: string): boolean;
+/**
+ * Get TTL for a query type
+ */
+export declare function getTTL(queryType: string): number;
+export default queryCache;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgGH;;GAEG;AACH,cAAM,UAAU;IACd,OAAO,CAAC,MAAM,CAAiD;;IAc/D;;OAEG;IACH,OAAO,CAAC,QAAQ;IAShB;;OAEG;IACH,OAAO,CAAC,WAAW;IAInB;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS;IAkBnF;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAUpF;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO;IAO1E;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAQ1E;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOrC;;OAEG;IACH,QAAQ,IAAI;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC/D;CAeF;AAGD,eAAO,MAAM,UAAU,YAAmB,CAAC;AAE3C;;GAEG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC,CAcZ;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAGtD;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED,eAAe,UAAU,CAAC"}

package/dist/cache.js

@@ -0,0 +1,230 @@
+/**
+ * Cache Module - LRU Caching for Query Results
+ *
+ * Provides in-memory caching with TTL for query results to reduce
+ * database load and improve response times.
+ */
+import { LRUCache } from 'lru-cache';
+import crypto from 'crypto';
+import { logCacheOp } from './logger.js';
+import { recordCacheHit, recordCacheMiss } from './metrics.js';
+/**
+ * Default cache configurations by category
+ */
+const CACHE_CONFIGS = {
+    // Static data - cache for 1 hour
+    static: {
+        ttlMs: 60 * 60 * 1000, // 1 hour
+        maxSize: 100
+    },
+    // Semi-static data - cache for 10 minutes
+    semi_static: {
+        ttlMs: 10 * 60 * 1000, // 10 minutes
+        maxSize: 200
+    },
+    // Dynamic queries - cache for 5 minutes
+    dynamic: {
+        ttlMs: 5 * 60 * 1000, // 5 minutes
+        maxSize: 500
+    },
+    // Frequently changing - cache for 1 minute
+    volatile: {
+        ttlMs: 60 * 1000, // 1 minute
+        maxSize: 100
+    }
+};
+/**
+ * Map query types to cache categories
+ */
+const QUERY_TYPE_TO_CATEGORY = {
+    // Static (changes rarely)
+    'list_repos': 'static',
+    'list_entity_types': 'static',
+    'get_entity_stats': 'static',
+    'get_tech_stack': 'static',
+    'get_repo_overview': 'static',
+    'list_modules': 'static',
+    // Semi-static (changes occasionally)
+    'find_by_type': 'semi_static',
+    'get_module': 'semi_static',
+    'search_modules': 'semi_static',
+    'module_entities': 'semi_static',
+    'module_for_entity': 'semi_static',
+    // Dynamic (user queries)
+    'search_entities': 'dynamic',
+    'search_knowledge': 'dynamic',
+    'search_github_docs': 'dynamic',
+    'hybrid_search': 'dynamic',
+    'keeper_for_msg': 'dynamic',
+    'msgs_for_keeper': 'dynamic',
+    'docs_mentioning': 'dynamic',
+    'entities_in_doc': 'dynamic',
+    'related_entities': 'dynamic',
+    // Volatile (changes frequently)
+    'get_stats': 'volatile',
+    'generate_weekly_digest': 'volatile'
+};
+/**
+ * Generate a cache key from query parameters
+ */
+function generateCacheKey(tool, queryType, params) {
+    // Create a deterministic string from params
+    const sortedParams = Object.keys(params)
+        .filter(k => params[k] !== undefined && params[k] !== null)
+        .sort()
+        .map(k => `${k}=${JSON.stringify(params[k])}`)
+        .join('|');
+    const keyString = `${tool}:${queryType}:${sortedParams}`;
+    // Hash for consistent key length
+    const hash = crypto.createHash('sha256').update(keyString).digest('hex').substring(0, 16);
+    return `${tool}:${queryType}:${hash}`;
+}
+/**
+ * Query Cache class
+ */
+class QueryCache {
+    caches = new Map();
+    constructor() {
+        // Initialize caches for each category
+        for (const [category, config] of Object.entries(CACHE_CONFIGS)) {
+            this.caches.set(category, new LRUCache({
+                max: config.maxSize,
+                ttl: config.ttlMs,
+                updateAgeOnGet: false, // Don't refresh TTL on read
+                updateAgeOnHas: false
+            }));
+        }
+    }
+    /**
+     * Get cache for a specific category
+     */
+    getCache(category) {
+        const cache = this.caches.get(category);
+        if (!cache) {
+            // Fall back to dynamic cache
+            return this.caches.get('dynamic');
+        }
+        return cache;
+    }
+    /**
+     * Get the category for a query type
+     */
+    getCategory(queryType) {
+        return QUERY_TYPE_TO_CATEGORY[queryType] || 'dynamic';
+    }
+    /**
+     * Get a cached result
+     */
+    get(tool, queryType, params) {
+        const category = this.getCategory(queryType);
+        const cache = this.getCache(category);
+        const key = generateCacheKey(tool, queryType, params);
+        const cached = cache.get(key);
+        if (cached !== undefined) {
+            logCacheOp({ operation: 'hit', key });
+            recordCacheHit();
+            return cached;
+        }
+        else {
+            logCacheOp({ operation: 'miss', key });
+            recordCacheMiss();
+            return undefined;
+        }
+    }
+    /**
+     * Set a cached result
+     */
+    set(tool, queryType, params, value) {
+        const category = this.getCategory(queryType);
+        const cache = this.getCache(category);
+        const key = generateCacheKey(tool, queryType, params);
+        const config = CACHE_CONFIGS[category] || CACHE_CONFIGS.dynamic;
+        cache.set(key, value);
+        logCacheOp({ operation: 'set', key, ttl_ms: config.ttlMs });
+    }
+    /**
+     * Check if a key exists in cache
+     */
+    has(tool, queryType, params) {
+        const category = this.getCategory(queryType);
+        const cache = this.getCache(category);
+        const key = generateCacheKey(tool, queryType, params);
+        return cache.has(key);
+    }
+    /**
+     * Delete a specific cached result
+     */
+    delete(tool, queryType, params) {
+        const category = this.getCategory(queryType);
+        const cache = this.getCache(category);
+        const key = generateCacheKey(tool, queryType, params);
+        cache.delete(key);
+        logCacheOp({ operation: 'evict', key });
+    }
+    /**
+     * Clear all caches
+     */
+    clear() {
+        for (const cache of this.caches.values()) {
+            cache.clear();
+        }
+    }
+    /**
+     * Clear a specific category's cache
+     */
+    clearCategory(category) {
+        const cache = this.caches.get(category);
+        if (cache) {
+            cache.clear();
+        }
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        let totalSize = 0;
+        const byCategory = {};
+        for (const [category, cache] of this.caches) {
+            const size = cache.size;
+            totalSize += size;
+            byCategory[category] = {
+                size,
+                maxSize: CACHE_CONFIGS[category]?.maxSize || 0
+            };
+        }
+        return { totalSize, byCategory };
+    }
+}
+// Singleton instance
+export const queryCache = new QueryCache();
+/**
+ * Wrapper function to cache async query results
+ */
+export async function cachedQuery(tool, queryType, params, fetchFn) {
+    // Check cache first
+    const cached = queryCache.get(tool, queryType, params);
+    if (cached !== undefined) {
+        return cached;
+    }
+    // Execute query
+    const result = await fetchFn();
+    // Cache result
+    queryCache.set(tool, queryType, params, result);
+    return result;
+}
+/**
+ * Check if a query type should be cached
+ */
+export function shouldCache(queryType) {
+    // Don't cache volatile queries
+    return QUERY_TYPE_TO_CATEGORY[queryType] !== 'volatile';
+}
+/**
+ * Get TTL for a query type
+ */
+export function getTTL(queryType) {
+    const category = QUERY_TYPE_TO_CATEGORY[queryType] || 'dynamic';
+    return CACHE_CONFIGS[category]?.ttlMs || CACHE_CONFIGS.dynamic.ttlMs;
+}
+export default queryCache;
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/graph_tool.d.ts

@@ -3,11 +3,23 @@
  *
  * Provides an MCP tool interface for querying the Apache AGE graph database
  * containing Regen Network code entities and relationships.
+ *
+ * Supports two modes:
+ * 1. API mode: When KOI_API_ENDPOINT is set, uses HTTP API at /api/koi/graph
+ * 2. Direct mode: Connects directly to PostgreSQL (only works on server)
+ *
+ * Production Features (Phase 7):
+ * - Structured logging with pino
+ * - Metrics collection for performance monitoring
+ * - Retry logic with exponential backoff
+ * - Circuit breaker for preventing cascading failures
+ * - LRU caching for query results
+ * - Input validation with zod schemas
  */
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 export declare const GRAPH_TOOL: Tool;
 /**
- * Execute the query_code_graph tool
+ * Execute the query_code_graph tool with production hardening
  */
 export declare function executeGraphTool(args: any): Promise<{
     content: {
@@ -30,6 +42,9 @@ declare const _default: {
             } | undefined;
             required?: string[] | undefined;
         };
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
         title?: string | undefined;
         description?: string | undefined;
         outputSchema?: {
@@ -48,9 +63,6 @@ declare const _default: {
             idempotentHint?: boolean | undefined;
             openWorldHint?: boolean | undefined;
         } | undefined;
-        _meta?: {
-            [x: string]: unknown;
-        } | undefined;
         icons?: {
             [x: string]: unknown;
             src: string;

package/dist/graph_tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_tool.d.ts","sourceRoot":"","sources":["../src/graph_tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAe1D,eAAO,MAAM,UAAU,EAAE,IAuCxB,CAAC;AAgBF;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,GAAG;;;;;GAia/C;AAgID;;GAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACH,wBAGE"}
+{"version":3,"file":"graph_tool.d.ts","sourceRoot":"","sources":["../src/graph_tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAyB1D,eAAO,MAAM,UAAU,EAAE,IAyCxB,CAAC;AAiIF;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,GAAG;;;;;GA6qB/C;AAgID;;GAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACH,wBAGE"}