# Circular Code Dependency Detector MCP for AI Agents MCP

> Circular Code Dependency Detector MCP for identifying import cycles and measuring module interdependence. It helps developers find loop paths like A -> B -> C -> A and analyze coupling metrics in JavaScript, TypeScript, and Python projects to prevent runtime initialization errors.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_V2TywrXk4ZedJ9OsuD67krBjloqkZ6H14wDHFEBh/mcp
- **Tags:** javascript, typescript, python, dependency-graph, cycle-detection

## Description

You are working on a large codebase and suddenly everything breaks because of an unexpected import loop. Tracking down which file is causing the circular dependency feels like chasing ghosts through dozens of folders. This MCP lets your AI client look directly at your project structure to find exactly where these loops start and end. You can use it to map out how modules relate to each other and identify which files are becoming too heavily dependent on everything else. It's part of the Vinkius catalog, making it easy to bring deep architectural analysis into your existing coding workflow without manual searching.

## Tools

### compute_coupling_metrics
Calculates how much a specific module relies on others. It helps you see if a file is too tightly bound to the rest of your project.

### detect_cycles
Locates exact paths where imports loop back on themselves. This prevents frustrating runtime errors.

### scan_dependencies
Looks through your directory to build a complete dependency map. It is the first step in understanding your project architecture.

## Prompt Examples

**Prompt:** 
```
Are there any circular imports in my current folder?
```

**Response:** 
```
I scanned the directory and found one cycle:

| Path |
| :--- |
| `src/auth.ts` $\rightarrow$ `src/utils.ts` $\rightarrow$ `src/auth.ts` |

You should check `src/utils.ts` to see if you can move the shared logic elsewhere.
```

**Prompt:** 
```
How much does auth_service.py depend on other modules?
```

**Response:** 
```
The coupling metrics for `auth_service.py` are:

* **In-degree:** 5 (5 modules depend on this)
* **Out-degree:** 2 (This module depends on 2 others)

It is a moderately coupled module.
```

**Prompt:** 
```
Check if this new import will create a loop.
```

**Response:** 
```
I analyzed the current dependency map. Adding an import from `index.ts` to `config.ts` **will not** create a new cycle, as `config.ts` does not currently depend on `index.ts`.
```

## Capabilities

### Find hidden import loops
Locate exact paths where dependencies loop back on themselves.

### Map module relationships
Build a clear picture of how files in your project interact.

### Identify bottleneck modules
Spot files that have too many incoming or outgoing dependencies.

### Check coupling strength
Measure how tightly bound a specific module is to the rest of your code.

### Scan project directories
Automatically audit your entire folder structure for dependency links.

## Use Cases

### Refactoring a monolith
You are breaking up a large service and need to ensure moving a file doesn't create a new loop. Your agent verifies the new structure is safe.

### Debugging startup crashes
A Python script fails at runtime with an import error. You ask your agent to scan the directory and find the culprit path.

### Code review automation
During a PR, you want to ensure no new circular dependencies were introduced. Your agent checks the dependency map automatically.

### Architectural auditing
You need to identify which modules are becoming too complex. Your agent calculates coupling metrics to highlight problematic files.

## Benefits

- Kill runtime errors by finding circular imports before they hit production.
- Improve code maintainability by checking module strength and dependency levels.
- Reduce technical debt by identifying overly coupled files that are hard to refactor.
- Get a clear view of your project structure through automated directory audits.
- Prevent build failures in TypeScript projects by spotting loops early.

## How It Works

The bottom line is you stop guessing where circular imports are coming from.

1. Point your AI client to the directory you want to analyze.
2. The MCP scans your files and builds a complete dependency map.
3. You receive a detailed report of all detected cycles and coupling levels.

## Frequently Asked Questions

**How can I find circular imports in my JavaScript project using Circular Code Dependency Detector?**
You can simply ask your AI client to scan your directory. The MCP will identify any loops and show you the exact file path causing the issue.

**Can Circular Code Dependency Detector help with Python dependency issues?**
Yes, it is specifically designed to handle Python module imports, helping you find cycles that cause runtime errors during startup.

**Does Circular Code Dependency Detector work with TypeScript?**
Absolutely. It works perfectly with TypeScript projects to help you manage complex import trees and prevent build-time failures.

**Can I use this MCP to see which modules are the most important in my project?**
Yes, by looking at the coupling metrics, you can identify modules with high in-degree counts, which are your most critical dependencies.

**Will Circular Code Dependency Detector slow down my coding workflow?**
No, it actually speeds things up by automating the tedious process of manual dependency tracing and error hunting.

**How do I start detecting cycles in my project?**
First, use the `scan_dependencies` tool on your project directory to generate a dependency map. Then, pass that map into `detect_cycles` to see all identified loops.

**Can I analyze Python projects?**
Yes, the scanner supports `python` syntax alongside `javascript` and `typescript`.

**What are coupling metrics?**
They quantify module interdependence. By using `compute_coupling_metrics`, you can see the in-degree and out-degree of a module to find high-risk files.