Ranex

You deploy and use the Ranex MCP Server to enable AI-assisted governance and automated checks for your Python projects. It provides a suite of tools to validate architecture, enforce state machine rules, run security scans, and integrate AI helpers through a lightweight, local MCP server.

How to use

You interact with the MCP server by running the MCP binary and connecting your client or Cursor-based workflow to the server. The server exposes a set of tools that you can invoke from your AI-enabled workflows to perform architecture validation, state machine checks, security scans, import validation, and other governance tasks. Use the provided CLI and MCP integration points to perform checks as part of your development and deployment pipelines.

How to install

Prerequisites: ensure you have Python and a compatible shell available on your system. You will also use a simple installer to create an isolated environment for running the MCP components.

Step 1: Run the installer to create a virtual environment.

./install.sh

Step 2: Activate the virtual environment.

source .venv/bin/activate

Step 3: Install the core packages manually if you prefer a direct approach.

python3 -m venv .venv
source .venv/bin/activate
pip install ranex_core-0.0.1-cp312-cp312-manylinux_2_28_x86_64.whl

Step 4: Initialize your project and run a security and architecture scan.

cd your-project
ranex init
ranex scan

Step 5: Set up the MCP server for AI integration.

# Install MCP server binary to a system path
cp ranex_mcp /usr/local/bin/

# Add to Cursor configuration to expose the MCP server
{
  "mcpServers": {
    "ranex": {
      "command": "/usr/local/bin/ranex_mcp"
    }
  }
}

Additional setup and configuration

The MCP server provides a range of tools that can be used to integrate governance checks into your AI workflows. In particular, you can enable state machine validation, security scanning, and import validation as part of your development lifecycle.

Key MCP tools exposed by the server include: validate_file_structure, validate_transition, check_import, security_scan, detect_antipattern, list_db_aliases, validate_sql, validate_intent, check_function_exists, and get_active_persona.

Example usage snippets show how to configure state machine validation and to run scans as part of your automation.

# State machine example (YAML)
# app/features/orders/state.yaml
feature: orders
initial_state: Pending

states:
  Pending: { description: "New order" }
  Confirmed: { description: "Order confirmed" }
  Processing: { description: "Being prepared" }
  Shipped: { description: "In transit" }
  Delivered: { description: "Completed", terminal: true }
  Cancelled: { description: "Cancelled", terminal: true }

transitions:
  - { from: Pending, to: Confirmed }
  - { from: Pending, to: Cancelled }
  - { from: Confirmed, to: Processing }
  - { from: Processing, to: Shipped }
  - { from: Shipped, to: Delivered }

Troubleshooting and notes

If you encounter issues during installation or while running scans, verify that the virtual environment is active and that the MCP binary is in your system PATH. Check that the Cursor or client configuration points to the correct MCP server command, and ensure the required tools are accessible in your workflow environment.

Available tools

validate_file_structure

Performs architecture validation to ensure project structure aligns with defined architectural rules.

validate_transition

Checks state machine transitions to prevent illegal or skipped steps.

check_import

Detects typosquatting and suspicious imports to improve dependency safety.

security_scan

Runs a SAST-like scan with 7 patterns to find common security issues.

detect_antipattern

Identifies code smells through 5 antipattern patterns to improve code quality.

list_db_aliases

Lists available database aliases and connection configurations.

validate_sql

Validates SQL usage and queries for correctness and safety.

validate_intent

Assesses ambiguity in prompts or intents to improve alignment.

check_function_exists

Performs semantic checks to verify function or endpoint presence.

get_active_persona

Retrieves the active AI persona for alignment checks.