@crowley/rag-mcp 1.0.5 → 1.0.6

package/dist/tools/clustering.js

@@ -3,249 +3,188 @@
  * similarity recommendations, and learning extraction.
  */
 import { truncate, pct, PREVIEW } from "../formatters.js";
+import { z } from "zod";
+import { TOOL_ANNOTATIONS } from "../annotations.js";
 /**
  * Create the clustering tools module with project-specific descriptions.
  */
 export function createClusteringTools(projectName) {
-    const tools = [
+    return [
         {
             name: "cluster_code",
             description: `Cluster code in the ${projectName} codebase by similarity. Groups related files around seed points.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    seedIds: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Seed point IDs to cluster around",
-                    },
-                    limit: {
-                        type: "number",
-                        description: "Max results per cluster (default: 5)",
-                        default: 5,
-                    },
-                    threshold: {
-                        type: "number",
-                        description: "Minimum similarity threshold (0-1, default: 0.7)",
-                        default: 0.7,
-                    },
-                },
-                required: ["seedIds"],
+            schema: z.object({
+                seedIds: z.array(z.string()).describe("Seed point IDs to cluster around"),
+                limit: z.number().optional().describe("Max results per cluster (default: 5)"),
+                threshold: z.number().optional().describe("Minimum similarity threshold (0-1, default: 0.7)"),
+            }),
+            annotations: TOOL_ANNOTATIONS["cluster_code"],
+            handler: async (args, ctx) => {
+                const { seedIds, limit = 5, threshold = 0.7 } = args;
+                const response = await ctx.api.post("/api/clusters", {
+                    collection: `${ctx.collectionPrefix}codebase`,
+                    seedIds,
+                    limit,
+                    threshold,
+                });
+                const data = response.data;
+                const clusters = data.clusters || data;
+                if (!clusters || (Array.isArray(clusters) && clusters.length === 0)) {
+                    return "No clusters found.";
+                }
+                let result = `## Code Clusters\n\n`;
+                for (const cluster of Array.isArray(clusters) ? clusters : [clusters]) {
+                    result += `### Seed: ${cluster.seedId || cluster.seed || "unknown"}\n`;
+                    const files = cluster.similar || cluster.files || cluster.results || [];
+                    for (const f of files) {
+                        result += `- **${f.file || f.name}** (${pct(f.score || f.similarity)})`;
+                        if (f.content)
+                            result += `\n  ${truncate(f.content, PREVIEW.SHORT)}`;
+                        result += "\n";
+                    }
+                    result += "\n";
+                }
+                return result;
             },
         },
         {
             name: "find_duplicates",
             description: `Find duplicate or near-duplicate code in ${projectName}. Groups similar files by content.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    collection: {
-                        type: "string",
-                        description: "Collection to search (default: codebase)",
-                    },
-                    limit: {
-                        type: "number",
-                        description: "Max duplicate groups to return (default: 10)",
-                        default: 10,
-                    },
-                    threshold: {
-                        type: "number",
-                        description: "Minimum similarity threshold (0-1, default: 0.9)",
-                        default: 0.9,
-                    },
-                },
+            schema: z.object({
+                collection: z.string().optional().describe("Collection to search (default: codebase)"),
+                limit: z.number().optional().describe("Max duplicate groups to return (default: 10)"),
+                threshold: z.number().optional().describe("Minimum similarity threshold (0-1, default: 0.9)"),
+            }),
+            annotations: TOOL_ANNOTATIONS["find_duplicates"],
+            handler: async (args, ctx) => {
+                const { collection, limit = 10, threshold = 0.9 } = args;
+                const fullCollection = collection
+                    ? (collection.startsWith(ctx.collectionPrefix) ? collection : `${ctx.collectionPrefix}${collection}`)
+                    : `${ctx.collectionPrefix}codebase`;
+                const response = await ctx.api.post("/api/duplicates", {
+                    collection: fullCollection,
+                    limit,
+                    threshold,
+                });
+                const data = response.data;
+                const groups = data.groups || data.duplicates || data;
+                if (!groups || (Array.isArray(groups) && groups.length === 0)) {
+                    return "No duplicates found.";
+                }
+                let result = `## Duplicate Code Groups\n\n`;
+                let groupNum = 1;
+                for (const group of Array.isArray(groups) ? groups : [groups]) {
+                    result += `### Group ${groupNum++}\n`;
+                    const files = group.files || group.items || group.results || [];
+                    const similarity = group.similarity || group.score;
+                    if (similarity) {
+                        result += `**Similarity:** ${pct(similarity)}\n`;
+                    }
+                    for (const f of files) {
+                        result += `- **${f.file || f.name}**`;
+                        if (f.content)
+                            result += `\n  ${truncate(f.content, 80)}`;
+                        result += "\n";
+                    }
+                    result += "\n";
+                }
+                return result;
             },
         },
         {
             name: "recommend_similar",
             description: `Recommend similar code based on positive and negative examples in ${projectName}.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    positiveIds: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "IDs of vectors to find similar code to",
-                    },
-                    negativeIds: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "IDs of vectors to avoid (dissimilar)",
-                    },
-                    limit: {
-                        type: "number",
-                        description: "Max results (default: 5)",
-                        default: 5,
-                    },
-                },
-                required: ["positiveIds"],
+            schema: z.object({
+                positiveIds: z.array(z.string()).describe("IDs of vectors to find similar code to"),
+                negativeIds: z.array(z.string()).optional().describe("IDs of vectors to avoid (dissimilar)"),
+                limit: z.number().optional().describe("Max results (default: 5)"),
+            }),
+            annotations: TOOL_ANNOTATIONS["recommend_similar"],
+            handler: async (args, ctx) => {
+                const { positiveIds, negativeIds, limit = 5 } = args;
+                const response = await ctx.api.post("/api/recommend", {
+                    collection: `${ctx.collectionPrefix}codebase`,
+                    positiveIds,
+                    negativeIds,
+                    limit,
+                });
+                const results = response.data.results || response.data;
+                if (!results || results.length === 0) {
+                    return "No recommendations found.";
+                }
+                let result = `## Recommendations\n\n`;
+                for (const r of results) {
+                    result += `- **${r.file || r.name}** (${pct(r.score || r.similarity)})`;
+                    if (r.content)
+                        result += `\n  ${truncate(r.content, PREVIEW.SHORT)}`;
+                    result += "\n";
+                }
+                return result;
             },
         },
         {
             name: "extract_learnings",
             description: `Extract learnings and insights from text for ${projectName}. Identifies decisions, patterns, and concepts.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    text: {
-                        type: "string",
-                        description: "Text to extract learnings from",
-                    },
-                    context: {
-                        type: "string",
-                        description: "Additional context about the text",
-                    },
-                    autoSave: {
-                        type: "boolean",
-                        description: "Automatically save extracted learnings (default: false)",
-                        default: false,
-                    },
-                    minConfidence: {
-                        type: "number",
-                        description: "Minimum confidence threshold (0-1, default: 0.7)",
-                        default: 0.7,
-                    },
-                },
-                required: ["text"],
-            },
-        },
-    ];
-    const handlers = {
-        cluster_code: async (args, ctx) => {
-            const { seedIds, limit = 5, threshold = 0.7 } = args;
-            const response = await ctx.api.post("/api/clusters", {
-                collection: `${ctx.projectName}_codebase`,
-                seedIds,
-                limit,
-                threshold,
-            });
-            const data = response.data;
-            const clusters = data.clusters || data;
-            if (!clusters || (Array.isArray(clusters) && clusters.length === 0)) {
-                return "No clusters found.";
-            }
-            let result = `## Code Clusters\n\n`;
-            for (const cluster of Array.isArray(clusters) ? clusters : [clusters]) {
-                result += `### Seed: ${cluster.seedId || cluster.seed || "unknown"}\n`;
-                const files = cluster.similar || cluster.files || cluster.results || [];
-                for (const f of files) {
-                    result += `- **${f.file || f.name}** (${pct(f.score || f.similarity)})`;
-                    if (f.content)
-                        result += `\n  ${truncate(f.content, PREVIEW.SHORT)}`;
-                    result += "\n";
-                }
-                result += "\n";
-            }
-            return result;
-        },
-        find_duplicates: async (args, ctx) => {
-            const { collection, limit = 10, threshold = 0.9 } = args;
-            const fullCollection = collection
-                ? (collection.startsWith(ctx.collectionPrefix) ? collection : `${ctx.collectionPrefix}${collection}`)
-                : `${ctx.collectionPrefix}codebase`;
-            const response = await ctx.api.post("/api/duplicates", {
-                collection: fullCollection,
-                limit,
-                threshold,
-            });
-            const data = response.data;
-            const groups = data.groups || data.duplicates || data;
-            if (!groups || (Array.isArray(groups) && groups.length === 0)) {
-                return "No duplicates found.";
-            }
-            let result = `## Duplicate Code Groups\n\n`;
-            let groupNum = 1;
-            for (const group of Array.isArray(groups) ? groups : [groups]) {
-                result += `### Group ${groupNum++}\n`;
-                const files = group.files || group.items || group.results || [];
-                const similarity = group.similarity || group.score;
-                if (similarity) {
-                    result += `**Similarity:** ${pct(similarity)}\n`;
-                }
-                for (const f of files) {
-                    result += `- **${f.file || f.name}**`;
-                    if (f.content)
-                        result += `\n  ${truncate(f.content, 80)}`;
+            schema: z.object({
+                text: z.string().describe("Text to extract learnings from"),
+                context: z.string().optional().describe("Additional context about the text"),
+                autoSave: z.boolean().optional().describe("Automatically save extracted learnings (default: false)"),
+                minConfidence: z.number().optional().describe("Minimum confidence threshold (0-1, default: 0.7)"),
+            }),
+            annotations: TOOL_ANNOTATIONS["extract_learnings"],
+            handler: async (args, ctx) => {
+                const { text, context, autoSave = false, minConfidence = 0.7 } = args;
+                const response = await ctx.api.post("/api/memory/extract", {
+                    projectName: ctx.projectName,
+                    text,
+                    context,
+                    autoSave,
+                    minConfidence,
+                });
+                const data = response.data;
+                let result = `## Extracted Learnings\n\n`;
+                result += `**Summary:** ${data.summary || "N/A"}\n\n`;
+                if (data.learnings && data.learnings.length > 0) {
+                    result += `### Learnings\n`;
+                    for (const l of data.learnings) {
+                        result += `- **[${l.type}]** (confidence: ${pct(l.confidence)}) ${l.content}\n`;
+                        if (l.tags && l.tags.length > 0) {
+                            result += `  Tags: ${l.tags.join(", ")}\n`;
+                        }
+                        if (l.reasoning) {
+                            result += `  *Reasoning: ${l.reasoning}*\n`;
+                        }
+                    }
                     result += "\n";
                 }
-                result += "\n";
-            }
-            return result;
-        },
-        recommend_similar: async (args, ctx) => {
-            const { positiveIds, negativeIds, limit = 5 } = args;
-            const response = await ctx.api.post("/api/recommend", {
-                collection: `${ctx.projectName}_codebase`,
-                positiveIds,
-                negativeIds,
-                limit,
-            });
-            const results = response.data.results || response.data;
-            if (!results || results.length === 0) {
-                return "No recommendations found.";
-            }
-            let result = `## Recommendations\n\n`;
-            for (const r of results) {
-                result += `- **${r.file || r.name}** (${pct(r.score || r.similarity)})`;
-                if (r.content)
-                    result += `\n  ${truncate(r.content, PREVIEW.SHORT)}`;
-                result += "\n";
-            }
-            return result;
-        },
-        extract_learnings: async (args, ctx) => {
-            const { text, context, autoSave = false, minConfidence = 0.7 } = args;
-            const response = await ctx.api.post("/api/memory/extract", {
-                projectName: ctx.projectName,
-                text,
-                context,
-                autoSave,
-                minConfidence,
-            });
-            const data = response.data;
-            let result = `## Extracted Learnings\n\n`;
-            result += `**Summary:** ${data.summary || "N/A"}\n\n`;
-            if (data.learnings && data.learnings.length > 0) {
-                result += `### Learnings\n`;
-                for (const l of data.learnings) {
-                    result += `- **[${l.type}]** (confidence: ${pct(l.confidence)}) ${l.content}\n`;
-                    if (l.tags && l.tags.length > 0) {
-                        result += `  Tags: ${l.tags.join(", ")}\n`;
+                if (data.entities) {
+                    if (data.entities.files && data.entities.files.length > 0) {
+                        result += `### Referenced Files\n`;
+                        for (const f of data.entities.files) {
+                            result += `- ${f}\n`;
+                        }
+                        result += "\n";
                     }
-                    if (l.reasoning) {
-                        result += `  *Reasoning: ${l.reasoning}*\n`;
+                    if (data.entities.functions && data.entities.functions.length > 0) {
+                        result += `### Referenced Functions\n`;
+                        for (const f of data.entities.functions) {
+                            result += `- ${f}\n`;
+                        }
+                        result += "\n";
                     }
-                }
-                result += "\n";
-            }
-            if (data.entities) {
-                if (data.entities.files && data.entities.files.length > 0) {
-                    result += `### Referenced Files\n`;
-                    for (const f of data.entities.files) {
-                        result += `- ${f}\n`;
+                    if (data.entities.concepts && data.entities.concepts.length > 0) {
+                        result += `### Concepts\n`;
+                        for (const c of data.entities.concepts) {
+                            result += `- ${c}\n`;
+                        }
+                        result += "\n";
                     }
-                    result += "\n";
                 }
-                if (data.entities.functions && data.entities.functions.length > 0) {
-                    result += `### Referenced Functions\n`;
-                    for (const f of data.entities.functions) {
-                        result += `- ${f}\n`;
-                    }
-                    result += "\n";
+                if (data.savedCount !== undefined) {
+                    result += `**Saved:** ${data.savedCount} learnings\n`;
                 }
-                if (data.entities.concepts && data.entities.concepts.length > 0) {
-                    result += `### Concepts\n`;
-                    for (const c of data.entities.concepts) {
-                        result += `- ${c}\n`;
-                    }
-                    result += "\n";
-                }
-            }
-            if (data.savedCount !== undefined) {
-                result += `**Saved:** ${data.savedCount} learnings\n`;
-            }
-            return result;
+                return result;
+            },
         },
-    };
-    return { tools, handlers };
+    ];
 }

package/dist/tools/confluence.d.ts

@@ -2,8 +2,8 @@
  * Confluence tools module - search, index, status, and space listing
  * for Confluence integration.
  */
-import type { ToolModule } from "../types.js";
+import type { ToolSpec } from "../types.js";
 /**
  * Create the Confluence tools module with project-specific descriptions.
  */
-export declare function createConfluenceTools(projectName: string): ToolModule;
+export declare function createConfluenceTools(projectName: string): ToolSpec[];

package/dist/tools/confluence.js

@@ -3,145 +3,109 @@
  * for Confluence integration.
  */
 import { truncate, pct } from "../formatters.js";
+import { z } from "zod";
+import { TOOL_ANNOTATIONS } from "../annotations.js";
 /**
  * Create the Confluence tools module with project-specific descriptions.
  */
 export function createConfluenceTools(projectName) {
-    const tools = [
+    return [
         {
             name: "search_confluence",
             description: `Search indexed Confluence documentation for ${projectName}. Returns relevant pages with content snippets.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    query: {
-                        type: "string",
-                        description: "Search query for Confluence content",
-                    },
-                    limit: {
-                        type: "number",
-                        description: "Max results (default: 5)",
-                        default: 5,
-                    },
-                    spaceKey: {
-                        type: "string",
-                        description: "Filter by Confluence space key",
-                    },
-                },
-                required: ["query"],
+            schema: z.object({
+                query: z.string().describe("Search query for Confluence content"),
+                limit: z.number().optional().describe("Max results (default: 5)"),
+                spaceKey: z.string().optional().describe("Filter by Confluence space key"),
+            }),
+            annotations: TOOL_ANNOTATIONS["search_confluence"],
+            handler: async (args, ctx) => {
+                const { query, limit = 5, spaceKey } = args;
+                const response = await ctx.api.post("/api/search", {
+                    collection: `${ctx.collectionPrefix}confluence`,
+                    query,
+                    limit,
+                    filters: spaceKey ? { spaceKey } : undefined,
+                });
+                const results = response.data.results;
+                if (!results || results.length === 0) {
+                    return "No Confluence results found.";
+                }
+                return results
+                    .map((r) => `### ${r.title || r.file || "Untitled"}\n` +
+                    `**Score:** ${pct(r.score)}` +
+                    (r.spaceKey ? ` | **Space:** ${r.spaceKey}` : "") +
+                    (r.url ? ` | [View](${r.url})` : "") +
+                    `\n\n${truncate(r.content || "", 600)}`)
+                    .join("\n\n---\n\n");
             },
         },
         {
             name: "index_confluence",
             description: `Index Confluence spaces/pages for ${projectName}. Requires Confluence credentials in RAG API.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    spaceKeys: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Specific space keys to index (indexes all accessible if empty)",
-                    },
-                    labels: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Filter pages by labels",
-                    },
-                    maxPages: {
-                        type: "number",
-                        description: "Maximum pages to index (default: 500)",
-                        default: 500,
-                    },
-                    force: {
-                        type: "boolean",
-                        description: "Force re-index even if already indexed",
-                        default: false,
-                    },
-                },
+            schema: z.object({
+                spaceKeys: z.array(z.string()).optional().describe("Specific space keys to index (indexes all accessible if empty)"),
+                labels: z.array(z.string()).optional().describe("Filter pages by labels"),
+                maxPages: z.number().optional().describe("Maximum pages to index (default: 500)"),
+                force: z.boolean().optional().describe("Force re-index even if already indexed"),
+            }),
+            annotations: TOOL_ANNOTATIONS["index_confluence"],
+            handler: async (args, ctx) => {
+                const { spaceKeys, labels, maxPages = 500, force = false } = args;
+                const response = await ctx.api.post("/api/index/confluence", {
+                    projectName: ctx.projectName,
+                    spaceKeys,
+                    labels,
+                    maxPages,
+                    force,
+                });
+                const data = response.data;
+                let result = `## Confluence Indexing\n\n`;
+                result += `- **Status:** ${data.status || "started"}\n`;
+                result += `- **Collection:** ${data.collection || `${ctx.collectionPrefix}confluence`}\n`;
+                result += `- **Options:**\n`;
+                if (spaceKeys && spaceKeys.length > 0) {
+                    result += `  - Spaces: ${spaceKeys.join(", ")}\n`;
+                }
+                if (labels && labels.length > 0) {
+                    result += `  - Labels: ${labels.join(", ")}\n`;
+                }
+                result += `  - Max Pages: ${maxPages}\n`;
+                result += `  - Force: ${force}\n`;
+                return result;
             },
         },
         {
             name: "get_confluence_status",
             description: "Check if Confluence integration is configured and available.",
-            inputSchema: {
-                type: "object",
-                properties: {},
+            schema: z.object({}),
+            annotations: TOOL_ANNOTATIONS["get_confluence_status"],
+            handler: async (_args, ctx) => {
+                const response = await ctx.api.get("/api/confluence/status");
+                const data = response.data;
+                let result = `## Confluence Status\n\n`;
+                result += `- **Configured:** ${data.configured ? "Yes" : "No"}\n`;
+                result += `- **Message:** ${data.message || "N/A"}\n`;
+                return result;
             },
         },
         {
             name: "list_confluence_spaces",
             description: "List available Confluence spaces that can be indexed.",
-            inputSchema: {
-                type: "object",
-                properties: {},
+            schema: z.object({}),
+            annotations: TOOL_ANNOTATIONS["list_confluence_spaces"],
+            handler: async (_args, ctx) => {
+                const response = await ctx.api.get("/api/confluence/spaces");
+                const spaces = response.data.spaces || response.data;
+                if (!spaces || spaces.length === 0) {
+                    return "No Confluence spaces available.";
+                }
+                let result = `## Confluence Spaces\n\n`;
+                for (const s of spaces) {
+                    result += `- **${s.key}** - ${s.name} (${s.type || "global"})\n`;
+                }
+                return result;
             },
         },
     ];
-    const handlers = {
-        search_confluence: async (args, ctx) => {
-            const { query, limit = 5, spaceKey } = args;
-            const response = await ctx.api.post("/api/search", {
-                collection: `${ctx.collectionPrefix}confluence`,
-                query,
-                limit,
-                filters: spaceKey ? { spaceKey } : undefined,
-            });
-            const results = response.data.results;
-            if (!results || results.length === 0) {
-                return "No Confluence results found.";
-            }
-            return results
-                .map((r) => `### ${r.title || r.file || "Untitled"}\n` +
-                `**Score:** ${pct(r.score)}` +
-                (r.spaceKey ? ` | **Space:** ${r.spaceKey}` : "") +
-                (r.url ? ` | [View](${r.url})` : "") +
-                `\n\n${truncate(r.content || "", 600)}`)
-                .join("\n\n---\n\n");
-        },
-        index_confluence: async (args, ctx) => {
-            const { spaceKeys, labels, maxPages = 500, force = false } = args;
-            const response = await ctx.api.post("/api/index/confluence", {
-                projectName: ctx.projectName,
-                spaceKeys,
-                labels,
-                maxPages,
-                force,
-            });
-            const data = response.data;
-            let result = `## Confluence Indexing\n\n`;
-            result += `- **Status:** ${data.status || "started"}\n`;
-            result += `- **Collection:** ${data.collection || `${ctx.collectionPrefix}confluence`}\n`;
-            result += `- **Options:**\n`;
-            if (spaceKeys && spaceKeys.length > 0) {
-                result += `  - Spaces: ${spaceKeys.join(", ")}\n`;
-            }
-            if (labels && labels.length > 0) {
-                result += `  - Labels: ${labels.join(", ")}\n`;
-            }
-            result += `  - Max Pages: ${maxPages}\n`;
-            result += `  - Force: ${force}\n`;
-            return result;
-        },
-        get_confluence_status: async (_args, ctx) => {
-            const response = await ctx.api.get("/api/confluence/status");
-            const data = response.data;
-            let result = `## Confluence Status\n\n`;
-            result += `- **Configured:** ${data.configured ? "Yes" : "No"}\n`;
-            result += `- **Message:** ${data.message || "N/A"}\n`;
-            return result;
-        },
-        list_confluence_spaces: async (_args, ctx) => {
-            const response = await ctx.api.get("/api/confluence/spaces");
-            const spaces = response.data.spaces || response.data;
-            if (!spaces || spaces.length === 0) {
-                return "No Confluence spaces available.";
-            }
-            let result = `## Confluence Spaces\n\n`;
-            for (const s of spaces) {
-                result += `- **${s.key}** - ${s.name} (${s.type || "global"})\n`;
-            }
-            return result;
-        },
-    };
-    return { tools, handlers };
 }

package/dist/tools/database.d.ts

@@ -1,5 +1,5 @@
 /**
  * Database Tools - Schema documentation, rules, enums, and validation.
  */
-import type { ToolModule } from "../types.js";
-export declare function createDatabaseTools(projectName: string): ToolModule;
+import type { ToolSpec } from "../types.js";
+export declare function createDatabaseTools(projectName: string): ToolSpec[];