# MCP Tools, Resources, and Prompts Reference
Ragex exposes 72 MCP tools, 6 resources, and 6 prompts via the [Model Context Protocol](https://spec.modelcontextprotocol.io/) over stdio and Unix socket (`/tmp/ragex_mcp.sock`).
All tools are called via `tools/call` with JSON-RPC 2.0. Resources are read via `resources/read`. Prompts are retrieved via `prompts/get`.
## Quick Reference
```json
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"TOOL_NAME","arguments":{...}},"id":1}
```
---
## Tools
### Indexing and Analysis
#### `analyze_file`
Analyze a source file and extract code structure (modules, functions, calls) into the knowledge graph. Supports auto-detection of language from file extension.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | Absolute or relative path to the file |
| `language` | string | no | auto | `elixir`, `erlang`, `python`, `javascript`, `typescript`, `auto` |
| `generate_embeddings` | boolean | no | true | Generate embeddings for semantic search |
#### `analyze_directory`
Recursively analyze all supported files in a directory, extracting code structure into the knowledge graph.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | Path to the directory (or file) to analyze |
| `max_depth` | integer | no | 10 | Maximum directory depth to traverse |
| `exclude_patterns` | string[] | no | | Patterns to exclude (e.g., `node_modules`, `.git`) |
#### `watch_directory`
Start watching a directory for file changes and auto-reindex modified files.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | Directory path to watch |
#### `unwatch_directory`
Stop watching a directory.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | Directory path to stop watching |
#### `list_watched`
List all currently watched directories. No parameters.
---
### Knowledge Graph Queries
#### `query_graph`
Query the knowledge graph for code entities and relationships.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query_type` | string | yes | `find_module`, `find_function`, `get_calls`, `get_dependencies` |
| `params` | object | yes | Query-specific parameters |
#### `list_nodes`
List all nodes in the knowledge graph with optional filtering.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `node_type` | string | no | | Filter by node type (module, function, etc.) |
| `limit` | integer | no | 100 | Maximum results |
#### `graph_stats`
Get comprehensive graph statistics including PageRank and centrality metrics. No parameters.
Returns: `node_count`, `edge_count`, `average_degree`, `density`, `top_by_pagerank`, `top_by_degree`, `node_counts_by_type`.
#### `find_callers`
Find all functions that call a specific function.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `module` | string | yes | Module name (e.g., `MyModule`) |
| `function_name` | string | yes | Function name (e.g., `process`) |
| `arity` | integer | no | Function arity (searches any arity if omitted) |
#### `find_paths`
Find all paths (call chains) between two functions or modules.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `from` | string | yes | | Source node ID (e.g., `ModuleA.function/1`) |
| `to` | string | yes | | Target node ID (e.g., `ModuleB.function/2`) |
| `max_depth` | integer | no | 10 | Maximum path length |
---
### Search
#### `semantic_search`
Search codebase using natural language queries via embedding-based semantic similarity.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | yes | | Natural language query (e.g., "function to parse JSON") |
| `limit` | integer | no | 10 | Maximum results |
| `threshold` | number | no | 0.2 | Minimum similarity score (0.0-1.0, typical: 0.1-0.3) |
| `node_type` | string | no | | Filter: `module` or `function` |
| `include_context` | boolean | no | true | Include related entities (callers, callees) |
#### `hybrid_search`
Advanced search combining symbolic graph queries with semantic similarity using Reciprocal Rank Fusion.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | yes | | Natural language search query |
| `strategy` | string | no | fusion | `fusion`, `semantic_first`, `graph_first` |
| `limit` | integer | no | 10 | Maximum results |
| `threshold` | number | no | 0.15 | Minimum similarity score |
| `node_type` | string | no | | Filter: `module` or `function` |
| `include_context` | boolean | no | true | Include related entities |
#### `metaast_search`
Search for semantically equivalent code constructs across languages using MetaAST analysis.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `source_language` | string | yes | | `elixir`, `erlang`, `python`, `javascript` |
| `source_construct` | string | yes | | e.g., `Enum.map/2`, `list_comprehension`, or MetaAST pattern |
| `target_languages` | string[] | no | [] | Target languages (empty = all) |
| `limit` | integer | no | 5 | Max results per language |
| `threshold` | number | no | 0.6 | Semantic similarity threshold |
| `strict_equivalence` | boolean | no | false | Require exact AST match |
#### `cross_language_alternatives`
Suggest cross-language alternatives for a code construct.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `language` | string | yes | | Source language |
| `code` | string | yes | | Code snippet or construct description |
| `target_languages` | string[] | no | [] | Languages to generate alternatives for |
#### `expand_query`
Expand a search query with semantic synonyms and cross-language terms.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | yes | | Original search query |
| `intent` | string | no | auto | `explain`, `refactor`, `example`, `debug`, `general` |
| `max_terms` | integer | no | 5 | Maximum expansion terms |
| `include_synonyms` | boolean | no | true | Include semantic synonyms |
| `include_cross_language` | boolean | no | true | Include cross-language terms |
#### `find_metaast_pattern`
Find all implementations of a MetaAST pattern across all languages.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pattern` | string | yes | | MetaAST pattern (e.g., `collection_op:map`, `loop:for`, `lambda`) |
| `languages` | string[] | no | [] | Filter by languages (empty = all) |
| `limit` | integer | no | 20 | Maximum results |
---
### Graph Algorithms
#### `betweenness_centrality`
Compute betweenness centrality to identify bridge/bottleneck functions using Brandes' algorithm.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `max_nodes` | integer | no | 1000 | Limit computation to N highest-degree nodes |
| `normalize` | boolean | no | true | Return normalized scores (0-1) |
#### `closeness_centrality`
Compute closeness centrality to identify central functions in the call graph.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `normalize` | boolean | no | true | Return normalized scores (0-1) |
#### `detect_communities`
Detect communities/clusters in the call graph to identify architectural modules.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `algorithm` | string | no | louvain | `louvain` or `label_propagation` |
| `max_iterations` | integer | no | 10 | Maximum iterations |
| `resolution` | number | no | 1.0 | Resolution parameter (Louvain only) |
| `hierarchical` | boolean | no | false | Return hierarchical structure (Louvain only) |
| `seed` | integer | no | | Random seed (label propagation only) |
#### `export_graph`
Export the call graph in visualization formats.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `format` | string | yes | graphviz | `graphviz` (DOT) or `d3` (JSON) |
| `include_communities` | boolean | no | true | Include community clustering |
| `color_by` | string | no | pagerank | `pagerank`, `betweenness`, `degree` (graphviz only) |
| `max_nodes` | integer | no | 500 | Maximum nodes to include |
---
### File Editing
#### `edit_file`
Safely edit a single file with automatic backup, syntax validation, and atomic operations.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | Path to the file |
| `changes` | array | yes | | List of changes (see below) |
| `validate` | boolean | no | true | Validate syntax before applying |
| `create_backup` | boolean | no | true | Create backup before editing |
| `language` | string | no | auto | Explicit language for validation |
Each change object:
- `type`: `replace`, `insert`, or `delete`
- `line_start`: Starting line number (1-indexed)
- `line_end`: Ending line (for replace/delete)
- `content`: New content (for replace/insert)
#### `edit_files`
Atomically edit multiple files with automatic rollback on failure.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `files` | array | yes | | List of `{path, changes, validate?, format?, language}` objects |
| `validate` | boolean | no | true | Validate all files before applying |
| `create_backup` | boolean | no | true | Create backups |
| `format` | boolean | no | false | Format code after editing |
#### `validate_edit`
Preview validation of changes without applying them.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `path` | string | yes | Path to the file |
| `changes` | array | yes | List of changes to validate |
| `language` | string | no | Explicit language for validation |
#### `rollback_edit`
Undo a recent edit by restoring from backup.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `path` | string | yes | Path to the file |
| `backup_id` | string | no | Specific backup to restore (default: most recent) |
#### `edit_history`
Query backup history for a file.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | Path to the file |
| `limit` | integer | no | 10 | Maximum backups to return |
#### `read_file`
Read the contents of a source file with line numbers.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `path` | string | yes | Absolute path to the file |
| `start_line` | integer | no | Start line (1-indexed) |
| `end_line` | integer | no | End line (1-indexed) |
---
### Refactoring
#### `refactor_code`
Semantic refactoring operations using AST analysis and knowledge graph.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `operation` | string | yes | | `rename_function` or `rename_module` |
| `params` | object | yes | | `{module, old_name, new_name, arity}` |
| `scope` | string | no | project | `module` or `project` |
| `validate` | boolean | no | true | Validate before and after |
| `format` | boolean | no | true | Format code after refactoring |
#### `advanced_refactor`
Advanced refactoring operations with 8 operation types.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `operation` | string | yes | | See operations below |
| `params` | object | yes | | Operation-specific parameters |
| `validate` | boolean | no | true | Validate before and after |
| `format` | boolean | no | true | Format code after refactoring |
| `scope` | string | no | project | `module` or `project` |
Operations:
- `extract_function` -- params: `{module, source_function, source_arity, new_function, line_start, line_end}`
- `inline_function` -- params: `{module, function, arity}`
- `convert_visibility` -- params: `{module, function, arity, visibility}` (visibility: `public` or `private`)
- `rename_parameter` -- params: `{module, function, arity, old_name, new_name}`
- `modify_attributes` -- params: `{module, changes}` (changes: list of `{action, attribute, value}`)
- `change_signature` -- params: `{module, function, arity, changes}` (changes: list of `{action, param_name, position, default}`)
- `move_function` -- params: `{source_module, target_module, function, arity}`
- `extract_module` -- params: `{source_module, new_module, functions}` (functions: list of `{name, arity}`)
#### `preview_refactor`
Preview refactoring changes without applying them. Shows diffs, conflicts, and statistics with optional AI commentary.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `operation` | string | yes | | `rename_function`, `rename_module`, `extract_function`, `inline_function` |
| `params` | object | yes | | Operation-specific parameters |
| `format` | string | no | unified | `unified`, `side_by_side`, `json` |
| `ai_commentary` | boolean | no | true | Generate AI risk assessment |
#### `refactor_conflicts`
Check for conflicts before applying a refactoring operation.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `operation` | string | yes | `rename_function`, `rename_module`, `move_function`, `extract_module` |
| `params` | object | yes | Operation-specific parameters |
#### `undo_refactor`
Undo the most recent refactoring operation.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `project_path` | string | no | Project root path (uses cwd if not specified) |
#### `refactor_history`
List refactoring operation history with timestamps and file counts.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `project_path` | string | no | cwd | Project root path |
| `limit` | integer | no | 50 | Maximum entries |
| `include_undone` | boolean | no | false | Include undone operations |
#### `visualize_impact`
Visualize the impact of refactoring changes.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `files` | string[] | yes | | File paths affected by refactoring |
| `format` | string | no | ascii | `graphviz`, `d3_json`, `ascii` |
| `depth` | integer | no | 1 | Impact radius depth |
| `include_risk` | boolean | no | true | Include risk analysis |
#### `suggest_refactorings`
Analyze code and generate prioritized refactoring suggestions.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `target` | string | yes | | File path, directory, or module name |
| `patterns` | string[] | no | all | Filter: `extract_function`, `inline_function`, `split_module`, `merge_modules`, `remove_dead_code`, `reduce_coupling`, `simplify_complexity`, `extract_module` |
| `min_priority` | string | no | low | `info`, `low`, `medium`, `high`, `critical` |
| `include_actions` | boolean | no | true | Include step-by-step action plans |
| `use_rag` | boolean | no | false | Use RAG for AI-powered advice |
| `format` | string | no | summary | `summary`, `detailed`, `json` |
#### `explain_suggestion`
Get detailed explanation for a specific refactoring suggestion.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `suggestion_id` | string | yes | | ID from `suggest_refactorings` response |
| `include_code_context` | boolean | no | true | Include relevant code snippets |
| `use_rag` | boolean | no | false | Generate enhanced explanation using RAG |
#### `estimate_refactoring_effort`
Estimate effort required for a refactoring operation.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `operation` | string | yes | | `rename_function`, `rename_module`, `extract_function`, `inline_function`, `move_function`, `change_signature` |
| `target` | string | yes | | `Module.function/arity` or `Module` |
| `format` | string | no | summary | `summary`, `detailed`, `json` |
#### `risk_assessment`
Calculate risk score for changing a function or module.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `target` | string | yes | | `Module.function/arity` or `Module` |
| `format` | string | no | summary | `summary`, `detailed`, `json` |
---
### Code Quality and Analysis
#### `analyze_quality`
Analyze code quality metrics (complexity, purity, LOC) using Metastatic.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | File or directory path |
| `metrics` | string[] | no | all | `cyclomatic`, `cognitive`, `nesting`, `halstead`, `loc`, `function_metrics`, `purity` |
| `store_results` | boolean | no | true | Store in knowledge graph |
| `recursive` | boolean | no | true | Recurse directories |
#### `quality_report`
Generate a comprehensive quality report for analyzed files.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `report_type` | string | no | summary | `summary`, `detailed`, `by_language`, `trends` |
| `format` | string | no | text | `text`, `json`, `markdown` |
| `include_files` | boolean | no | false | Include individual file details |
#### `find_complex_code`
Find files or functions exceeding complexity thresholds.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `metric` | string | no | cyclomatic | `cyclomatic`, `cognitive`, `nesting` |
| `threshold` | number | no | 10 | Threshold value |
| `comparison` | string | no | gt | `gt`, `gte`, `lt`, `lte`, `eq` |
| `limit` | integer | no | 20 | Maximum results |
| `sort_order` | string | no | desc | `asc` or `desc` |
| `show_functions` | boolean | no | false | Include per-function breakdown |
#### `detect_smells`
Detect code smells: long functions, deep nesting, magic numbers, complex conditionals, long parameter lists.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | File or directory path |
| `recursive` | boolean | no | true | Recurse directories |
| `min_severity` | string | no | low | `low`, `medium`, `high`, `critical` |
| `thresholds` | object | no | | `{max_statements: 50, max_nesting: 4, max_parameters: 5, max_cognitive: 15}` |
| `smell_types` | string[] | no | all | `long_function`, `deep_nesting`, `magic_number`, `complex_conditional`, `long_parameter_list` |
#### `analyze_business_logic`
Analyze files for business logic issues using 33 analyzers (20 business logic + 13 CWE-based security).
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | File or directory path |
| `analyzers` | string[] | no | all | Filter specific analyzers (see below) |
| `min_severity` | string | no | info | `info`, `low`, `medium`, `high`, `critical` |
| `recursive` | boolean | no | true | Recurse directories |
| `format` | string | no | summary | `summary`, `detailed`, `json` |
Business logic analyzers: `callback_hell`, `missing_error_handling`, `silent_error_case`, `swallowing_exception`, `hardcoded_value`, `n_plus_one_query`, `inefficient_filter`, `unmanaged_task`, `telemetry_in_recursive_function`, `missing_telemetry_for_external_http`, `sync_over_async`, `direct_struct_update`, `missing_handle_async`, `blocking_in_plug`, `missing_telemetry_in_auth_plug`, `missing_telemetry_in_liveview_mount`, `missing_telemetry_in_oban_worker`, `missing_preload`, `inline_javascript`, `missing_throttle`.
CWE-based security analyzers: `sql_injection` (CWE-89), `xss_vulnerability` (CWE-79), `ssrf_vulnerability` (CWE-918), `path_traversal` (CWE-22), `insecure_direct_object_reference` (CWE-639), `missing_authentication` (CWE-306), `missing_authorization` (CWE-862), `incorrect_authorization` (CWE-863), `missing_csrf_protection` (CWE-352), `sensitive_data_exposure` (CWE-200), `unrestricted_file_upload` (CWE-434), `improper_input_validation` (CWE-20), `toctou` (CWE-367).
---
### Dependency and Dead Code Analysis
#### `analyze_dependencies`
Analyze module dependencies -- coupling metrics, circular dependencies, relationships.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `module` | string | no | all | Module name to analyze |
| `include_transitive` | boolean | no | false | Include transitive dependencies |
| `format` | string | no | summary | `summary`, `detailed`, `json` |
#### `find_circular_dependencies`
Find circular dependencies in the codebase.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `scope` | string | no | module | `module` or `function` |
| `min_cycle_length` | integer | no | 2 | Minimum cycle length |
| `limit` | integer | no | 100 | Maximum cycles to return |
#### `coupling_report`
Generate coupling metrics report with afferent/efferent coupling and instability.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `format` | string | no | text | `text`, `json`, `markdown` |
| `sort_by` | string | no | instability | `name`, `instability`, `afferent`, `efferent` |
| `include_transitive` | boolean | no | false | Include transitive metrics |
| `threshold` | integer | no | 0 | Minimum total coupling (0 = show all) |
#### `find_dead_code`
Find potentially unused code (functions with no callers) with confidence scoring.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `scope` | string | no | all | `exports`, `private`, `all`, `modules` |
| `min_confidence` | number | no | 0.5 | Confidence threshold (0.0-1.0) |
| `exclude_tests` | boolean | no | true | Exclude test modules |
| `include_callbacks` | boolean | no | false | Include potential callbacks |
| `format` | string | no | summary | `summary`, `detailed`, `suggestions` |
#### `analyze_dead_code_patterns`
Analyze files for intraprocedural dead code patterns (unreachable code, constant conditionals) using AST analysis.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | File path or directory |
| `min_confidence` | string | no | low | `low`, `medium`, `high` |
| `format` | string | no | summary | `summary`, `detailed`, `json` |
#### `analyze_impact`
Analyze the impact of changing a function or module via graph traversal.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `target` | string | yes | | `Module.function/arity` or `Module` |
| `depth` | integer | no | 5 | Maximum traversal depth |
| `include_tests` | boolean | no | true | Include test files |
| `format` | string | no | summary | `summary`, `detailed`, `json` |
---
### Duplicate Detection
#### `find_duplicates`
Find code duplicates using AST-based clone detection (Type I-IV) via Metastatic. Works across languages.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | File or directory (comma-separated for comparison) |
| `threshold` | number | no | 0.8 | Similarity threshold for Type III clones |
| `recursive` | boolean | no | true | Recurse directories |
| `format` | string | no | summary | `summary`, `detailed`, `json` |
| `exclude_patterns` | string[] | no | `[_build, deps, .git]` | Exclusion patterns |
#### `find_similar_code`
Find semantically similar code using embedding-based similarity.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `threshold` | number | no | 0.95 | Similarity threshold |
| `limit` | integer | no | 100 | Maximum pairs to return |
| `node_type` | string | no | function | `function` or `module` |
| `format` | string | no | summary | `summary`, `detailed`, `json` |
---
### Security
#### `scan_security`
Scan for security vulnerabilities: injection, unsafe deserialization, hardcoded secrets, weak crypto.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | File or directory path |
| `recursive` | boolean | no | true | Recurse directories |
| `min_severity` | string | no | low | `low`, `medium`, `high`, `critical` |
| `categories` | string[] | no | all | `injection`, `unsafe_deserialization`, `hardcoded_secret`, `weak_cryptography`, `insecure_protocol` |
#### `security_audit`
Generate comprehensive security audit report with CWE mapping and recommendations.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | Directory path to audit |
| `format` | string | no | text | `json`, `markdown`, `text` |
| `min_severity` | string | no | low | `low`, `medium`, `high`, `critical` |
#### `check_secrets`
Scan for hardcoded secrets (API keys, passwords, tokens) in source code.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | File or directory path |
| `recursive` | boolean | no | true | Recurse directories |
#### `analyze_security_issues`
Run all 13 CWE-based security analyzers: SQL injection, XSS, SSRF, path traversal, authentication/authorization issues, CSRF, data exposure, etc.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | File or directory path |
| `min_severity` | string | no | low | `info`, `low`, `medium`, `high`, `critical` |
| `recursive` | boolean | no | true | Recurse directories |
| `categories` | string[] | no | all | `injection`, `authentication`, `authorization`, `data_exposure`, `input_validation`, `race_condition` |
| `format` | string | no | summary | `summary`, `detailed`, `json` |
---
### Semantic Analysis
#### `semantic_operations`
Extract semantic operations (OpKind) from code -- identifies database, auth, HTTP, cache, queue, file, and external API operations with framework-specific patterns.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | File or directory path |
| `domains` | string[] | no | all | `db`, `http`, `auth`, `cache`, `queue`, `file`, `external_api` |
| `recursive` | boolean | no | true | Recurse directories |
| `include_security` | boolean | no | true | Include security-relevant operations |
| `format` | string | no | summary | `summary`, `detailed`, `json` |
#### `semantic_analysis`
Full semantic analysis combining OpKind extraction with security assessment.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | File or directory path |
| `recursive` | boolean | no | true | Recurse directories |
| `include_operations` | boolean | no | true | Include operation breakdown by domain |
| `include_security` | boolean | no | true | Include security analysis |
| `format` | string | no | summary | `summary`, `detailed`, `json` |
---
### RAG (Retrieval-Augmented Generation)
All RAG tools require an AI provider to be configured (DeepSeek, OpenAI, Anthropic, or Ollama).
#### `rag_query`
Query codebase using RAG with AI.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | yes | | Natural language query about the codebase |
| `limit` | integer | no | 10 | Max code snippets to retrieve |
| `include_code` | boolean | no | true | Include full code snippets |
| `provider` | string | no | default | `deepseek_r1`, `openai`, `anthropic`, `ollama` |
#### `rag_explain`
Explain code using RAG with AI assistance.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `target` | string | yes | — | File path or Module’s function |
| `aspect` | string | no | all | `purpose`, `complexity`, `dependencies`, `all` |
#### `rag_suggest`
Suggest code improvements using RAG with AI.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `target` | string | yes | | File path or function identifier |
| `focus` | string | no | all | `performance`, `readability`, `testing`, `security`, `all` |
#### `rag_query_stream`
Same as `rag_query` but uses streaming internally. Returns complete result.
Additional parameter: `show_chunks` (boolean, default: false) -- include intermediate chunks for debugging.
#### `rag_explain_stream`
Same as `rag_explain` with internal streaming. Additional: `show_chunks`.
#### `rag_suggest_stream`
Same as `rag_suggest` with internal streaming. Additional: `show_chunks`.
#### `validate_with_ai`
Validate code with AI-enhanced error explanations and fix suggestions.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `content` | string | yes | | Code content to validate |
| `path` | string | no | | File path (for language detection) |
| `language` | string | no | auto | `elixir`, `erlang`, `python`, `javascript`, `typescript` |
| `ai_explain` | boolean | no | true | Enable AI explanations |
| `surrounding_lines` | integer | no | 3 | Context lines around errors |
---
### AI and Embeddings
#### `get_embeddings_stats`
Get statistics about indexed embeddings. No parameters.
#### `get_ai_usage`
Get AI provider usage statistics (requests, tokens, costs).
| Parameter | Type | Required | Description |
|---|---|---|---|
| `provider` | string | no | Filter by `openai`, `anthropic`, `deepseek_r1`, `ollama` |
#### `get_ai_cache_stats`
Get AI response cache statistics and hit rates. No parameters.
#### `clear_ai_cache`
Clear AI response cache.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `operation` | string | no | `query`, `explain`, `suggest`, or `all` |
---
### Agent
The agent system provides conversational analysis sessions with persistent context.
#### `agent_analyze`
Analyze a project and generate an AI-polished report. Creates a session for follow-up conversation.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `path` | string | yes | | Project root path |
| `provider` | string | no | deepseek_r1 | AI provider |
| `include_suggestions` | boolean | no | true | Include refactoring suggestions |
| `skip_embeddings` | boolean | no | false | Skip embeddings for faster analysis |
Returns a `session_id` for use with `agent_chat`.
#### `agent_chat`
Continue conversation with the agent in an existing session.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `session_id` | string | yes | Session ID from `agent_analyze` |
| `message` | string | yes | User message or question |
| `provider` | string | no | AI provider override |
#### `agent_session_info`
Get information about an agent session.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `session_id` | string | yes | Session ID |
#### `agent_list_sessions`
List all active agent sessions.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `limit` | integer | no | 20 | Maximum sessions |
#### `agent_clear_session`
End and clear an agent session.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `session_id` | string | yes | Session ID |
---
## Resources
Resources provide read-only access to Ragex's internal state. Read via `resources/read` with the resource URI.
```json
{"jsonrpc":"2.0","method":"resources/read","params":{"uri":"ragex://graph/stats"},"id":1}
```
### `ragex://graph/stats` -- Graph Statistics
Comprehensive knowledge graph statistics including node/edge counts, PageRank scores, and centrality metrics.
Returns: `node_count`, `node_counts_by_type`, `edge_count`, `average_degree`, `density`, `top_by_pagerank`, `top_by_degree`.
### `ragex://cache/status` -- Cache Status
Embedding cache statistics including hit rates, file tracking status, and disk usage.
Returns: `cache_enabled`, `cache_file`, `cache_size_bytes`, `cache_valid`, `embeddings_count`, `model_name`, `last_saved`, `tracked_files`, `changed_files`, `unchanged_files`, `stale_entities_count`.
### `ragex://model/config` -- Model Configuration
Active embedding model configuration including name, dimensions, capabilities, and readiness.
Returns: `model_name`, `dimensions`, `ready`, `memory_usage_mb`, `capabilities` (`supports_batch`, `supports_normalization`, `local_inference`), `parameters` (`max_sequence_length`, `pooling`).
### `ragex://project/index` -- Project Index
Index of all tracked files with metadata, language distribution, and LOC statistics.
Returns: `total_files`, `tracked_files` (first 100 with `path`, `content_hash`, `analyzed_at`, `size_bytes`, `language`), `language_distribution`, `recently_changed`, `changed_files_count`, `total_entities`, `entities_by_type`.
### `ragex://algorithms/catalog` -- Algorithm Catalog
Catalog of available graph algorithms with parameters, complexity, and use cases.
Includes: `pagerank`, `betweenness_centrality`, `closeness_centrality`, `degree_centrality`, `find_paths`, `detect_communities`. Each with parameters, complexity notation, and use case descriptions.
### `ragex://analysis/summary` -- Analysis Summary
Pre-computed analysis summary including key modules, architectural insights, and community structure.
Returns: `overview` (total_nodes, total_edges, average_degree, density), `key_modules` (by PageRank), `bottlenecks` (by betweenness centrality), `communities` (top 10 by size), `community_count`.
---
## Prompts
Prompts are templated high-level workflows that compose multiple tools. Retrieved via `prompts/get`.
```json
{"jsonrpc":"2.0","method":"prompts/get","params":{"name":"analyze_architecture","arguments":{"path":"/path/to/project"}},"id":1}
```
### `analyze_architecture`
Comprehensive architectural analysis: community detection, centrality metrics, structural insights.
| Argument | Required | Description |
|---|---|---|
| `path` | yes | Path to analyze |
| `depth` | no | `shallow` (quick) or `deep` (detailed with betweenness centrality and communities) |
### `find_impact`
Analyze the impact and importance of a function: callers, importance scores, refactoring risk.
| Argument | Required | Description |
|---|---|---|
| `module` | yes | Module name |
| `function` | yes | Function name |
| `arity` | yes | Function arity |
### `explain_code_flow`
Explain execution flow between two functions with narrative description and code context.
| Argument | Required | Description |
|---|---|---|
| `from_function` | yes | Starting function (`Module.function/arity`) |
| `to_function` | yes | Target function (`Module.function/arity`) |
| `context_lines` | no | Context lines to show (default: 3) |
### `find_similar_code`
Find code similar to a natural language description using hybrid search.
| Argument | Required | Description |
|---|---|---|
| `description` | yes | Natural language description |
| `file_type` | no | Language filter (e.g., `elixir`, `python`) |
| `top_k` | no | Number of results (default: 5) |
### `suggest_refactoring`
Analyze code and suggest refactoring opportunities.
| Argument | Required | Description |
|---|---|---|
| `target_path` | yes | Path to analyze |
| `focus` | no | `modularity`, `coupling`, or `complexity` |
### `safe_rename`
Preview and optionally perform safe semantic renaming with impact analysis.
| Argument | Required | Description |
|---|---|---|
| `type` | yes | `function` or `module` |
| `old_name` | yes | Current name |
| `new_name` | yes | New name |
| `scope` | no | `module` or `project` (default: project) |
---
## Supported Languages
- **Elixir** (.ex, .exs) -- full support including AST-aware refactoring
- **Erlang** (.erl, .hrl) -- analysis, search, quality metrics
- **Python** (.py) -- analysis, search, quality metrics
- **JavaScript** (.js, .jsx, .mjs) -- analysis, search, quality metrics
- **TypeScript** (.ts, .tsx) -- analysis, search, quality metrics
## Connection
**stdio**: Launch with `mix run --no-halt`. Send JSON-RPC 2.0 messages to stdin, read responses from stdout. Used by MCP-compatible clients (Claude Desktop, etc.).
**Unix socket**: Connect to `/tmp/ragex_mcp.sock`. Each request is a single JSON-RPC 2.0 line terminated by `\n`. Used by editor integrations (NeoVim, LunarVim).
```bash
# Example: ping the socket server
(echo '{"jsonrpc":"2.0","method":"ping","id":1}'; sleep 3) | socat -T5 STDIO UNIX-CONNECT:/tmp/ragex_mcp.sock
```
