MCP Tools, Resources, and Prompts Reference

Ragex exposes 72 MCP tools, 6 resources, and 6 prompts via the Model Context Protocol 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

{"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.

analyze_directory

Recursively analyze all supported files in a directory, extracting code structure into the knowledge graph.

watch_directory

Start watching a directory for file changes and auto-reindex modified files.

unwatch_directory

Stop watching a directory.

list_watched

List all currently watched directories. No parameters.

Knowledge Graph Queries

query_graph

Query the knowledge graph for code entities and relationships.

list_nodes

List all nodes in the knowledge graph with optional filtering.

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.

find_paths

Find all paths (call chains) between two functions or modules.

Search

semantic_search

Search codebase using natural language queries via embedding-based semantic similarity.

hybrid_search

Advanced search combining symbolic graph queries with semantic similarity using Reciprocal Rank Fusion.

metaast_search

Search for semantically equivalent code constructs across languages using MetaAST analysis.

cross_language_alternatives

Suggest cross-language alternatives for a code construct.

expand_query

Expand a search query with semantic synonyms and cross-language terms.

find_metaast_pattern

Find all implementations of a MetaAST pattern across all languages.

Graph Algorithms

betweenness_centrality

Compute betweenness centrality to identify bridge/bottleneck functions using Brandes' algorithm.

closeness_centrality

Compute closeness centrality to identify central functions in the call graph.

detect_communities

Detect communities/clusters in the call graph to identify architectural modules.

export_graph

Export the call graph in visualization formats.

File Editing

edit_file

Safely edit a single file with automatic backup, syntax validation, and atomic operations.

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.

validate_edit

Preview validation of changes without applying them.

rollback_edit

Undo a recent edit by restoring from backup.

edit_history

Query backup history for a file.

read_file

Read the contents of a source file with line numbers.

Refactoring

refactor_code

Semantic refactoring operations using AST analysis and knowledge graph.

advanced_refactor

Advanced refactoring operations with 8 operation types.

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.

refactor_conflicts

Check for conflicts before applying a refactoring operation.

undo_refactor

Undo the most recent refactoring operation.

refactor_history

List refactoring operation history with timestamps and file counts.

visualize_impact

Visualize the impact of refactoring changes.

suggest_refactorings

Analyze code and generate prioritized refactoring suggestions.

explain_suggestion

Get detailed explanation for a specific refactoring suggestion.

estimate_refactoring_effort

Estimate effort required for a refactoring operation.

risk_assessment

Calculate risk score for changing a function or module.

Code Quality and Analysis

analyze_quality

Analyze code quality metrics (complexity, purity, LOC) using Metastatic.

quality_report

Generate a comprehensive quality report for analyzed files.

find_complex_code

Find files or functions exceeding complexity thresholds.

detect_smells

Detect code smells: long functions, deep nesting, magic numbers, complex conditionals, long parameter lists.

analyze_business_logic

Analyze files for business logic issues using 33 analyzers (20 business logic + 13 CWE-based security).

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.

find_circular_dependencies

Find circular dependencies in the codebase.

coupling_report

Generate coupling metrics report with afferent/efferent coupling and instability.

find_dead_code

Find potentially unused code (functions with no callers) with confidence scoring.

analyze_dead_code_patterns

Analyze files for intraprocedural dead code patterns (unreachable code, constant conditionals) using AST analysis.

analyze_impact

Analyze the impact of changing a function or module via graph traversal.

Duplicate Detection

find_duplicates

Find code duplicates using AST-based clone detection (Type I-IV) via Metastatic. Works across languages.

find_similar_code

Find semantically similar code using embedding-based similarity.

Security

scan_security

Scan for security vulnerabilities: injection, unsafe deserialization, hardcoded secrets, weak crypto.

security_audit

Generate comprehensive security audit report with CWE mapping and recommendations.

check_secrets

Scan for hardcoded secrets (API keys, passwords, tokens) in source code.

analyze_security_issues

Run all 13 CWE-based security analyzers: SQL injection, XSS, SSRF, path traversal, authentication/authorization issues, CSRF, data exposure, etc.

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.

semantic_analysis

Full semantic analysis combining OpKind extraction with security assessment.

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.

rag_explain

Explain code using RAG with AI assistance.

rag_suggest

Suggest code improvements using RAG with AI.

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.

AI and Embeddings

get_embeddings_stats

Get statistics about indexed embeddings. No parameters.

get_ai_usage

Get AI provider usage statistics (requests, tokens, costs).

get_ai_cache_stats

Get AI response cache statistics and hit rates. No parameters.

clear_ai_cache

Clear AI response cache.

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.

Returns a session_id for use with agent_chat.

agent_chat

Continue conversation with the agent in an existing session.

agent_session_info

Get information about an agent session.

agent_list_sessions

List all active agent sessions.

agent_clear_session

End and clear an agent session.

Resources

Resources provide read-only access to Ragex's internal state. Read via resources/read with the resource URI.

{"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.

{"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.

find_impact

Analyze the impact and importance of a function: callers, importance scores, refactoring risk.

explain_code_flow

Explain execution flow between two functions with narrative description and code context.

find_similar_code

Find code similar to a natural language description using hybrid search.

suggest_refactoring

Analyze code and suggest refactoring opportunities.

safe_rename

Preview and optionally perform safe semantic renaming with impact analysis.

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).

# Example: ping the socket server
(echo '{"jsonrpc":"2.0","method":"ping","id":1}'; sleep 3) | socat -T5 STDIO UNIX-CONNECT:/tmp/ragex_mcp.sock