Ragex MCP Resources

Resources provide read-only access to Ragex's internal state through the Model Context Protocol. They enable LLMs to observe and query Ragex's knowledge graph, embeddings cache, model configuration, and analysis results.

Overview

Resources are accessed via URIs with the format: ragex://<category>/<resource>

All resources return JSON data with MIME type application/json.

Available Resources

1. Graph Statistics (ragex://graph/stats)

Provides comprehensive statistics about the knowledge graph.

Returns:

{
  "node_count": 1234,
  "node_counts_by_type": {
    "module": 150,
    "function": 1084
  },
  "edge_count": 2500,
  "average_degree": 2.03,
  "density": 0.0016,
  "top_by_pagerank": [
    {
      "node_id": "MyApp.Core.start/2",
      "pagerank_score": 0.015432
    }
  ],
  "top_by_degree": [
    {
      "node_id": "MyApp.Utils.log/1",
      "in_degree": 85,
      "out_degree": 3,
      "total_degree": 88
    }
  ]
}

Use Cases:

• Quick overview of codebase size and complexity
• Identify most important modules and functions
• Assess code connectivity and coupling

2. Cache Status (ragex://cache/status)

Reports on embedding cache health and file tracking status.

Returns:

{
  "cache_enabled": true,
  "cache_file": "/home/user/.cache/ragex/project_abc123/embeddings.ets",
  "cache_size_bytes": 15728640,
  "cache_valid": true,
  "embeddings_count": 1234,
  "model_name": "all_mini_lm_l6_v2",
  "last_saved": 1704376800,
  "tracked_files": 45,
  "changed_files": 2,
  "unchanged_files": 43,
  "stale_entities_count": 8
}

Use Cases:

• Determine if cache refresh is needed
• Monitor embedding regeneration status
• Track file changes since last analysis

3. Model Configuration (ragex://model/config)

Returns active embedding model details and capabilities.

Returns:

{
  "model_name": "sentence-transformers/all-MiniLM-L6-v2",
  "dimensions": 384,
  "ready": true,
  "memory_usage_mb": 400,
  "capabilities": {
    "supports_batch": true,
    "supports_normalization": true,
    "local_inference": true
  },
  "parameters": {
    "max_sequence_length": 512,
    "pooling": "mean"
  }
}

Use Cases:

• Verify model readiness before semantic operations
• Check model compatibility for cache migration
• Estimate resource requirements

4. Project Index (ragex://project/index)

Lists all tracked files with metadata and language distribution.

Returns:

{
  "total_files": 45,
  "tracked_files": [
    {
      "path": "/project/lib/my_app/core.ex",
      "content_hash": "a1b2c3d4...",
      "analyzed_at": 1704376500,
      "size_bytes": 2048,
      "language": "elixir"
    }
  ],
  "language_distribution": {
    "elixir": 38,
    "python": 5,
    "javascript": 2
  },
  "recently_changed": ["/project/lib/my_app/utils.ex"],
  "changed_files_count": 2,
  "total_entities": 1234,
  "entities_by_type": {
    "modules": 150,
    "functions": 1084
  }
}

Use Cases:

• Discover all analyzed files in project
• Monitor file change activity
• Understand language composition

5. Algorithm Catalog (ragex://algorithms/catalog)

Comprehensive catalog of available graph algorithms with parameters and complexity.

Returns:

{
  "algorithms": [
    {
      "name": "pagerank",
      "category": "centrality",
      "description": "Importance scoring based on call relationships",
      "parameters": {
        "damping": {
          "type": "float",
          "default": 0.85,
          "description": "Damping factor"
        },
        "max_iterations": {
          "type": "integer",
          "default": 100,
          "description": "Maximum iterations"
        }
      },
      "complexity": "O(k * (n + m)) where k is iterations, n is nodes, m is edges",
      "use_cases": [
        "Identify most important functions in codebase",
        "Find architectural entry points",
        "Prioritize refactoring efforts"
      ]
    }
  ]
}

Algorithms Included:

• PageRank - Importance scoring
• Betweenness Centrality - Bridge/bottleneck identification
• Closeness Centrality - Central function identification
• Degree Centrality - Connection counting
• Find Paths - Call chain discovery
• Detect Communities - Architectural module discovery

Use Cases:

• Discover available algorithms and their parameters
• Understand complexity characteristics
• Select appropriate algorithm for analysis task

6. Analysis Summary (ragex://analysis/summary)

Pre-computed architectural analysis with key insights.

Returns:

{
  "overview": {
    "total_nodes": 1234,
    "total_edges": 2500,
    "average_degree": 2.03,
    "density": 0.0016
  },
  "key_modules": [
    {
      "node_id": "MyApp.Core",
      "importance": 0.025
    }
  ],
  "bottlenecks": [
    {
      "node_id": "MyApp.Router.dispatch/2",
      "betweenness_score": 0.12
    }
  ],
  "communities": [
    {
      "community_id": "1",
      "size": 150,
      "sample_members": ["MyApp.Auth", "MyApp.Auth.Token", "MyApp.Auth.User"]
    }
  ],
  "community_count": 8
}

Use Cases:

• Quick architectural overview
• Identify critical functions and bottlenecks
• Understand code organization and modularity

Usage Examples

Via MCP Protocol

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resources": [
      {
        "uri": "ragex://graph/stats",
        "name": "Graph Statistics",
        "description": "...",
        "mimeType": "application/json"
      }
    ]
  }
}

Reading a Resource

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "ragex://graph/stats"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "contents": [
      {
        "uri": "ragex://graph/stats",
        "mimeType": "application/json",
        "text": "{\"node_count\":1234,...}"
      }
    ]
  }
}

Best Practices

1. Cache Resources: Results are computed on-demand but can be expensive for large codebases
2. Check Model Readiness: Query model/config before semantic operations
3. Monitor Cache: Use cache/status to decide when to refresh embeddings
4. Combine Resources: Use multiple resources together for comprehensive analysis

Error Handling

Resources return errors in standard MCP format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error: Unknown resource: graph/invalid"
  }
}

Common Errors:

• Invalid URI scheme (must be ragex://)
• Unknown category or resource
• Resource computation failure (e.g., empty graph)

Performance

For large codebases (>10k entities), analysis/summary may take several seconds.

See Also

• PROMPTS.md - High-level workflow templates
• ALGORITHMS.md - Detailed algorithm documentation
• CONFIGURATION.md - Cache and model configuration