Search documentation of Ragex

# Ragex MCP Resources

View Source

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

Resource | Typical Response Time | Notes
--- | --- | ---
`graph/stats` | 50-200ms | Depends on graph size
`cache/status` | <10ms | File system check
`model/config` | <5ms | In-memory data
`project/index` | 10-50ms | Depends on tracked files
`algorithms/catalog` | <5ms | Static data
`analysis/summary` | 200-1000ms | Runs community detection

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

← Previous Page MCP Prompts
Next Page → Streaming Notifications