@run-iq/mcp-server

MCP (Model Context Protocol) server that exposes the Parametric Policy Engine (PPE) to LLMs. Connects to Claude Desktop, Cursor, VS Code, and any MCP-compatible client via stdio.

Plugin-aware: the server dynamically adapts its tools, resources, and prompts to whatever plugins are loaded — zero hardcoding required.

Installation

npm install -g @run-iq/mcp-server

Or run directly with npx:

npx @run-iq/mcp-server

Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "run-iq": {
      "command": "npx",
      "args": ["@run-iq/mcp-server"]
    }
  }
}

Cursor / VS Code

{
  "mcpServers": {
    "run-iq": {
      "command": "npx",
      "args": ["@run-iq/mcp-server"]
    }
  }
}

Custom Plugins

The server is 100% domain-agnostic by default. You MUST attach plugins to give the AI engine capabilities. You can load plugins from NPM packages or from a local directory.

Option 1: Load from NPM (Recommended) Provides dynamic imports directly from node_modules or global installations.

{
  "mcpServers": {
    "run-iq": {
      "command": "npx",
      "args": ["@run-iq/mcp-server", "--plugin", "@run-iq/plugin-fiscal", "--plugin", "@my-org/payroll"]
    }
  }
}

Option 2: Load local bundles Load compiled javascript files from a local directory:

{
  "mcpServers": {
    "run-iq": {
      "command": "npx",
      "args": ["@run-iq/mcp-server", "--plugins-dir", "/path/to/plugins"]
    }
  }
}

Each .js or .mjs file in the directory must export a PluginBundle:

import type { PluginBundle } from '@run-iq/plugin-sdk';

const bundle: PluginBundle = {
  plugin: new MyPlugin(),
  descriptor: myDescriptor,
  dsls: [new MyDslEvaluator()],
};

export default bundle;

Tools (8)

| Tool | Description | |------|-------------| | evaluate | Evaluate rules against input data (always dry-run) | | simulate | Compare N scenarios side-by-side with the same rules | | validate_rules | Verify rule structure, checksum, model params, and plugin fields | | create_rule | Generate a valid Rule JSON with auto-computed SHA-256 checksum | | inspect_rule | Analyze a single rule in detail (validity, active status, errors) | | explain_result | Human-readable explanation of an EvaluationResult | | list_models | List available calculation models with parameter schemas | | create_checksum | Compute SHA-256 checksum for a params object |

All tools with plugin-specific fields (e.g. create_rule, validate_rules) dynamically adapt their schemas based on loaded plugins.

Resources (3)

| URI | Description | |-----|-------------| | schema://rules | Complete rule schema: base fields, plugin extensions, model params, input variables, JSONLogic syntax, and examples | | models://catalog | Markdown documentation of all calculation models with parameters and usage examples | | plugins://loaded | Information about loaded plugins, DSL evaluators, and descriptor status |

Prompts (2)

| Prompt | Description | |--------|-------------| | domain-expert | Domain-specific expertise adapted to loaded plugins: scenario comparison, result explanation, recommendations | | analyze-text | Translate regulatory/policy text into Run-IQ rule definitions with all required plugin fields |

Both prompts dynamically inject plugin metadata, guidelines, and examples.

Plugin-aware architecture

The server adapts to any loaded plugin through the PluginDescriptor contract (from @run-iq/plugin-sdk):

Plugin loads → descriptor provides metadata → server adapts everything

• Tools: create_rule adds plugin-required fields to its Zod schema. validate_rules checks plugin-specific constraints.
• Resources: schema://rules documents plugin extension fields, input variables, and examples.
• Prompts: domain-expert becomes a fiscal/social/payroll expert based on what's loaded. analyze-text injects plugin-specific model guidance and examples.

Default behavior

By default, the server loads an empty engine. You must specify --plugin (NPM package) or --plugins-dir (local folder) to inject calculation models and rules. For example, passing --plugin @run-iq/plugin-fiscal provides the 6 standard tax calculation models.

Writing a custom plugin

A plugin describes itself via PluginDescriptor:

import type { PluginDescriptor } from '@run-iq/plugin-sdk';

export const socialDescriptor: PluginDescriptor = {
  name: '@run-iq/plugin-social',
  version: '0.1.0',
  domainLabel: 'social',
  description: 'Social benefits calculation plugin',
  ruleExtensions: [
    { name: 'benefitType', type: 'string', required: true,
      enum: ['ALLOCATION', 'AIDE', 'EXONERATION'], description: '...' },
  ],
  inputFields: [
    { name: 'householdIncome', type: 'number', description: '...', examples: [150000] },
  ],
  examples: [/* concrete rule examples */],
  promptGuidelines: [
    'Consider household composition when creating rules',
    'Use THRESHOLD model for means-tested benefits',
  ],
};

The MCP server will automatically expose benefitType in create_rule, validate it in validate_rules, document it in schema://rules, and inject the guidelines into prompts.

Safety

• Always dry-run: the engine never persists snapshots — safe for AI experimentation
• Read-only: no mutations to external state
• Checksum verification: SHA-256 integrity checks on rule params

Requirements

• Node.js >= 20

License

MIT — Abdou-Raouf ATARMLA