@massa-ai/core 1.2.1

package/dist/tools/get_analytics.js

@@ -0,0 +1,114 @@
+/**
+ * Get Analytics Tool
+ *
+ * Retrieves search analytics and performance metrics
+ */
+import { getSearchAnalytics } from "../services/search/analytics-factory.js";
+import { logger } from "@massa-ai/shared";
+import { validateEnum } from "./enum-validation.js";
+export class GetAnalyticsTool {
+    name = "get_analytics";
+    description = "Get search analytics and performance metrics (usage patterns, cache performance, etc)";
+    inputSchema = {
+        type: "object",
+        properties: {
+            type: {
+                type: "string",
+                enum: ["summary", "project", "query", "cache", "recent"],
+                description: "Type of analytics: 'summary' (overall), 'project' (specific project), 'query' (specific query), 'cache' (cache performance), 'recent' (recent searches)",
+            },
+            projectId: {
+                type: "string",
+                description: "Project ID. Required for type='project'. Optional for type='cache' (omit for global cache stats across all projects; provide to scope to one project). Optional for type='query'/'recent'.",
+            },
+            query: {
+                type: "string",
+                description: "Search query (required for type='query')",
+            },
+            limit: {
+                type: "number",
+                description: "Limit for results (default: 10 for most, 50 for recent)",
+                default: 10,
+            },
+        },
+        required: ["type"],
+    };
+    constructor() { }
+    async handle(params) {
+        const { projectId, query, limit = 10 } = params;
+        const type = validateEnum("type", params.type, ["summary", "project", "query", "cache", "recent"]);
+        try {
+            const analytics = getSearchAnalytics();
+            logger.info("Getting analytics", { type, projectId, query });
+            let data;
+            switch (type) {
+                case "summary":
+                    data = await analytics.getSummary(limit);
+                    break;
+                case "project":
+                    if (!projectId) {
+                        return {
+                            success: false,
+                            error: "projectId is required for type='project'",
+                        };
+                    }
+                    data = await analytics.getProjectStats(projectId, limit);
+                    if (!data) {
+                        return {
+                            success: false,
+                            error: `No analytics found for project: ${projectId}`,
+                        };
+                    }
+                    break;
+                case "query":
+                    if (!query) {
+                        return {
+                            success: false,
+                            error: "query is required for type='query'",
+                        };
+                    }
+                    data = await analytics.getQueryStats(query, projectId);
+                    if (!data) {
+                        return {
+                            success: false,
+                            error: `No analytics found for query: ${query}`,
+                        };
+                    }
+                    break;
+                case "cache":
+                    data = await analytics.getCachePerformance(projectId);
+                    break;
+                case "recent": {
+                    const recentLimit = limit || 50;
+                    data = await analytics.getRecentSearches(recentLimit, projectId);
+                    break;
+                }
+            }
+            logger.info("Analytics retrieved", {
+                type,
+                dataSize: JSON.stringify(data).length,
+            });
+            return {
+                success: true,
+                data: {
+                    type,
+                    ...(projectId && { projectId }),
+                    ...(query && { query }),
+                    result: data,
+                },
+            };
+        }
+        catch (error) {
+            logger.error("Failed to get analytics", error, {
+                type,
+                projectId,
+                query,
+            });
+            return {
+                success: false,
+                error: `Failed to get analytics: ${error.message}`,
+            };
+        }
+    }
+}
+//# sourceMappingURL=get_analytics.js.map

package/dist/tools/get_analytics.js.map

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

package/dist/tools/get_architecture.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Get Architecture Tool (get_architecture) — Wave 5 FR-01 / FR-02.
+ *
+ * Returns the architecture map for a project: packages, entry points, routes,
+ * hotspots, communities, layers, and opt-in `cycles` (iterative Tarjan SCC
+ * over CALL edges). Mirrors the existing `project_map` tool but with opt-in
+ * aspects and a teaching-error-first contract (unknown aspect → 400 listing
+ * valid values, Wave 4 N6 parity).
+ *
+ * Input:  { projectId, projectPath?, aspects?, centralityLimit?, format?, fields? }
+ * Output: serialized ArchitectureMap (cycles + cycles_truncated present only
+ *         when `aspects` includes "cycles").
+ */
+import { IToolHandler, ToolResponse } from "@massa-ai/shared";
+export declare class GetArchitectureTool implements IToolHandler {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            projectId: {
+                type: string;
+                description: string;
+            };
+            projectPath: {
+                type: string;
+                description: string;
+            };
+            aspects: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            centralityLimit: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            format: {
+                type: string;
+                enum: string[];
+                description: string;
+                default: string;
+            };
+            fields: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handle(params: unknown): Promise<ToolResponse>;
+}
+//# sourceMappingURL=get_architecture.d.ts.map

package/dist/tools/get_architecture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get_architecture.d.ts","sourceRoot":"","sources":["../../src/tools/get_architecture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAkB9D,qBAAa,mBAAoB,YAAW,YAAY;IACtD,IAAI,SAAsB;IAC1B,WAAW,SAE0J;IAErK,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAsCT;IAEI,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;CAiDrD"}

package/dist/tools/get_architecture.js

@@ -0,0 +1,104 @@
+/**
+ * Get Architecture Tool (get_architecture) — Wave 5 FR-01 / FR-02.
+ *
+ * Returns the architecture map for a project: packages, entry points, routes,
+ * hotspots, communities, layers, and opt-in `cycles` (iterative Tarjan SCC
+ * over CALL edges). Mirrors the existing `project_map` tool but with opt-in
+ * aspects and a teaching-error-first contract (unknown aspect → 400 listing
+ * valid values, Wave 4 N6 parity).
+ *
+ * Input:  { projectId, projectPath?, aspects?, centralityLimit?, format?, fields? }
+ * Output: serialized ArchitectureMap (cycles + cycles_truncated present only
+ *         when `aspects` includes "cycles").
+ */
+import { symbolGraphService } from "../services/symbol/symbol-graph.service.js";
+import { serializeToolResponse } from "./serialize.js";
+import { ToolError } from "./enum-validation.js";
+import { VALID_ARCHITECTURE_ASPECTS } from "../services/symbol/architecture.js";
+export class GetArchitectureTool {
+    name = "get_architecture";
+    description = "Get the architecture map for a project: packages, entry points, routes, hotspots, communities, layers, and opt-in cycles (Tarjan SCC over CALL edges). " +
+        "Pass aspects:[\"cycles\"] to surface strongly connected components (file-level call cycles). Unknown aspect values return a teaching error listing valid values.";
+    inputSchema = {
+        type: "object",
+        properties: {
+            projectId: {
+                type: "string",
+                description: "The project ID (as registered via index_project).",
+            },
+            projectPath: {
+                type: "string",
+                description: "Absolute path to the project working tree. Optional; used only for auto-reindex triggers.",
+            },
+            aspects: {
+                type: "array",
+                items: { type: "string" },
+                description: "Opt-in aspects. Only \"cycles\" today: runs iterative Tarjan SCC over CALL edges and returns { cycles, cycles_truncated }. Unknown values return a 400 teaching error listing valid values.",
+            },
+            centralityLimit: {
+                type: "number",
+                description: "Max number of top central files to include. Default 20.",
+                default: 20,
+            },
+            format: {
+                type: "string",
+                enum: ["json", "toon", "tree"],
+                description: "Output format. 'json' (default) emits the raw object. 'toon' encodes it. 'tree' (Wave 5 FR-06) emits a text-indented grouped model via the shared groupRowsByPrefix helper (groups hotspots by file). Default: json.",
+                default: "json",
+            },
+            fields: {
+                type: "array",
+                items: { type: "string" },
+                description: "Projection — keep only these keys (dotted paths supported). Absent/empty → full data.",
+            },
+        },
+        required: ["projectId"],
+    };
+    async handle(params) {
+        const p = params;
+        const { format = "json", fields } = p;
+        if (!p.projectId) {
+            return { success: false, error: "projectId is required" };
+        }
+        // Validate aspects (teaching error before any DB work — Wave 4 N6 parity).
+        if (p.aspects !== undefined) {
+            for (const a of p.aspects) {
+                if (!VALID_ARCHITECTURE_ASPECTS.includes(a)) {
+                    return {
+                        success: false,
+                        error: `Invalid aspects value: ${String(a)}. Valid values: ${VALID_ARCHITECTURE_ASPECTS.join(", ")}.`,
+                    };
+                }
+            }
+        }
+        const centralityLimit = p.centralityLimit ?? 20;
+        try {
+            const map = await symbolGraphService.getArchitecture(p.projectId, {
+                aspects: p.aspects,
+                centralityLimit,
+            });
+            if (!map) {
+                return {
+                    success: false,
+                    error: `Project '${p.projectId}' not found or has no indexed files.`,
+                };
+            }
+            // Wave 5 FR-07: tree format groups hotspots by file via the shared
+            // groupRowsByPrefix helper. json/toon unchanged when tree not selected.
+            const groupOpts = format === "tree" ? { format, fields, groupBy: { file: "file" } } : { format, fields };
+            return serializeToolResponse(map, groupOpts);
+        }
+        catch (error) {
+            // ToolError (teaching error from the service or the validator) →
+            // surface the message verbatim so the MCP transport maps it to 400.
+            if (error instanceof ToolError) {
+                return { success: false, error: error.message };
+            }
+            return {
+                success: false,
+                error: `Failed to get architecture: ${error.message}`,
+            };
+        }
+    }
+}
+//# sourceMappingURL=get_architecture.js.map

package/dist/tools/get_architecture.js.map

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

package/dist/tools/get_index_status.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Get Index Status Tool
+ *
+ * Queries the status and progress of an async indexing job.
+ */
+import { IToolHandler } from "@massa-ai/shared";
+import { ToolResponse } from "@massa-ai/shared";
+export declare class GetIndexStatusTool implements IToolHandler {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            jobId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handle(params: unknown): Promise<ToolResponse>;
+}
+//# sourceMappingURL=get_index_status.d.ts.map

package/dist/tools/get_index_status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get_index_status.d.ts","sourceRoot":"","sources":["../../src/tools/get_index_status.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAQhD,qBAAa,kBAAmB,YAAW,YAAY;IACrD,IAAI,SAAsB;IAC1B,WAAW,SACiE;IAC5E,WAAW;;;;;;;;;MAST;IAEI,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;CA2CrD"}

package/dist/tools/get_index_status.js

@@ -0,0 +1,61 @@
+/**
+ * Get Index Status Tool
+ *
+ * Queries the status and progress of an async indexing job.
+ */
+import { indexJobTracker } from "../services/jobs/index-job-tracker.js";
+import { logger } from "@massa-ai/shared";
+export class GetIndexStatusTool {
+    name = "get_index_status";
+    description = "Get the status and progress of an async indexing job started with index";
+    inputSchema = {
+        type: "object",
+        properties: {
+            jobId: {
+                type: "string",
+                description: "Job ID returned by index",
+            },
+        },
+        required: ["jobId"],
+    };
+    async handle(params) {
+        const { jobId } = params;
+        try {
+            const job = indexJobTracker.getJob(jobId);
+            if (!job) {
+                return {
+                    success: false,
+                    error: `Job not found: ${jobId}`,
+                };
+            }
+            // Calcula elapsed time
+            const elapsed = job.completedAt
+                ? job.completedAt.getTime() - job.createdAt.getTime()
+                : Date.now() - job.createdAt.getTime();
+            return {
+                success: true,
+                data: {
+                    jobId: job.jobId,
+                    projectId: job.projectId,
+                    projectPath: job.projectPath,
+                    status: job.status,
+                    progress: job.progress,
+                    result: job.result,
+                    error: job.error,
+                    elapsedMs: elapsed,
+                    createdAt: job.createdAt.toISOString(),
+                    startedAt: job.startedAt?.toISOString(),
+                    completedAt: job.completedAt?.toISOString(),
+                },
+            };
+        }
+        catch (error) {
+            logger.error("Failed to get index status", error, { jobId });
+            return {
+                success: false,
+                error: `Failed to get status: ${error.message}`,
+            };
+        }
+    }
+}
+//# sourceMappingURL=get_index_status.js.map

package/dist/tools/get_index_status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get_index_status.js","sourceRoot":"","sources":["../../src/tools/get_index_status.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAM1C,MAAM,OAAO,kBAAkB;IAC7B,IAAI,GAAG,kBAAkB,CAAC;IAC1B,WAAW,GACT,yEAAyE,CAAC;IAC5E,WAAW,GAAG;QACZ,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,0BAA0B;aACxC;SACF;QACD,QAAQ,EAAE,CAAC,OAAO,CAAC;KACpB,CAAC;IAEF,KAAK,CAAC,MAAM,CAAC,MAAe;QAC1B,MAAM,EAAE,KAAK,EAAE,GAAG,MAA8B,CAAC;QAEjD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAE1C,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,kBAAkB,KAAK,EAAE;iBACjC,CAAC;YACJ,CAAC;YAED,uBAAuB;YACvB,MAAM,OAAO,GAAG,GAAG,CAAC,WAAW;gBAC7B,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,OAAO,EAAE;gBACrD,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;YAEzC,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,IAAI,EAAE;oBACJ,KAAK,EAAE,GAAG,CAAC,KAAK;oBAChB,SAAS,EAAE,GAAG,CAAC,SAAS;oBACxB,WAAW,EAAE,GAAG,CAAC,WAAW;oBAC5B,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,QAAQ,EAAE,GAAG,CAAC,QAAQ;oBACtB,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,KAAK,EAAE,GAAG,CAAC,KAAK;oBAChB,SAAS,EAAE,OAAO;oBAClB,SAAS,EAAE,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE;oBACtC,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE;oBACvC,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,WAAW,EAAE;iBAC5C;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,4BAA4B,EAAE,KAAc,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YAEtE,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,yBAA0B,KAAe,CAAC,OAAO,EAAE;aAC3D,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/tools/get_optimized_context.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Get Optimized Context Tool
+ *
+ * Thin MCP tool layer — validates input and delegates to ContextController.
+ * All business logic lives in controllers/context-controller.ts.
+ */
+import { IToolHandler, ToolResponse } from "@massa-ai/shared";
+export declare class GetOptimizedContextTool implements IToolHandler {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            projectId: {
+                type: string;
+                description: string;
+            };
+            projectPath: {
+                type: string;
+                description: string;
+            };
+            maxTokens: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            maxResults: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            workingMemoryBudget: {
+                type: string;
+                description: string;
+            };
+            userId: {
+                type: string;
+                description: string;
+            };
+            sessionId: {
+                type: string;
+                description: string;
+            };
+            includeMemories: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
+            memoryBudgetRatio: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            format: {
+                type: string;
+                enum: string[];
+                description: string;
+                default: string;
+            };
+            fields: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    private controller;
+    constructor();
+    handle(params: unknown): Promise<ToolResponse>;
+}
+//# sourceMappingURL=get_optimized_context.d.ts.map

package/dist/tools/get_optimized_context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get_optimized_context.d.ts","sourceRoot":"","sources":["../../src/tools/get_optimized_context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAoB9D,qBAAa,uBAAwB,YAAW,YAAY;IAC1D,IAAI,SAA2B;IAC/B,WAAW,SACkG;IAC7G,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAiET;IAEF,OAAO,CAAC,UAAU,CAAoB;;IAMhC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;CAkCrD"}

package/dist/tools/get_optimized_context.js

@@ -0,0 +1,110 @@
+/**
+ * Get Optimized Context Tool
+ *
+ * Thin MCP tool layer — validates input and delegates to ContextController.
+ * All business logic lives in controllers/context-controller.ts.
+ */
+import { logger } from "@massa-ai/shared";
+import { ContextController } from "../controllers/context-controller.js";
+import { serializeToolResponse } from "./serialize.js";
+export class GetOptimizedContextTool {
+    name = "get_optimized_context";
+    description = "Retrieve code context + persistent memories with maximum token efficiency (search + memories + compress)";
+    inputSchema = {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "Search query to find relevant context",
+            },
+            projectId: {
+                type: "string",
+                description: "Project ID for code context",
+            },
+            projectPath: {
+                type: "string",
+                description: "Project path (for auto-reindex)",
+            },
+            maxTokens: {
+                type: "number",
+                description: "Maximum tokens in returned context",
+                default: 4000,
+            },
+            maxResults: {
+                type: "number",
+                description: "Maximum search results to include",
+                default: 5,
+            },
+            workingMemoryBudget: {
+                type: "number",
+                description: "Token budget for active working set before compression (defaults to 80% of maxTokens)",
+            },
+            userId: {
+                type: "string",
+                description: "User ID for memory search (filters memories by user)",
+            },
+            sessionId: {
+                type: "string",
+                description: "Session ID for memory search (includes current session memories)",
+            },
+            includeMemories: {
+                type: "boolean",
+                description: "Include persistent memories from previous sessions (default: true)",
+                default: true,
+            },
+            memoryBudgetRatio: {
+                type: "number",
+                description: "Fraction of maxTokens allocated for memories (0-1, default: 0.2 = 20%)",
+                default: 0.2,
+            },
+            format: {
+                type: "string",
+                enum: ["json", "toon"],
+                description: "Output format (json or toon). Default: json.",
+                default: "json",
+            },
+            fields: {
+                type: "array",
+                items: { type: "string" },
+                description: "Projection — keep only these keys (dotted paths supported, e.g. ['nodes.symbol']). Absent/empty → full data.",
+            },
+        },
+        required: ["query", "projectId"],
+    };
+    controller;
+    constructor() {
+        this.controller = ContextController.getInstance();
+    }
+    async handle(params) {
+        const p = params;
+        const { format = "json", fields } = p;
+        try {
+            const result = await this.controller.getOptimizedContext(p);
+            const data = {
+                context: result.context,
+                sources: result.sources,
+                resultsCount: result.resultsCount,
+                memoriesCount: result.memoriesCount,
+                sessionCacheHits: result.sessionCacheHits,
+            };
+            const metadata = {
+                tokensSaved: result.tokensSaved,
+                compressionRatio: result.compressionRatio,
+                tokensSavedBySessionCache: result.tokensSavedBySessionCache,
+                cacheHit: result.sessionCacheHits > 0,
+            };
+            return { ...serializeToolResponse(data, { format, fields }), metadata };
+        }
+        catch (error) {
+            logger.error("Failed to get optimized context", error, {
+                query: p.query,
+                projectId: p.projectId,
+            });
+            return {
+                success: false,
+                error: `Failed to retrieve context: ${error.message}`,
+            };
+        }
+    }
+}
+//# sourceMappingURL=get_optimized_context.js.map

package/dist/tools/get_optimized_context.js.map

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

package/dist/tools/get_references.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Get References Tool (get_references)
+ *
+ * Find all usage sites of a symbol across the project.
+ * Returns file, line, usage kind, and code context snippets.
+ */
+import { IToolHandler, ToolResponse } from "@massa-ai/shared";
+export declare class GetReferencesTool implements IToolHandler {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            projectId: {
+                type: string;
+                description: string;
+            };
+            symbolName: {
+                type: string;
+                description: string;
+            };
+            fqn: {
+                type: string;
+                description: string;
+            };
+            maxResults: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            ifNoneMatch: {
+                type: string;
+                description: string;
+            };
+            format: {
+                type: string;
+                enum: string[];
+                description: string;
+                default: string;
+            };
+            fields: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handle(params: unknown): Promise<ToolResponse>;
+}
+//# sourceMappingURL=get_references.d.ts.map

package/dist/tools/get_references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get_references.d.ts","sourceRoot":"","sources":["../../src/tools/get_references.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAsB9D,qBAAa,iBAAkB,YAAW,YAAY;IACpD,IAAI,SAAoB;IACxB,WAAW,SAC+J;IAE1K,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAyCT;IAEI,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;CA0ErD"}