purecontext-mcp 1.1.7 → 1.2.0

package/dist/server/tools/check-rename-safe.d.ts

@@ -0,0 +1,48 @@
+/**
+ * check-rename-safe.ts
+ *
+ * MCP tool: check_rename_safe
+ *
+ * Pre-flight check for renaming a symbol. Returns a binary verdict, all
+ * affected files, and the specific lines that will need updating — so an
+ * agent can decide whether to proceed without manually inspecting raw
+ * reference lists.
+ *
+ * Safety rules:
+ *   safe: false  — if conflicts exist (newName already present in the same file)
+ *   safe: false  — if any reference is a string-literal (runtime string that
+ *                  won't be fixed by a text rename, requires human judgment)
+ *   safe: true   — all other cases (comment references are included but not
+ *                  blockers)
+ *
+ * changeType detection (in priority order):
+ *   'comment'        — line starts with // or * (JSDoc)
+ *   'import'         — line contains the `import` keyword
+ *   'string-literal' — symbol name appears inside quote characters
+ *   'type-reference' — line contains `type` or `interface` keyword
+ *   'call'           — default
+ */
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare const name = "check_rename_safe";
+export declare const description: string;
+export declare const inputSchema: {
+    repoId: z.ZodString;
+    symbolId: z.ZodString;
+    newName: z.ZodString;
+    checkConflicts: z.ZodOptional<z.ZodBoolean>;
+};
+export interface AffectedSite {
+    filePath: string;
+    line: number;
+    column: number;
+    context: string;
+    changeType: 'call' | 'import' | 'type-reference' | 'string-literal' | 'comment';
+}
+export declare function handler(args: {
+    repoId: string;
+    symbolId: string;
+    newName: string;
+    checkConflicts?: boolean;
+}): Promise<CallToolResult>;
+//# sourceMappingURL=check-rename-safe.d.ts.map

package/dist/server/tools/check-rename-safe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-rename-safe.d.ts","sourceRoot":"","sources":["../../../src/server/tools/check-rename-safe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,eAAO,MAAM,IAAI,sBAAsB,CAAC;AAExC,eAAO,MAAM,WAAW,QAK0B,CAAC;AAEnD,eAAO,MAAM,WAAW;;;;;CAWvB,CAAC;AAIF,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,SAAS,CAAC;CACjF;AAyDD,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,OAAO,CAAC,cAAc,CAAC,CA6J1B"}

package/dist/server/tools/check-rename-safe.js

@@ -0,0 +1,218 @@
+/**
+ * check-rename-safe.ts
+ *
+ * MCP tool: check_rename_safe
+ *
+ * Pre-flight check for renaming a symbol. Returns a binary verdict, all
+ * affected files, and the specific lines that will need updating — so an
+ * agent can decide whether to proceed without manually inspecting raw
+ * reference lists.
+ *
+ * Safety rules:
+ *   safe: false  — if conflicts exist (newName already present in the same file)
+ *   safe: false  — if any reference is a string-literal (runtime string that
+ *                  won't be fixed by a text rename, requires human judgment)
+ *   safe: true   — all other cases (comment references are included but not
+ *                  blockers)
+ *
+ * changeType detection (in priority order):
+ *   'comment'        — line starts with // or * (JSDoc)
+ *   'import'         — line contains the `import` keyword
+ *   'string-literal' — symbol name appears inside quote characters
+ *   'type-reference' — line contains `type` or `interface` keyword
+ *   'call'           — default
+ */
+import { z } from 'zod';
+import { openDatabase, getRepo } from '../../core/db/schema.js';
+import { getSymbolById } from '../../core/db/symbol-store.js';
+import { getAllFilesWithContent } from '../../core/db/file-store.js';
+import { buildMeta } from './_meta.js';
+export const name = 'check_rename_safe';
+export const description = 'Pre-flight check for renaming a symbol. Returns a verdict, all affected files, ' +
+    'and the specific lines that will need updating. ' +
+    'safe: false when the new name conflicts with an existing symbol or when string-literal ' +
+    'references exist that require manual updates. ' +
+    'Use search_symbols to find the symbolId first.';
+export const inputSchema = {
+    repoId: z.string().describe('Repo ID from index_folder or resolve_repo'),
+    symbolId: z.string().describe('Symbol ID of the symbol to rename'),
+    newName: z.string().min(1).describe('Proposed new name for the symbol'),
+    checkConflicts: z
+        .boolean()
+        .optional()
+        .describe('Check if newName already exists in the same file (default true). ' +
+        'Set false to skip conflict detection for speed.'),
+};
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Classify a reference line into a change type.
+ * Checked in priority order so that the most specific match wins.
+ */
+function detectChangeType(lineContent, symbolName) {
+    const trimmed = lineContent.trim();
+    // Comment: line starts with // or * (JSDoc block) or /*
+    if (/^(\/\/|\*|\/\*)/.test(trimmed)) {
+        return 'comment';
+    }
+    // Import statement
+    if (/\bimport\b/.test(trimmed)) {
+        return 'import';
+    }
+    // String literal: symbol name appears inside quote characters
+    const escaped = escapeRegex(symbolName);
+    if (new RegExp(`['"\`][^'"\`]*\\b${escaped}\\b[^'"\`]*['"\`]`).test(trimmed)) {
+        return 'string-literal';
+    }
+    // Type reference: `type` or `interface` keyword on this line
+    if (/\btype\b/.test(trimmed) || /\binterface\b/.test(trimmed)) {
+        return 'type-reference';
+    }
+    // Default: call / variable usage
+    return 'call';
+}
+// ─── Handler ──────────────────────────────────────────────────────────────────
+export async function handler(args) {
+    const t0 = Date.now();
+    const { repoId, symbolId, newName, checkConflicts = true } = 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,
+            };
+        }
+        const symbol = getSymbolById(db, repoId, symbolId);
+        if (!symbol) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `Symbol "${symbolId}" not found in repo "${repoId}".`,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // No-op: renaming to the same name is always safe
+        if (symbol.name === newName) {
+            const output = {
+                safe: true,
+                verdict: `Safe to rename: new name is the same as the current name (no-op).`,
+                symbolName: symbol.name,
+                newName,
+                conflicts: [],
+                affectedSites: [],
+                affectedFileCount: 0,
+                _tokenEstimate: 0,
+                _meta: buildMeta({ timingMs: Date.now() - t0 }),
+            };
+            return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+        }
+        // ── 1. Find all references ────────────────────────────────────────────────
+        const affectedSites = [];
+        const pattern = new RegExp(`\\b${escapeRegex(symbol.name)}\\b`);
+        // Definition file is excluded from reference scan (we don't list the
+        // declaration itself as an affected site — only call/import sites)
+        const definitionFile = symbol.filePath;
+        const files = getAllFilesWithContent(db, repoId);
+        for (const { path, rawContent } of files) {
+            if (!rawContent)
+                continue;
+            if (path === definitionFile)
+                continue;
+            const text = rawContent.toString('utf8');
+            const lines = text.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                if (!pattern.test(line))
+                    continue;
+                const match = pattern.exec(line);
+                const column = match ? match.index + 1 : 1; // 1-based
+                affectedSites.push({
+                    filePath: path,
+                    line: i + 1,
+                    column,
+                    context: line.length > 120 ? line.slice(0, 120) : line,
+                    changeType: detectChangeType(line, symbol.name),
+                });
+            }
+        }
+        // ── 2. Conflict detection ─────────────────────────────────────────────────
+        const conflicts = [];
+        if (checkConflicts) {
+            // Look for any symbol with newName in the same file as the declaration
+            const conflictRows = db
+                .prepare(`SELECT name, file_path, kind FROM symbols
+           WHERE repo_id = ? AND name = ? AND file_path = ?`)
+                .all(repoId, newName, definitionFile);
+            for (const row of conflictRows) {
+                conflicts.push(`${row.name} (${row.kind}) in ${row.file_path}`);
+            }
+        }
+        // ── 3. Compute verdict ────────────────────────────────────────────────────
+        const hasStringLiterals = affectedSites.some((s) => s.changeType === 'string-literal');
+        const safe = conflicts.length === 0 && !hasStringLiterals;
+        const uniqueFiles = new Set(affectedSites.map((s) => s.filePath));
+        const affectedFileCount = uniqueFiles.size;
+        const callCount = affectedSites.filter((s) => s.changeType === 'call').length;
+        const importCount = affectedSites.filter((s) => s.changeType === 'import').length;
+        const stringLitCount = affectedSites.filter((s) => s.changeType === 'string-literal').length;
+        const commentCount = affectedSites.filter((s) => s.changeType === 'comment').length;
+        const typeRefCount = affectedSites.filter((s) => s.changeType === 'type-reference').length;
+        let verdict;
+        if (!safe) {
+            const reasons = [];
+            if (conflicts.length > 0) {
+                reasons.push(`"${newName}" conflicts with an existing symbol`);
+            }
+            if (hasStringLiterals) {
+                reasons.push(`${stringLitCount} string-literal reference(s) require manual update`);
+            }
+            verdict = `Not safe to rename: ${reasons.join('; ')}. ${affectedFileCount} file(s) affected.`;
+        }
+        else {
+            const breakdown = [];
+            if (callCount > 0)
+                breakdown.push(`${callCount} call site${callCount > 1 ? 's' : ''}`);
+            if (importCount > 0)
+                breakdown.push(`${importCount} import${importCount > 1 ? 's' : ''}`);
+            if (typeRefCount > 0)
+                breakdown.push(`${typeRefCount} type reference${typeRefCount > 1 ? 's' : ''}`);
+            if (commentCount > 0)
+                breakdown.push(`${commentCount} comment${commentCount > 1 ? 's' : ''}`);
+            const detail = breakdown.length > 0 ? ` (${breakdown.join(', ')})` : '';
+            verdict = `Safe to rename: ${affectedFileCount} file${affectedFileCount !== 1 ? 's' : ''} affected${detail}. No conflicts.`;
+        }
+        const responseText = JSON.stringify(affectedSites);
+        const output = {
+            safe,
+            verdict,
+            symbolName: symbol.name,
+            newName,
+            conflicts,
+            affectedSites,
+            affectedFileCount,
+            _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=check-rename-safe.js.map

package/dist/server/tools/check-rename-safe.js.map

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

package/dist/server/tools/diff-health-radar.d.ts

@@ -0,0 +1,44 @@
+/**
+ * diff-health-radar.ts
+ *
+ * MCP tool: diff_health_radar
+ *
+ * Compare health radar scores between two indexed repos (or two states of the
+ * same codebase). Primary use cases:
+ *
+ *   • PR review: index main branch → index feature branch → compare
+ *   • Refactoring validation: index before → refactor → re-index → compare
+ *   • Cross-repo benchmark: compare health of two different projects
+ *
+ * Runs health_radar on both repos, then computes per-axis deltas (head − base).
+ * Positive delta = improvement; negative delta = regression.
+ *
+ * Output:
+ *   • base snapshot — health scores from baseRepoId
+ *   • head snapshot — health scores from headRepoId
+ *   • axes delta map — score change per axis with trend label
+ *   • overallDelta — change in overall health (head − base)
+ *   • trend — 'improved' | 'degraded' | 'stable' (based on overallDelta)
+ *   • regressions — axis names that degraded by > SIGNIFICANT_DELTA
+ *   • improvements — axis names that improved by > SIGNIFICANT_DELTA
+ *
+ * A delta of +5 or more is treated as a meaningful improvement.
+ * A delta of −5 or more (negative) is treated as a meaningful regression.
+ */
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare const name = "diff_health_radar";
+export declare const description: string;
+export declare const inputSchema: {
+    baseRepoId: z.ZodString;
+    headRepoId: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    includeStability: z.ZodOptional<z.ZodBoolean>;
+};
+export declare function handler(args: {
+    baseRepoId: string;
+    headRepoId: string;
+    scope?: string;
+    includeStability?: boolean;
+}): Promise<CallToolResult>;
+//# sourceMappingURL=diff-health-radar.d.ts.map

package/dist/server/tools/diff-health-radar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-health-radar.d.ts","sourceRoot":"","sources":["../../../src/server/tools/diff-health-radar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAIzE,eAAO,MAAM,IAAI,sBAAsB,CAAC;AAExC,eAAO,MAAM,WAAW,QAMwB,CAAC;AAEjD,eAAO,MAAM,WAAW;;;;;CAqBvB,CAAC;AAkGF,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,OAAO,CAAC,cAAc,CAAC,CAuH1B"}

package/dist/server/tools/diff-health-radar.js

@@ -0,0 +1,192 @@
+/**
+ * diff-health-radar.ts
+ *
+ * MCP tool: diff_health_radar
+ *
+ * Compare health radar scores between two indexed repos (or two states of the
+ * same codebase). Primary use cases:
+ *
+ *   • PR review: index main branch → index feature branch → compare
+ *   • Refactoring validation: index before → refactor → re-index → compare
+ *   • Cross-repo benchmark: compare health of two different projects
+ *
+ * Runs health_radar on both repos, then computes per-axis deltas (head − base).
+ * Positive delta = improvement; negative delta = regression.
+ *
+ * Output:
+ *   • base snapshot — health scores from baseRepoId
+ *   • head snapshot — health scores from headRepoId
+ *   • axes delta map — score change per axis with trend label
+ *   • overallDelta — change in overall health (head − base)
+ *   • trend — 'improved' | 'degraded' | 'stable' (based on overallDelta)
+ *   • regressions — axis names that degraded by > SIGNIFICANT_DELTA
+ *   • improvements — axis names that improved by > SIGNIFICANT_DELTA
+ *
+ * A delta of +5 or more is treated as a meaningful improvement.
+ * A delta of −5 or more (negative) is treated as a meaningful regression.
+ */
+import { z } from 'zod';
+import { handler as healthRadarHandler } from './health-radar.js';
+import { buildMeta } from './_meta.js';
+// ─── Tool exports ─────────────────────────────────────────────────────────────
+export const name = 'diff_health_radar';
+export const description = 'Compare health radar scores between two indexed repos (or two states of the same codebase). ' +
+    'Runs health_radar on baseRepoId and headRepoId, then computes per-axis deltas. ' +
+    'Positive delta = improvement; negative delta = regression. ' +
+    'Primary use cases: PR review (index main vs feature branch), refactoring validation ' +
+    '(index before/after), and cross-repo health benchmarking. ' +
+    'Use health_radar for a single-repo snapshot.';
+export const inputSchema = {
+    baseRepoId: z
+        .string()
+        .describe('Baseline repo ID (e.g. main branch). From index_folder or resolve_repo.'),
+    headRepoId: z
+        .string()
+        .describe('Head repo ID to compare against the baseline (e.g. feature branch).'),
+    scope: z
+        .string()
+        .optional()
+        .describe('Directory prefix filter applied to both repos (e.g. "src/core/"). ' +
+        'Narrows analysis to the same subtree in each repo.'),
+    includeStability: z
+        .boolean()
+        .optional()
+        .describe('Include churn-based stability axis in both snapshots (requires git metadata; default true). ' +
+        'Set false to skip git queries when git data is absent.'),
+};
+// ─── Constants ────────────────────────────────────────────────────────────────
+const SIGNIFICANT_DELTA = 5; // Minimum delta (absolute) to count as meaningful
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function toTrend(delta) {
+    if (delta >= SIGNIFICANT_DELTA)
+        return 'improved';
+    if (delta <= -SIGNIFICANT_DELTA)
+        return 'degraded';
+    return 'stable';
+}
+function parseSnapshot(result, repoId) {
+    if (result.isError)
+        return null;
+    const text = result.content[0]?.text;
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+const AXIS_NAMES = [
+    'complexity',
+    'coupling',
+    'maintainability',
+    'documentation',
+    'stability',
+];
+// ─── Handler ──────────────────────────────────────────────────────────────────
+export async function handler(args) {
+    const t0 = Date.now();
+    const { baseRepoId, headRepoId, scope, includeStability = true } = args;
+    // ── Run health_radar on both repos in parallel ────────────────────────────
+    const [baseResult, headResult] = await Promise.all([
+        healthRadarHandler({ repoId: baseRepoId, scope, includeStability }),
+        healthRadarHandler({ repoId: headRepoId, scope, includeStability }),
+    ]);
+    // ── Validate both succeeded ────────────────────────────────────────────────
+    const baseJson = parseSnapshot(baseResult, baseRepoId);
+    const headJson = parseSnapshot(headResult, headRepoId);
+    if (!baseJson) {
+        // Forward the base error
+        if (baseResult.isError)
+            return baseResult;
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ error: `Failed to compute health radar for base repo "${baseRepoId}"` }) }],
+            isError: true,
+        };
+    }
+    if (!headJson) {
+        // Forward the head error
+        if (headResult.isError)
+            return headResult;
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ error: `Failed to compute health radar for head repo "${headRepoId}"` }) }],
+            isError: true,
+        };
+    }
+    // ── Compute per-axis deltas ────────────────────────────────────────────────
+    const axes = {};
+    const regressions = [];
+    const improvements = [];
+    for (const axisName of AXIS_NAMES) {
+        const baseAxis = baseJson.axes[axisName];
+        const headAxis = headJson.axes[axisName];
+        const baseScore = baseAxis.score;
+        const headScore = headAxis.score;
+        const delta = headScore - baseScore;
+        const trend = toTrend(delta);
+        axes[axisName] = {
+            baseScore,
+            headScore,
+            delta,
+            trend,
+            baseAvailable: baseAxis.available,
+            headAvailable: headAxis.available,
+        };
+        if (trend === 'degraded')
+            regressions.push(axisName);
+        if (trend === 'improved')
+            improvements.push(axisName);
+    }
+    // ── Overall delta and trend ────────────────────────────────────────────────
+    const overallDelta = headJson.overallHealth - baseJson.overallHealth;
+    const trend = toTrend(overallDelta);
+    // ── Snapshots (subset for output) ─────────────────────────────────────────
+    const base = {
+        repoId: baseRepoId,
+        overallHealth: baseJson.overallHealth,
+        grade: baseJson.grade,
+        axes: baseJson.axes,
+        gitDataAvailable: baseJson.summary.gitDataAvailable,
+    };
+    const head = {
+        repoId: headRepoId,
+        overallHealth: headJson.overallHealth,
+        grade: headJson.grade,
+        axes: headJson.axes,
+        gitDataAvailable: headJson.summary.gitDataAvailable,
+    };
+    // ── Summary ────────────────────────────────────────────────────────────────
+    const axesCompared = AXIS_NAMES.filter((n) => axes[n].baseAvailable || axes[n].headAvailable).length;
+    const gradeChange = base.grade === head.grade
+        ? base.grade
+        : `${base.grade} → ${head.grade}`;
+    const output = {
+        baseRepoId,
+        headRepoId,
+        scope,
+        generatedAt: new Date().toISOString(),
+        base,
+        head,
+        axes,
+        overallDelta,
+        trend,
+        regressions,
+        improvements,
+        summary: {
+            axesCompared,
+            regressionCount: regressions.length,
+            improvementCount: improvements.length,
+            stableCount: AXIS_NAMES.length - regressions.length - improvements.length,
+            overallGradeChange: gradeChange,
+        },
+        _tokenEstimate: 0,
+        _meta: buildMeta({ timingMs: Date.now() - t0 }),
+    };
+    const text = JSON.stringify(output, null, 2);
+    output._tokenEstimate = Math.ceil(text.length / 4);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(output, null, 2) }],
+    };
+}
+//# sourceMappingURL=diff-health-radar.js.map

package/dist/server/tools/diff-health-radar.js.map

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

package/dist/server/tools/find-cycles.d.ts

@@ -0,0 +1,31 @@
+/**
+ * find-cycles.ts
+ *
+ * MCP tool: find_cycles
+ *
+ * Detect all import cycles in the dependency graph and return them as ordered
+ * file paths. Unlike detect_antipatterns (which reports only a count and
+ * severity), this tool returns the actual cycle paths so an agent can understand
+ * and resolve circular dependencies.
+ *
+ * Algorithm: DFS with path stack. Each cycle is reported exactly once, rooted
+ * at its lexicographically smallest file. Severity is 'error' for tight 2–3-node
+ * cycles (tightly coupled pairs/triangles) and 'warning' for longer chains.
+ */
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare const name = "find_cycles";
+export declare const description: string;
+export declare const inputSchema: {
+    repoId: z.ZodString;
+    filePath: z.ZodOptional<z.ZodString>;
+    maxCycles: z.ZodOptional<z.ZodNumber>;
+    minLength: z.ZodOptional<z.ZodNumber>;
+};
+export declare function handler(args: {
+    repoId: string;
+    filePath?: string;
+    maxCycles?: number;
+    minLength?: number;
+}): Promise<CallToolResult>;
+//# sourceMappingURL=find-cycles.d.ts.map

package/dist/server/tools/find-cycles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-cycles.d.ts","sourceRoot":"","sources":["../../../src/server/tools/find-cycles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,eAAO,MAAM,IAAI,gBAAgB,CAAC;AAElC,eAAO,MAAM,WAAW,QAK0D,CAAC;AAEnF,eAAO,MAAM,WAAW;;;;;CA0BvB,CAAC;AAoBF,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,cAAc,CAAC,CAuC1B"}

package/dist/server/tools/find-cycles.js

@@ -0,0 +1,85 @@
+/**
+ * find-cycles.ts
+ *
+ * MCP tool: find_cycles
+ *
+ * Detect all import cycles in the dependency graph and return them as ordered
+ * file paths. Unlike detect_antipatterns (which reports only a count and
+ * severity), this tool returns the actual cycle paths so an agent can understand
+ * and resolve circular dependencies.
+ *
+ * Algorithm: DFS with path stack. Each cycle is reported exactly once, rooted
+ * at its lexicographically smallest file. Severity is 'error' for tight 2–3-node
+ * cycles (tightly coupled pairs/triangles) and 'warning' for longer chains.
+ */
+import { z } from 'zod';
+import { openDatabase, getRepo } from '../../core/db/schema.js';
+import { findImportCycles } from '../../graph/graph-traversal.js';
+import { buildMeta } from './_meta.js';
+export const name = 'find_cycles';
+export const description = 'Detect all import cycles in the dependency graph and return them as ordered ' +
+    'file paths. Unlike detect_antipatterns (which only counts cycles), this tool ' +
+    'returns the actual cycle paths so you can understand and resolve circular ' +
+    'dependencies. Severity is "error" for tight 2–3 node cycles and "warning" ' +
+    'for longer chains. Use filePath to scope results to cycles involving one file.';
+export const inputSchema = {
+    repoId: z.string().describe('Repo ID from index_folder or resolve_repo'),
+    filePath: z
+        .string()
+        .optional()
+        .describe('Scope to cycles that involve this file (relative to repo root). ' +
+        'If omitted, all cycles in the repo are returned up to maxCycles.'),
+    maxCycles: z
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .optional()
+        .describe('Stop after finding this many cycles (default 20)'),
+    minLength: z
+        .number()
+        .int()
+        .min(2)
+        .max(20)
+        .optional()
+        .describe('Minimum cycle length to report (default 2). ' +
+        'A mutual import A→B→A has length 2. Raise this to skip direct pairs.'),
+};
+// ─── Handler ──────────────────────────────────────────────────────────────────
+export async function handler(args) {
+    const t0 = Date.now();
+    const { repoId, filePath, maxCycles = 20, minLength = 2 } = 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,
+            };
+        }
+        const result = findImportCycles(repoId, db, filePath, maxCycles, minLength);
+        const responseText = JSON.stringify(result.cycles);
+        const output = {
+            cycles: result.cycles,
+            totalFound: result.totalFound,
+            truncated: result.truncated,
+            _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=find-cycles.js.map