purecontext-mcp 1.1.7 → 1.2.0

package/dist/server/tools/get-complexity-hotspots.d.ts

@@ -0,0 +1,50 @@
+/**
+ * get-complexity-hotspots.ts
+ *
+ * MCP tool: get_complexity_hotspots
+ *
+ * Aggregates per-symbol complexity metrics to the file level and returns a
+ * ranked list of the files with the highest complexity concentration. Use this
+ * to answer "where should I focus refactoring effort?" — it surfaces files that
+ * contain many complex symbols, deeply nested logic, or high average cyclomatic
+ * complexity.
+ *
+ * Differs from related tools:
+ *   get_quality_metrics    — per-symbol composite score, not file-level aggregation
+ *   search_by_complexity   — threshold/range filter for individual symbols
+ *   get_complexity_hotspots — file-level aggregation + hotspot ranking
+ *
+ * Designed for:
+ *   - Identifying which files to tackle first in a refactoring sprint
+ *   - Generating a "complexity heat map" for an architecture review
+ *   - Spotting files that are growing too complex before they become unmaintainable
+ */
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare const name = "get_complexity_hotspots";
+export declare const description: string;
+export declare const inputSchema: {
+    repoId: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    topN: z.ZodOptional<z.ZodNumber>;
+    minComplexity: z.ZodOptional<z.ZodNumber>;
+    metric: z.ZodOptional<z.ZodEnum<{
+        size: "size";
+        complexity: "complexity";
+        nesting: "nesting";
+        cognitive: "cognitive";
+        composite: "composite";
+    }>>;
+    includeSymbols: z.ZodOptional<z.ZodBoolean>;
+    symbolLimit: z.ZodOptional<z.ZodNumber>;
+};
+export declare function handler(args: {
+    repoId: string;
+    scope?: string;
+    topN?: number;
+    minComplexity?: number;
+    metric?: 'complexity' | 'cognitive' | 'size' | 'nesting' | 'composite';
+    includeSymbols?: boolean;
+    symbolLimit?: number;
+}): Promise<CallToolResult>;
+//# sourceMappingURL=get-complexity-hotspots.d.ts.map

package/dist/server/tools/get-complexity-hotspots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-complexity-hotspots.d.ts","sourceRoot":"","sources":["../../../src/server/tools/get-complexity-hotspots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAGzE,eAAO,MAAM,IAAI,4BAA4B,CAAC;AAE9C,eAAO,MAAM,WAAW,QAWiD,CAAC;AAE1E,eAAO,MAAM,WAAW;;;;;;;;;;;;;;CA2CvB,CAAC;AA4EF,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,YAAY,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC;IACvE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqO1B"}

package/dist/server/tools/get-complexity-hotspots.js

@@ -0,0 +1,282 @@
+/**
+ * get-complexity-hotspots.ts
+ *
+ * MCP tool: get_complexity_hotspots
+ *
+ * Aggregates per-symbol complexity metrics to the file level and returns a
+ * ranked list of the files with the highest complexity concentration. Use this
+ * to answer "where should I focus refactoring effort?" — it surfaces files that
+ * contain many complex symbols, deeply nested logic, or high average cyclomatic
+ * complexity.
+ *
+ * Differs from related tools:
+ *   get_quality_metrics    — per-symbol composite score, not file-level aggregation
+ *   search_by_complexity   — threshold/range filter for individual symbols
+ *   get_complexity_hotspots — file-level aggregation + hotspot ranking
+ *
+ * Designed for:
+ *   - Identifying which files to tackle first in a refactoring sprint
+ *   - Generating a "complexity heat map" for an architecture review
+ *   - Spotting files that are growing too complex before they become unmaintainable
+ */
+import { z } from 'zod';
+import { openDatabase, getRepo } from '../../core/db/schema.js';
+import { buildMeta } from './_meta.js';
+export const name = 'get_complexity_hotspots';
+export const description = 'Aggregate per-symbol complexity metrics to the file level and return a ranked list ' +
+    'of the files with the highest complexity concentration. Use this to answer ' +
+    '"where should I focus refactoring effort?" — it surfaces files with many complex ' +
+    'symbols, deeply nested logic, or high average cyclomatic complexity. ' +
+    'Returns a hotspot score (0–100) per file, plus the top offending symbols within ' +
+    'each hotspot file.' +
+    '\n\nDiffers from related tools:' +
+    '\n  get_quality_metrics    — per-symbol composite score ranked by worst symbols' +
+    '\n  search_by_complexity   — threshold/range filtering of individual symbols' +
+    '\n  get_debt_report        — broader tech-debt summary including comment density' +
+    '\n  health_radar           — multi-dimensional health scores per file';
+export const inputSchema = {
+    repoId: z.string().describe('Repository ID returned by index_folder or list_repos'),
+    scope: z
+        .string()
+        .optional()
+        .describe('Restrict to a directory prefix (e.g. "src/core/"). ' +
+        'Omit to analyse the entire repo.'),
+    topN: z
+        .number().int().min(1).max(100)
+        .optional()
+        .describe('Number of hotspot files to return (default 10)'),
+    minComplexity: z
+        .number().int().min(1)
+        .optional()
+        .describe('Minimum cyclomatic complexity for a symbol to count as "complex" ' +
+        'when computing the complex-symbol density for each file (default 5).'),
+    metric: z
+        .enum(['complexity', 'cognitive', 'size', 'nesting', 'composite'])
+        .optional()
+        .describe('Primary metric used to rank hotspot files. ' +
+        '"complexity" = avg cyclomatic (default), ' +
+        '"cognitive" = avg cognitive complexity, ' +
+        '"size" = total line count, ' +
+        '"nesting" = max nesting depth, ' +
+        '"composite" = weighted hotspot score.'),
+    includeSymbols: z
+        .boolean()
+        .optional()
+        .describe('Include the top offending symbols within each hotspot file (default true). ' +
+        'Set false for a compact file-level-only response.'),
+    symbolLimit: z
+        .number().int().min(1).max(20)
+        .optional()
+        .describe('Max number of symbols to include per hotspot file (default 5). ' +
+        'Symbols are ranked by cyclomatic complexity descending.'),
+};
+// ─── Hotspot score ────────────────────────────────────────────────────────────
+/**
+ * Composite hotspot score 0–100.
+ *
+ * Weights (must sum to 1.0):
+ *   avg cyclomatic  (35%) — ceiling at 30 (avg CC ≥ 30 → max contribution)
+ *   max cyclomatic  (30%) — ceiling at 50
+ *   complex density (20%) — complexSymbols / symbolCount, ceiling 1.0
+ *   max nesting     (15%) — ceiling at 10 levels
+ */
+function computeHotspotScore(stats) {
+    const avgCC = Math.min(stats.avgCyclomaticComplexity / 30, 1) * 100;
+    const maxCC = Math.min(stats.maxCyclomaticComplexity / 50, 1) * 100;
+    const density = stats.symbolCount > 0
+        ? Math.min(stats.complexSymbolCount / stats.symbolCount, 1) * 100
+        : 0;
+    const nesting = Math.min(stats.maxNestingDepth / 10, 1) * 100;
+    return Math.round(avgCC * 0.35 + maxCC * 0.30 + density * 0.20 + nesting * 0.15);
+}
+// ─── Handler ──────────────────────────────────────────────────────────────────
+export async function handler(args) {
+    const t0 = Date.now();
+    const { repoId, topN = 10, minComplexity = 5, metric = 'complexity', includeSymbols = true, symbolLimit = 5, } = args;
+    const db = openDatabase(repoId);
+    try {
+        // ── Validate repo exists ───────────────────────────────────────────────────
+        const repo = getRepo(db, repoId);
+        if (!repo) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: `Repo "${repoId}" not found. Run index_folder first.` }),
+                    }],
+                isError: true,
+            };
+        }
+        // ── Fetch all measurable symbols ───────────────────────────────────────────
+        const conditions = [
+            'repo_id = @repoId',
+            'line_count IS NOT NULL',
+        ];
+        const params = { repoId };
+        if (args.scope) {
+            conditions.push('(file_path = @scope OR file_path LIKE @scopePrefix)');
+            params['scope'] = args.scope;
+            params['scopePrefix'] = args.scope.endsWith('/')
+                ? `${args.scope}%`
+                : `${args.scope}/%`;
+        }
+        const sql = `
+      SELECT id, name, kind, file_path, start_byte, signature, summary,
+             COALESCE(line_count, 0)            AS line_count,
+             COALESCE(cyclomatic_complexity, 1)  AS cyclomatic_complexity,
+             COALESCE(cognitive_complexity, 0)   AS cognitive_complexity,
+             COALESCE(nesting_depth, 0)          AS nesting_depth,
+             COALESCE(param_count, 0)            AS param_count,
+             COALESCE(return_count, 0)           AS return_count
+      FROM symbols
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY file_path ASC, cyclomatic_complexity DESC
+    `;
+        const rows = db.prepare(sql).all(params);
+        if (rows.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            repoId,
+                            totalFilesAnalyzed: 0,
+                            hotspots: [],
+                            summary: {
+                                hotspotFileCount: 0,
+                                avgHotspotScore: 0,
+                                totalComplexSymbols: 0,
+                                totalSymbolsAnalyzed: 0,
+                            },
+                            _tokenEstimate: 10,
+                            _meta: buildMeta({ timingMs: Date.now() - t0 }),
+                        }),
+                    }],
+            };
+        }
+        // ── Group symbols by file ──────────────────────────────────────────────────
+        const fileMap = new Map();
+        for (const row of rows) {
+            const list = fileMap.get(row.file_path) ?? [];
+            list.push(row);
+            fileMap.set(row.file_path, list);
+        }
+        // ── Compute per-file stats ─────────────────────────────────────────────────
+        const fileStatsList = [];
+        for (const [filePath, syms] of fileMap) {
+            const symbolCount = syms.length;
+            const complexSymbolCount = syms.filter((s) => s.cyclomatic_complexity >= minComplexity).length;
+            const avgCC = syms.reduce((s, r) => s + r.cyclomatic_complexity, 0) / symbolCount;
+            const maxCC = Math.max(...syms.map((r) => r.cyclomatic_complexity));
+            const avgCog = syms.reduce((s, r) => s + r.cognitive_complexity, 0) / symbolCount;
+            const maxCog = Math.max(...syms.map((r) => r.cognitive_complexity));
+            const avgND = syms.reduce((s, r) => s + r.nesting_depth, 0) / symbolCount;
+            const maxND = Math.max(...syms.map((r) => r.nesting_depth));
+            const avgLC = syms.reduce((s, r) => s + r.line_count, 0) / symbolCount;
+            const totalLC = syms.reduce((s, r) => s + r.line_count, 0);
+            const statsWithoutScore = {
+                filePath,
+                symbolCount,
+                complexSymbolCount,
+                avgCyclomaticComplexity: Math.round(avgCC * 10) / 10,
+                maxCyclomaticComplexity: maxCC,
+                avgCognitiveComplexity: Math.round(avgCog * 10) / 10,
+                maxCognitiveComplexity: maxCog,
+                avgNestingDepth: Math.round(avgND * 10) / 10,
+                maxNestingDepth: maxND,
+                avgLineCount: Math.round(avgLC * 10) / 10,
+                totalLineCount: totalLC,
+            };
+            fileStatsList.push({
+                ...statsWithoutScore,
+                hotspotScore: computeHotspotScore(statsWithoutScore),
+            });
+        }
+        // ── Sort by chosen metric ──────────────────────────────────────────────────
+        fileStatsList.sort((a, b) => {
+            switch (metric) {
+                case 'cognitive': return b.avgCognitiveComplexity - a.avgCognitiveComplexity;
+                case 'size': return b.totalLineCount - a.totalLineCount;
+                case 'nesting': return b.maxNestingDepth - a.maxNestingDepth;
+                case 'composite': return b.hotspotScore - a.hotspotScore;
+                case 'complexity':
+                default: return b.avgCyclomaticComplexity - a.avgCyclomaticComplexity;
+            }
+        });
+        const topFiles = fileStatsList.slice(0, topN);
+        const totalFilesAnalyzed = fileStatsList.length;
+        // ── Resolve start lines and attach top symbols ────────────────────────────
+        const hotspots = [];
+        for (const stats of topFiles) {
+            const hotspot = { ...stats };
+            if (includeSymbols) {
+                const syms = fileMap.get(stats.filePath) ?? [];
+                // Resolve start lines from file content (best-effort)
+                const fileRow = db.prepare('SELECT raw_content FROM files WHERE repo_id = ? AND path = ?').get(repoId, stats.filePath);
+                const lineOf = (startByte) => {
+                    if (fileRow?.raw_content) {
+                        const slice = fileRow.raw_content.slice(0, Math.min(startByte, fileRow.raw_content.length));
+                        let line = 1;
+                        for (let i = 0; i < slice.length; i++) {
+                            if (slice[i] === 0x0a)
+                                line++;
+                        }
+                        return line;
+                    }
+                    return Math.max(1, Math.floor(startByte / 80) + 1);
+                };
+                // Top symbols ranked by cyclomatic complexity
+                const topSyms = [...syms]
+                    .sort((a, b) => b.cyclomatic_complexity - a.cyclomatic_complexity)
+                    .slice(0, symbolLimit);
+                hotspot.topSymbols = topSyms.map((s) => ({
+                    symbolId: s.id,
+                    name: s.name,
+                    kind: s.kind,
+                    startLine: lineOf(s.start_byte),
+                    signature: s.signature,
+                    summary: s.summary,
+                    cyclomaticComplexity: s.cyclomatic_complexity,
+                    cognitiveComplexity: s.cognitive_complexity,
+                    lineCount: s.line_count,
+                    nestingDepth: s.nesting_depth,
+                }));
+            }
+            hotspots.push(hotspot);
+        }
+        // ── Summary stats ─────────────────────────────────────────────────────────
+        const avgHotspotScore = topFiles.length > 0
+            ? Math.round(topFiles.reduce((s, f) => s + f.hotspotScore, 0) / topFiles.length)
+            : 0;
+        const totalComplexSymbols = fileStatsList.reduce((s, f) => s + f.complexSymbolCount, 0);
+        const totalSymbolsAnalyzed = rows.length;
+        // ── Token estimate ─────────────────────────────────────────────────────────
+        const responseBytes = hotspots.reduce((sum, h) => {
+            const symBytes = (h.topSymbols ?? []).reduce((s, sym) => s + sym.signature.length + sym.summary.length + 80, 0);
+            return sum + h.filePath.length + 150 + symBytes;
+        }, 0);
+        const tokenEstimate = Math.ceil(responseBytes / 4);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        repoId,
+                        totalFilesAnalyzed,
+                        rankedBy: metric,
+                        minComplexity,
+                        hotspots,
+                        summary: {
+                            hotspotFileCount: topFiles.length,
+                            avgHotspotScore,
+                            totalComplexSymbols,
+                            totalSymbolsAnalyzed,
+                        },
+                        _tokenEstimate: tokenEstimate,
+                        _meta: buildMeta({ timingMs: Date.now() - t0 }),
+                    }, null, 2),
+                }],
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=get-complexity-hotspots.js.map

package/dist/server/tools/get-complexity-hotspots.js.map

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

package/dist/server/tools/get-coupling-map.d.ts

@@ -0,0 +1,39 @@
+/**
+ * get-coupling-map.ts
+ *
+ * MCP tool: get_coupling_map
+ *
+ * Return per-file coupling scores with the named files each file depends on,
+ * going beyond the aggregate score in get_quality_metrics to show exactly who
+ * depends on whom.
+ *
+ * Metrics (Martin's instability metric):
+ *   efferentCoupling (Ce) — files this file imports
+ *   afferentCoupling (Ca) — files that import this file
+ *   instability = Ce / (Ce + Ca)
+ *     0 = maximally stable (nothing this file depends on can break it)
+ *     1 = maximally unstable (leaf node — safe to change without ripple effects)
+ */
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare const name = "get_coupling_map";
+export declare const description: string;
+export declare const inputSchema: {
+    repoId: z.ZodString;
+    filePath: z.ZodOptional<z.ZodString>;
+    topN: z.ZodOptional<z.ZodNumber>;
+    minScore: z.ZodOptional<z.ZodNumber>;
+    direction: z.ZodOptional<z.ZodEnum<{
+        both: "both";
+        efferent: "efferent";
+        afferent: "afferent";
+    }>>;
+};
+export declare function handler(args: {
+    repoId: string;
+    filePath?: string;
+    topN?: number;
+    minScore?: number;
+    direction?: 'efferent' | 'afferent' | 'both';
+}): Promise<CallToolResult>;
+//# sourceMappingURL=get-coupling-map.d.ts.map

package/dist/server/tools/get-coupling-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-coupling-map.d.ts","sourceRoot":"","sources":["../../../src/server/tools/get-coupling-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,eAAO,MAAM,IAAI,qBAAqB,CAAC;AAEvC,eAAO,MAAM,WAAW,QAOoE,CAAC;AAE7F,eAAO,MAAM,WAAW;;;;;;;;;;CAgCvB,CAAC;AAsBF,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;CAC9C,GAAG,OAAO,CAAC,cAAc,CAAC,CA4D1B"}

package/dist/server/tools/get-coupling-map.js

@@ -0,0 +1,107 @@
+/**
+ * get-coupling-map.ts
+ *
+ * MCP tool: get_coupling_map
+ *
+ * Return per-file coupling scores with the named files each file depends on,
+ * going beyond the aggregate score in get_quality_metrics to show exactly who
+ * depends on whom.
+ *
+ * Metrics (Martin's instability metric):
+ *   efferentCoupling (Ce) — files this file imports
+ *   afferentCoupling (Ca) — files that import this file
+ *   instability = Ce / (Ce + Ca)
+ *     0 = maximally stable (nothing this file depends on can break it)
+ *     1 = maximally unstable (leaf node — safe to change without ripple effects)
+ */
+import { z } from 'zod';
+import { openDatabase, getRepo } from '../../core/db/schema.js';
+import { getCouplingMap } from '../../core/db/dep-store.js';
+import { buildMeta } from './_meta.js';
+export const name = 'get_coupling_map';
+export const description = 'Return per-file coupling scores showing exactly which files each file depends on and ' +
+    'which files depend on it. Goes beyond get_quality_metrics to expose the full dependency ' +
+    'lists, not just aggregate counts. Uses Martin\'s instability metric: ' +
+    'instability = efferentCoupling / (efferentCoupling + afferentCoupling). ' +
+    'A score near 0 means the file is a stable hub (risky to change). ' +
+    'A score near 1 means it is a leaf (safe to change). ' +
+    'Use topN to surface the most coupled files in the repo, or filePath to inspect one file.';
+export const inputSchema = {
+    repoId: z.string().describe('Repo ID from index_folder or resolve_repo'),
+    filePath: z
+        .string()
+        .optional()
+        .describe('Scope to a single file (relative to repo root). ' +
+        'If omitted, returns the top-N most coupled files across the whole repo.'),
+    topN: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe('Maximum number of files to return when filePath is omitted (default 20)'),
+    minScore: z
+        .number()
+        .min(0)
+        .optional()
+        .describe('Only include files whose total coupling (efferent + afferent) is ≥ this value. ' +
+        'Use to focus on highly coupled files only.'),
+    direction: z
+        .enum(['efferent', 'afferent', 'both'])
+        .optional()
+        .describe('"efferent" — show only outgoing deps (files this file imports); ' +
+        '"afferent" — show only incoming deps (files that import this file); ' +
+        '"both" (default) — show both. Restricting direction reduces response size.'),
+};
+// ─── Handler ──────────────────────────────────────────────────────────────────
+export async function handler(args) {
+    const t0 = Date.now();
+    const { repoId, filePath, topN = 20, minScore, direction = 'both' } = args;
+    const db = openDatabase(repoId);
+    try {
+        const repo = getRepo(db, repoId);
+        if (!repo) {
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify({ error: `Repo "${repoId}" not found. Run index_folder first.` }) },
+                ],
+                isError: true,
+            };
+        }
+        let rows = getCouplingMap(db, repoId, filePath);
+        // Apply minScore filter (total coupling)
+        if (minScore !== undefined) {
+            rows = rows.filter((r) => r.efferentCoupling + r.afferentCoupling >= minScore);
+        }
+        // Sort by total coupling descending, then by filePath for stable ordering
+        rows.sort((a, b) => b.efferentCoupling + b.afferentCoupling - (a.efferentCoupling + a.afferentCoupling) ||
+            a.filePath.localeCompare(b.filePath));
+        // Apply topN only when not scoped to a single file
+        if (!filePath) {
+            rows = rows.slice(0, topN);
+        }
+        // Strip dep lists for the omitted direction to save tokens
+        const files = rows.map((r) => ({
+            filePath: r.filePath,
+            efferentCoupling: r.efferentCoupling,
+            afferentCoupling: r.afferentCoupling,
+            instability: r.instability,
+            efferentDeps: direction !== 'afferent' ? r.efferentDeps : [],
+            afferentDeps: direction !== 'efferent' ? r.afferentDeps : [],
+        }));
+        const responseText = JSON.stringify(files);
+        const output = {
+            files,
+            totalFiles: files.length,
+            _tokenEstimate: Math.ceil(responseText.length / 4),
+            _meta: buildMeta({ timingMs: Date.now() - t0 }),
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(output, null, 2) }],
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=get-coupling-map.js.map

package/dist/server/tools/get-coupling-map.js.map

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

package/dist/server/tools/get-debt-report.d.ts

@@ -0,0 +1,44 @@
+/**
+ * get-debt-report.ts
+ *
+ * MCP tool: get_debt_report
+ *
+ * Generate a comprehensive technical debt report for an indexed repo.
+ * Aggregates signals from four debt dimensions:
+ *
+ *   complexity    — cyclomatic complexity, nesting depth, function length
+ *   structural    — circular dependencies, high coupling, layer violations
+ *   maintainability — dead code, god classes, long parameter lists
+ *   volatility    — churn hotspots (requires git metadata)
+ *
+ * Produces:
+ *   • An overall debt score (0–100, higher = more debt) with letter grade
+ *   • Per-category scores with top issues
+ *   • Top N debt files ranked by combined score across all dimensions
+ *   • Prioritized action items sorted by estimated ROI
+ *
+ * All queries are read-only against the symbol and dep_edges tables — no
+ * sub-tool calls. This keeps latency low and error handling simple.
+ */
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare const name = "get_debt_report";
+export declare const description: string;
+export declare const inputSchema: {
+    repoId: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    topN: z.ZodOptional<z.ZodNumber>;
+    includeChurn: z.ZodOptional<z.ZodBoolean>;
+    format: z.ZodOptional<z.ZodEnum<{
+        summary: "summary";
+        detailed: "detailed";
+    }>>;
+};
+export declare function handler(args: {
+    repoId: string;
+    scope?: string;
+    topN?: number;
+    includeChurn?: boolean;
+    format?: 'summary' | 'detailed';
+}): Promise<CallToolResult>;
+//# sourceMappingURL=get-debt-report.d.ts.map

package/dist/server/tools/get-debt-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-debt-report.d.ts","sourceRoot":"","sources":["../../../src/server/tools/get-debt-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAKzE,eAAO,MAAM,IAAI,oBAAoB,CAAC;AAEtC,eAAO,MAAM,WAAW,QAKoD,CAAC;AAE7E,eAAO,MAAM,WAAW;;;;;;;;;CA0BvB,CAAC;AA8oBF,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;CACjC,GAAG,OAAO,CAAC,cAAc,CAAC,CAuJ1B"}