available-tools.md

Available Tools Reference

CodeRAG provides 23 powerful tools for code analysis:

Core CRUD Operations

add_node

Description: Add a new code node (class, method, field, etc.)

Parameters:

• type: Node type (class, method, interface, field, package)
• id: Unique identifier
• name: Display name
• properties: Additional properties object
• project_id: Project identifier (optional, auto-detected if single project)

Example:

{
  "type": "class",
  "id": "com.example.UserService",
  "name": "UserService", 
  "properties": {
    "package": "com.example",
    "access_modifier": "public",
    "is_abstract": false
  }
}

update_node

Description: Update an existing node's properties

Parameters:

• node_id: ID of node to update
• properties: Properties to update
• project_id: Project identifier (optional)

get_node

Description: Retrieve a node by ID

Parameters:

• node_id: Unique node identifier
• project_id: Project identifier (optional)

delete_node

Description: Delete a node and its relationships

Parameters:

• node_id: ID of node to delete
• project_id: Project identifier (optional)

add_edge

Description: Add a relationship edge between nodes

Parameters:

• source_id: Source node ID
• target_id: Target node ID
• relationship_type: Type of relationship (extends, implements, calls, etc.)
• properties: Additional edge properties
• project_id: Project identifier (optional)

Common relationship types:

• EXTENDS: Inheritance
• IMPLEMENTS: Interface implementation
• CALLS: Method/function calls
• REFERENCES: Field/variable references
• CONTAINS: Containment (class contains method)
• BELONGS_TO: Package membership

get_edge

Description: Retrieve an edge by ID

Parameters:

• edge_id: Unique edge identifier
• project_id: Project identifier (optional)

delete_edge

Description: Delete a relationship edge

Parameters:

• edge_id: ID of edge to delete
• project_id: Project identifier (optional)

Search & Discovery

find_nodes_by_type

Description: Find all nodes of a specific type

Parameters:

• node_type: Type to search for (class, interface, method, field, package)
• limit: Maximum results to return (default: 100)
• project_id: Project identifier (optional)

Example:

{
  "node_type": "class",
  "limit": 50,
  "project_id": "my-project"
}

search_nodes

Description: Search nodes by name or description

Parameters:

• search_term: Text to search for
• node_type: Optional type filter
• limit: Maximum results (default: 100)
• project_id: Project identifier (optional)

Search capabilities:

• Partial name matching
• Case-insensitive search
• Searches name and description fields
• Supports wildcard patterns

find_edges_by_source

Description: Find all edges from a source node

Parameters:

• source_node_id: Source node identifier
• relationship_type: Optional relationship filter
• limit: Maximum results (default: 100)
• project_id: Project identifier (optional)

Semantic Search

semantic_search

Description: Search for code using natural language queries to find functionality by meaning

Parameters:

• query: Natural language description of functionality to search for
• project_id: Optional project identifier to scope search
• node_types: Optional array of node types to filter (class, method, function, etc.)
• limit: Maximum results (default: 10)
• similarity_threshold: Minimum similarity score 0.0-1.0 (default: 0.7)
• include_graph_context: Include related entities in results (default: false)
• max_hops: Maximum relationship hops for context (default: 2)

Example:

{
  "query": "functions that validate email addresses",
  "project_id": "my-web-app",
  "node_types": ["function", "method"],
  "limit": 5,
  "similarity_threshold": 0.8,
  "include_graph_context": true
}

get_similar_code

Description: Find code entities semantically similar to a specific node

Parameters:

• node_id: ID of the reference code entity
• project_id: Project containing the reference node
• limit: Maximum results (default: 5)

Example:

{
  "node_id": "UserValidator.validateEmail",
  "project_id": "my-web-app",
  "limit": 10
}

update_embeddings

Description: Generate or refresh semantic embeddings for code entities

Parameters:

• project_id: Optional project identifier to scope update
• node_types: Optional array of node types to update

Example:

{
  "project_id": "my-web-app",
  "node_types": ["class", "method", "function"]
}

initialize_semantic_search

Description: Initialize semantic search infrastructure and vector indexes

Parameters: None

Usage: Run once per database to set up vector search capabilities

Relationship Analysis

find_classes_calling_method

Description: Find classes that call a specific method

Parameters:

• method_name: Name of the method to search for
• target_class: Optional class that owns the method
• project_id: Project identifier (optional)

Use cases:

• Impact analysis for method changes
• Finding usage patterns
• Dependency analysis
• Refactoring planning

find_classes_implementing_interface

Description: Find classes implementing an interface

Parameters:

• interface_name: Name of the interface
• project_id: Project identifier (optional)

Returns:

• List of implementing classes
• Implementation details
• Inheritance hierarchy information

get_inheritance_hierarchy

Description: Get complete inheritance hierarchy for a class

Parameters:

• class_name: Name of the class
• direction: "up" (ancestors), "down" (descendants), or "both" (default)
• max_depth: Maximum hierarchy depth (default: 10)
• project_id: Project identifier (optional)

Output format:

{
  "root_class": "BaseEntity",
  "hierarchy": {
    "ancestors": [
      {"name": "Object", "depth": 0},
      {"name": "BaseEntity", "depth": 1}
    ],
    "descendants": [
      {"name": "User", "depth": 1},
      {"name": "Product", "depth": 1},
      {"name": "AdminUser", "depth": 2}
    ]
  }
}

Quality & Metrics

calculate_ck_metrics

Description: Calculate Chidamber & Kemerer metrics for a class

Parameters:

• class_id: Unique class identifier
• project_id: Project identifier (optional)

Metrics calculated:

• WMC (Weighted Methods per Class): Complexity measure
• DIT (Depth of Inheritance Tree): Inheritance depth
• NOC (Number of Children): Direct subclasses
• CBO (Coupling Between Objects): Class dependencies
• RFC (Response for Class): Total method calls
• LCOM (Lack of Cohesion in Methods): Method cohesion

Output includes:

• Raw metric values
• Quality classifications (Good/Warning/Critical)
• Interpretation guidance
• Improvement recommendations

calculate_package_metrics

Description: Calculate package-level metrics

Parameters:

• package_name: Package/module name
• project_id: Project identifier (optional)

Metrics calculated:

• Ca (Afferent Coupling): Incoming dependencies
• Ce (Efferent Coupling): Outgoing dependencies
• I (Instability): Change resilience (Ce/(Ca+Ce))
• A (Abstractness): Abstract classes ratio
• D (Distance from Main Sequence): Balance measure

find_architectural_issues

Description: Detect architectural problems

Parameters:

• project_id: Project identifier (optional)
• severity: Filter by severity (low, medium, high, critical)

Issues detected:

• Circular Dependencies: Package dependency cycles
• God Classes: Classes with excessive responsibilities
• High Coupling: Classes with too many dependencies
• Unstable Dependencies: Architectural violations
• Dead Code: Unused classes and methods
• Long Parameter Lists: Methods with too many parameters

get_project_summary

Description: Get overall project quality summary

Parameters:

• project_id: Project identifier (optional)
• include_metrics: Include detailed metrics (default: true)

Summary includes:

• Entity counts by type
• Relationship statistics
• Quality score and grade
• Top architectural issues
• Recommendations for improvement
• Trend analysis (if historical data available)

Scanning Tools

add_file

Description: Parse and add a single source file

Parameters:

• file_path: Absolute path to source file
• language: Programming language (optional, auto-detected)
• clear_existing: Clear existing file data (default: false)
• project_id: Project identifier (optional)

Supported languages:

• TypeScript (.ts, .tsx)
• JavaScript (.js, .jsx)
• Java (.java)
• Python (.py)

scan_dir

Description: Scan entire directory/project

Parameters:

• directory_path: Path to project root
• languages: Array of languages to scan (optional, auto-detected)
• exclude_paths: Directories to exclude (default: ["node_modules", "dist", "build"])
• include_tests: Include test files (default: false)
• clear_existing: Clear existing project data (default: false)
• max_depth: Maximum directory depth (default: 10)
• project_id: Project identifier (optional, derived from directory name)

Example:

{
  "directory_path": "/path/to/my-project",
  "languages": ["typescript", "javascript"],
  "exclude_paths": ["node_modules", "dist", "coverage"],
  "include_tests": true,
  "clear_existing": true,
  "max_depth": 8
}

Multi-Project Management

list_projects

Description: List all projects with optional statistics and filtering

Parameters:

• include_stats: Include entity/relationship counts (default: false)
• sort_by: Sort criteria (name, created_at, updated_at, entity_count)
• limit: Maximum projects to return (1-1000, default: 100)
• name_filter: Filter projects by name pattern (optional)

Example:

{
  "include_stats": true,
  "sort_by": "entity_count",
  "limit": 20,
  "name_filter": "*service*"
}

Output includes:

• Project metadata (ID, name, description)
• Creation and update timestamps
• Entity and relationship statistics
• Supported languages
• Quality summary

Tool Usage Patterns

1. Initial Project Analysis

# 1. Scan the project
scan_dir -> directory_path: "/path/to/project"

# 2. Get overview
get_project_summary

# 3. Find issues
find_architectural_issues

# 4. Analyze key classes
calculate_ck_metrics -> class_id: "com.example.UserService"

2. Dependency Investigation

# 1. Find the class
search_nodes -> search_term: "UserService"

# 2. Get its dependencies
find_edges_by_source -> source_node_id: "com.example.UserService"

# 3. Find what depends on it
find_classes_calling_method -> method_name: "authenticate"

# 4. Calculate coupling metrics
calculate_ck_metrics -> class_id: "com.example.UserService"

3. Architecture Analysis

# 1. Map inheritance hierarchies
get_inheritance_hierarchy -> class_name: "BaseEntity"

# 2. Find interface implementations
find_classes_implementing_interface -> interface_name: "Repository"

# 3. Analyze package structure
calculate_package_metrics -> package_name: "com.example.service"

# 4. Identify architectural issues
find_architectural_issues

4. Multi-Project Management

# 1. List all projects
list_projects -> include_stats: true

# 2. Compare projects
get_project_summary -> project_id: "project-a"
get_project_summary -> project_id: "project-b"

# 3. Cross-project analysis
search_nodes -> search_term: "Controller"  # Searches all projects

5. Semantic Code Discovery

# 1. Initialize semantic search (one-time setup)
initialize_semantic_search

# 2. Generate embeddings for existing project
update_embeddings -> project_id: "my-project"

# 3. Search by functionality
semantic_search -> query: "functions that validate email addresses"

# 4. Find similar code
get_similar_code -> node_id: "UserValidator.validateEmail", project_id: "my-project"

# 5. Search with context
semantic_search -> query: "database connection utilities", include_graph_context: true

Error Handling

All tools return standardized error responses:

{
  "error": {
    "code": "NODE_NOT_FOUND",
    "message": "Node with ID 'com.example.Missing' not found",
    "details": {
      "node_id": "com.example.Missing",
      "project_id": "my-project"
    }
  }
}

Common error codes:

• NODE_NOT_FOUND: Requested node doesn't exist
• EDGE_NOT_FOUND: Requested edge doesn't exist
• PROJECT_NOT_FOUND: Project doesn't exist
• INVALID_PARAMETERS: Invalid or missing parameters
• DATABASE_ERROR: Neo4J connection or query error
• SCAN_ERROR: File scanning or parsing error

Performance Considerations

Query Optimization

Large result sets:

• Use limit parameter to control result size
• Filter by project_id when possible
• Use specific node types rather than broad searches

Complex analysis:

• Break large hierarchies into smaller queries
• Use targeted searches instead of full scans
• Consider caching results for repeated analysis

Batch Operations

Multiple file scanning:

• Use scan_dir instead of multiple add_file calls
• Exclude unnecessary directories to improve performance
• Process large projects in stages if needed

Bulk analysis:

• Group related queries together
• Use project-specific queries when possible
• Cache frequently accessed results

Next Steps

• Quality Metrics - Detailed explanation of metrics and thresholds
• MCP Prompts Guide - Guided workflows using these tools
• Troubleshooting - Solving common tool issues