get_project_map¶

Generate a high-level overview of a codebase including package structure, function/class inventory, entry points, and complexity hotspots.

Quick Reference¶

get_project_map(
    project_root: str = None,                # Project directory
    include_complexity: bool = True,         # Calculate complexity
    complexity_threshold: int = 10,          # Threshold for hotspots
    include_circular_check: bool = True,     # Check circular imports
    detect_service_boundaries: bool = False, # Detect microservices
    min_isolation_score: float = 0.6         # Service boundary threshold
) -> ProjectMapResult

User Stories¶

Persona	Story	Tool Value
🔰 Alex (First-Timer)	"Get a bird's-eye view of an unfamiliar codebase"	Orientation in new projects
👥 David (Team Lead)	"Generate project overview for new team members"	Faster onboarding
🏢 Jennifer (Enterprise Architect)	"Map entire monorepo with 1000+ modules"	Enterprise-scale analysis
🔧 Chris (OSS Contributor)	"Generate comprehensive architecture diagram of Code Scalpel itself"	Deep understanding

→ See all user stories

Parameters¶

Parameter	Type	Required	Default	Description
`project_root`	string	No	cwd	Project root directory
`include_complexity`	bool	No	true	Calculate cyclomatic complexity
`complexity_threshold`	int	No	10	Threshold for flagging hotspots
`include_circular_check`	bool	No	true	Check for circular imports
`detect_service_boundaries`	bool	No	false	Detect microservice boundaries
`min_isolation_score`	float	No	0.6	Minimum score for service detection

Response Schema¶

{
  "data": {
    "packages": [
      {
        "name": "string",
        "path": "string",
        "modules": ["string"],
        "subpackages": ["string"]
      }
    ],
    "modules": [
      {
        "name": "string",
        "path": "string",
        "functions": ["string"],
        "classes": ["string"],
        "imports": ["string"],
        "complexity": "integer"
      }
    ],
    "entry_points": [
      {
        "type": "string",
        "function": "string",
        "file": "string",
        "line": "integer"
      }
    ],
    "complexity_hotspots": [
      {
        "function": "string",
        "file": "string",
        "complexity": "integer",
        "line": "integer"
      }
    ],
    "circular_imports": [
      {
        "cycle": ["string"],
        "severity": "string"
      }
    ],
    "statistics": {
      "total_files": "integer",
      "total_functions": "integer",
      "total_classes": "integer",
      "total_lines": "integer",
      "average_complexity": "float"
    },
    "mermaid_diagram": "string"
  },
  "tier_applied": "string",
  "duration_ms": "integer"
}

Examples¶

Basic Project Map¶

AI PromptMCP Tool CallCLI CommandResponse

Give me an overview of the src directory structure

{
  "project_root": "/project/src"
}

codescalpel get-project-map src/

{
  "data": {
    "packages": [
      {
        "name": "src",
        "path": "/project/src",
        "modules": ["main.py", "config.py"],
        "subpackages": ["api", "services", "models", "utils"]
      },
      {
        "name": "api",
        "path": "/project/src/api",
        "modules": ["routes.py", "middleware.py", "auth.py"]
      },
      {
        "name": "services",
        "path": "/project/src/services",
        "modules": ["user_service.py", "order_service.py", "payment_service.py"]
      }
    ],
    "modules": [
      {
        "name": "main.py",
        "path": "/project/src/main.py",
        "functions": ["main", "setup_logging", "create_app"],
        "classes": [],
        "imports": ["flask", "config", "api.routes"],
        "complexity": 5
      },
      {
        "name": "user_service.py",
        "path": "/project/src/services/user_service.py",
        "functions": [],
        "classes": ["UserService"],
        "imports": ["models.user", "db"],
        "complexity": 12
      }
    ],
    "entry_points": [
      {
        "type": "main",
        "function": "main",
        "file": "main.py",
        "line": 45
      },
      {
        "type": "flask_route",
        "function": "handle_login",
        "file": "api/routes.py",
        "line": 25
      },
      {
        "type": "flask_route",
        "function": "handle_signup",
        "file": "api/routes.py",
        "line": 50
      }
    ],
    "complexity_hotspots": [
      {
        "function": "process_payment",
        "file": "services/payment_service.py",
        "complexity": 18,
        "line": 45
      },
      {
        "function": "validate_order",
        "file": "services/order_service.py",
        "complexity": 15,
        "line": 78
      }
    ],
    "circular_imports": [],
    "statistics": {
      "total_files": 15,
      "total_functions": 48,
      "total_classes": 12,
      "total_lines": 2450,
      "average_complexity": 4.2
    },
    "mermaid_diagram": "graph TD\n    subgraph src\n        main.py\n        config.py\n    end\n    subgraph api\n        routes.py\n        auth.py\n    end\n    subgraph services\n        user_service.py\n        order_service.py\n    end\n    main.py --> routes.py\n    routes.py --> user_service.py"
  },
  "tier_applied": "community",
  "duration_ms": 320
}

Find Complexity Hotspots¶

AI PromptMCP Tool CallCLI CommandResponse

Find all functions with complexity over 8 in the project

{
  "project_root": "/project/src",
  "include_complexity": true,
  "complexity_threshold": 8
}

codescalpel get-project-map src/ \
  --include-complexity \
  --complexity-threshold 8

{
  "data": {
    "complexity_hotspots": [
      {
        "function": "process_payment",
        "file": "services/payment_service.py",
        "complexity": 18,
        "line": 45,
        "recommendation": "Consider breaking into smaller functions"
      },
      {
        "function": "validate_order",
        "file": "services/order_service.py",
        "complexity": 15,
        "line": 78
      },
      {
        "function": "parse_config",
        "file": "config.py",
        "complexity": 12,
        "line": 20
      },
      {
        "function": "handle_webhook",
        "file": "api/webhooks.py",
        "complexity": 10,
        "line": 35
      }
    ],
    "statistics": {
      "functions_above_threshold": 4,
      "average_complexity": 4.2,
      "max_complexity": 18
    }
  }
}

Check for Circular Imports¶

AI PromptMCP Tool CallCLI CommandResponse

Check the project for circular import issues

{
  "project_root": "/project/src",
  "include_circular_check": true
}

codescalpel get-project-map src/ --include-circular-check

{
  "data": {
    "circular_imports": [
      {
        "cycle": ["models.user", "services.user_service", "models.user"],
        "files": ["models/user.py", "services/user_service.py"],
        "severity": "HIGH",
        "suggestion": "Move shared code to a separate module or use lazy imports"
      },
      {
        "cycle": ["api.routes", "api.middleware", "api.routes"],
        "files": ["api/routes.py", "api/middleware.py"],
        "severity": "MEDIUM",
        "suggestion": "Consider consolidating or using TYPE_CHECKING imports"
      }
    ],
    "has_circular_imports": true,
    "total_cycles": 2
  }
}

Detect Service Boundaries¶

AI PromptMCP Tool CallCLI CommandResponse

Analyze the project to detect potential microservice boundaries

{
  "project_root": "/project/src",
  "detect_service_boundaries": true,
  "min_isolation_score": 0.6
}

codescalpel get-project-map src/ \
  --detect-service-boundaries \
  --min-isolation-score 0.6

{
  "data": {
    "service_boundaries": [
      {
        "name": "user_domain",
        "modules": ["models/user.py", "services/user_service.py", "api/user_routes.py"],
        "isolation_score": 0.85,
        "external_dependencies": ["db", "config"],
        "recommendation": "Good candidate for extraction"
      },
      {
        "name": "payment_domain",
        "modules": ["services/payment_service.py", "api/payment_routes.py"],
        "isolation_score": 0.72,
        "external_dependencies": ["db", "stripe_client"],
        "recommendation": "Consider extracting with stripe_client"
      }
    ]
  },
  "tier_applied": "enterprise",
  "duration_ms": 580
}

Entry Point Types¶

Type	Description	Example
`main`	`if __name__ == "__main__"`	`main.py:main`
`flask_route`	Flask `@app.route`	`routes.py:index`
`django_view`	Django view function	`views.py:home`
`fastapi_route`	FastAPI endpoint	`api.py:get_users`
`cli_command`	Click/argparse command	`cli.py:run`
`celery_task`	Celery `@task`	`tasks.py:send_email`
`pytest_test`	Test function	`test_user.py:test_login`

Mermaid Diagram¶

The tool generates a project structure diagram:

graph TD
    subgraph src
        main[main.py]
        config[config.py]
    end

    subgraph api
        routes[routes.py]
        auth[auth.py]
    end

    subgraph services
        user[user_service.py]
        order[order_service.py]
    end

    main --> config
    main --> routes
    routes --> auth
    routes --> user
    routes --> order

Tier Limits¶

get_project_map capabilities vary by tier:

Feature	Community	Pro	Enterprise
Max files	100	1,000	Unlimited
Max modules	50	200	1,000
Detail level	Basic	Detailed	Comprehensive
Complexity analysis	✅	✅	✅
Circular import check	✅	✅	✅
Dependency analysis	Basic (imports only)	✅ Full (cross-file)	✅ Full (cross-file)
Architecture diagrams	❌	✅ Mermaid	✅ Advanced
Service boundary detection	❌	❌	✅ Microservices
Custom mapping rules	❌	❌	✅ Plugin support

Community Tier¶

✅ Generate basic project structure map
✅ Package and module inventory
✅ Entry point detection (main, routes, CLI)
✅ Complexity hotspot identification
✅ Circular import detection
⚠️ Limited to 100 files, 50 modules - May not cover full project
⚠️ Basic detail level - High-level overview only
❌ No cross-file dependency analysis
❌ No architecture diagrams

Pro Tier¶

✅ All Community features
✅ 1,000 files, 200 modules - Handle larger projects
✅ Detailed analysis - More comprehensive overview
✅ Full cross-file dependencies - Understand module relationships
✅ Mermaid architecture diagrams - Visualize project structure
✅ Enhanced complexity metrics - Better hotspot detection
✅ Historical tracking - Compare across versions

Enterprise Tier¶

✅ All Pro features
✅ Unlimited files, 1,000 modules - No project size limits
✅ Comprehensive detail level - Deepest insights
✅ Service boundary detection - Identify microservice boundaries
✅ Custom mapping rules - Organization-specific analysis
✅ Advanced diagrams - Interactive, customizable visualizations
✅ Plugin support - Extend with custom analyzers

Key Difference: Project Scale and Detail - Community: 100 files, basic overview - Small projects/quick check - Pro: 1,000 files, detailed analysis, diagrams - Production codebases - Enterprise: Unlimited, comprehensive, service detection - Enterprise monorepos

→ See tier comparison

Best Practices¶

Run on new codebases - Quick orientation
Monitor complexity - Track hotspots over time
Fix circular imports - Prevent runtime issues
Use for documentation - Mermaid diagrams for docs
Identify refactoring targets - High complexity = refactor

get_call_graph - Function relationships
analyze_code - Single file analysis
crawl_project - Full project analysis

get_project_map¶

Quick Reference¶

User Stories¶

Parameters¶

Response Schema¶

Examples¶

Basic Project Map¶

Find Complexity Hotspots¶

Check for Circular Imports¶

Detect Service Boundaries¶

Entry Point Types¶

Mermaid Diagram¶

Tier Limits¶

Community Tier¶

Pro Tier¶

Enterprise Tier¶

Best Practices¶

Related Tools¶