iris-execute-mcp

jbrandtmse/iris-execute-mcp

3.3

If you are the rightful owner of iris-execute-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The IRIS Execute MCP Server offers a comprehensive suite of tools for seamless integration with InterSystems IRIS, providing capabilities for basic operations, compilation, and advanced unit testing.

Tools
9
Resources
0
Prompts
0

IRIS Execute MCP Server

Complete MCP Integration for InterSystems IRIS - 8 Development Tools! 🎉

The IRIS Execute MCP server provides 8 fully functional tools for comprehensive IRIS development integration, including basic operations, compilation tools, and advanced unit testing capabilities with a custom VS Code-friendly TestRunner.

Current Tool Status ✅

Basic Tools (5):

  • ✅ execute_command: Direct ObjectScript execution with I/O CAPTURE - Real output capture!
  • ✅ execute_classmethod: Dynamic class method invocation with full parameter support
  • ✅ get_global: Dynamic global retrieval with complex subscripts
  • ✅ set_global: Dynamic global setting with verification
  • ✅ get_system_info: Real-time IRIS system information

Compilation Tools (2):

  • ✅ compile_objectscript_class: Compile one or more ObjectScript classes with error reporting
  • ✅ compile_objectscript_package: Compile all classes in a package recursively

Unit Testing Tool (1):

  • ✅ execute_unit_tests: Lightning-fast unit test execution using DirectTestRunner (VS Code friendly!)

Installation

Prerequisites

  • Python 3.8+
  • InterSystems IRIS 2024.3 or later
  • VS Code with Cline extension

Step 1: Clone and Setup

# Clone the repository
git clone https://github.com/jbrandtmse/iris-execute-mcp.git
cd iris-execute-mcp

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Step 2: Configure Environment

Create a .env file (copy from .env.example):

IRIS_HOSTNAME=localhost
IRIS_PORT=1972
IRIS_NAMESPACE=HSCUSTOM
IRIS_USERNAME=*username*
IRIS_PASSWORD=*password*

Step 3: Install IRIS Classes

  1. Open IRIS Studio or VS Code with ObjectScript extension
  2. Import classes from src/ExecuteMCP/Core/ and src/ExecuteMCP/TestRunner/ directories
  3. Compile the ExecuteMCP package:
Do $System.OBJ.CompilePackage("ExecuteMCP")

Cline MCP Configuration

Step 1: Open Cline MCP Settings

  1. Open VS Code with Cline extension
  2. Open Settings (Ctrl + ,)
  3. Search for "MCP"
  4. Find "Cline > MCP: Servers"
  5. Click "Edit in settings.json"

Step 2: Configuration (All 8 Tools)

Add this to your Cline MCP settings:

{
  "iris-execute-mcp": {
    "autoApprove": [
      "execute_command",
      "execute_classmethod",
      "get_global",
      "set_global",
      "get_system_info",
      "compile_objectscript_class",
      "compile_objectscript_package",
      "execute_unit_tests"
    ],
    "disabled": false,
    "timeout": 60,
    "type": "stdio",
    "command": "C:/iris-execute-mcp/venv/Scripts/python.exe",
    "args": ["C:/iris-execute-mcp/iris_execute_mcp.py"],
    "env": {
      "IRIS_HOSTNAME": "localhost",
      "IRIS_PORT": "1972",
      "IRIS_NAMESPACE": "HSCUSTOM",
      "IRIS_USERNAME": "*username*",
      "IRIS_PASSWORD": "*password*"
    }
  }
}

Key Configuration Details:

✅ Server Name: iris-execute-mcp
✅ Script Name: iris_execute_mcp.py (consolidated server with all features)
✅ 8 Tools: 5 basic + 2 compilation + 1 unit testing tool
✅ Virtual Environment: Uses isolated dependencies for reliability
✅ Environment Variables: Proper IRIS connection configuration
✅ Auto-Approve: All 8 tools approved for seamless AI workflows

Step 3: Restart and Test

  1. Save the settings.json file
  2. Restart VS Code completely
  3. Open a new Cline chat
  4. Test functionality:
    • "Show me IRIS system information"
    • "Execute: WRITE $ZV"
    • "Execute unit tests for ExecuteMCP.Test.SampleUnitTest"

Verification

Test Server Startup

# Navigate to project directory
cd C:/iris-execute-mcp

# Activate virtual environment
venv\Scripts\activate

# Test server startup
python iris_execute_mcp.py

Expected output:

INFO - Starting IRIS Execute FastMCP Server
INFO - IRIS Available: True
INFO - ✅ IRIS connectivity test passed
INFO - 🚀 FastMCP server ready for connections

Test Tools Directly

# Validate MVP implementation
python validate_mvp.py

Tool Documentation

Basic Tools

execute_command

Execute ObjectScript commands with I/O capture:

# Examples:
"Execute: WRITE $ZV"
→ Returns actual IRIS version string

"Execute: SET ^MyGlobal = 123"
→ Returns "Command executed successfully"
execute_classmethod

Dynamically invoke ObjectScript class methods:

# Examples:
"Call GetVersion on %SYSTEM.Version"
→ Returns IRIS version details

"Call ABS on %SYSTEM.SQL.Functions with parameter -456"
→ Returns 456
get_global / set_global

Manage IRIS globals dynamically:

# Set a global
"Set global ^MyApp('Config','Version') to '1.0.0'"

# Get a global
"Get the value of ^MyApp('Config','Version')"
get_system_info

Retrieve IRIS system information:

"What version of IRIS is running?"
→ Returns version, namespace, timestamp

Compilation Tools

compile_objectscript_class

Compile one or more ObjectScript classes with comprehensive error reporting.

IMPORTANT: Class names MUST include the .cls suffix for proper compilation.

# Compile single class (note the .cls suffix)
"Compile ObjectScript class MyPackage.MyClass.cls"
→ Returns compilation status and any errors

# Compile multiple classes (all with .cls suffix)
"Compile classes MyPackage.Class1.cls, MyPackage.Class2.cls"
→ Returns status for each class

# Custom compilation flags
"Compile MyPackage.MyClass.cls with flags 'bckry'"
→ b=rebuild, c=compile, k=keep source, r=recursive, y=display info

# Note: If .cls suffix is omitted, it will be automatically added
"Compile MyPackage.MyClass" → Internally becomes "MyPackage.MyClass.cls"
compile_objectscript_package

Compile all classes in a package recursively:

# Compile entire package
"Compile ObjectScript package MyPackage"
→ Compiles all classes in package and sub-packages

# With custom flags
"Compile package MyPackage with flags 'bc'"
→ Basic compile without recursion

Unit Testing Tool

execute_unit_tests

Execute tests using the DirectTestRunner instead of %UnitTest.Manager.

✅ 5,700x Performance Improvement!

This tool provides a VS Code-friendly alternative to the standard %UnitTest.Manager, eliminating file path dependencies and VS Code sync issues. The DirectTestRunner executes tests directly from compiled classes without filesystem interaction, achieving execution times of 6-21ms instead of the previous 60-120 second timeouts.

# Run all tests in a package
"Execute unit tests for ExecuteMCP.Test"
→ Executes all test classes in the package

# Run tests in a specific class
"Execute unit tests for ExecuteMCP.Test.SimpleTest"
→ Executes all test methods in the class

# Run a specific test method
"Execute unit tests for ExecuteMCP.Test.SimpleTest:TestAddition"
→ Executes only the specified test method

# Response includes:
# - Summary with pass/fail counts
# - Individual test results
# - Execution times
# - Full assertion details

Advantages over %UnitTest.Manager:

  • ✅ 5,700x faster: 6-21ms vs 60-120 seconds
  • ✅ No filesystem dependencies (works with VS Code auto-sync)
  • ✅ No ^UnitTestRoot configuration required
  • ✅ Executes from compiled classes directly
  • ✅ Full support for %UnitTest.TestCase and assertion macros
  • ✅ Clean JSON response format
  • ✅ Ultra-lightweight DirectTestRunner implementation

Architecture

Technology Stack

  • Python MCP Server: FastMCP framework with STDIO transport
  • IRIS Backend: ExecuteMCP.Core.Command, ExecuteMCP.Core.Compile, and ExecuteMCP.Core.DirectTestRunner classes
  • DirectTestRunner: Ultra-fast test execution bypassing %UnitTest.Manager complexity
  • I/O Capture: Global variable mechanism avoiding STDIO conflicts
  • Compilation Engine: $System.OBJ methods with comprehensive error handling

Key Innovations

  1. I/O Capture Breakthrough: Real output from WRITE commands via ^MCPCapture
  2. Dynamic Method Invocation: Call any ObjectScript class method by name
  3. DirectTestRunner: 5,700x faster than %UnitTest.Manager (6-21ms execution)
  4. Zero Timeout Architecture: All operations complete in <100ms

Performance Metrics

  • ✅ Command Execution: 0ms with I/O capture
  • ✅ Method Invocation: <10ms for complex calls
  • ✅ Global Operations: Sub-millisecond response
  • ✅ Unit Test Execution: 6-21ms (vs 60-120 seconds previously!)
  • ✅ System Info: <50ms full details

Troubleshooting

MCP Connection Issues

If you see "MCP error -32000: Connection closed":

  1. Restart VS Code completely
  2. Or disable/enable Cline extension
  3. Check server is running: python iris_execute_mcp.py

Tool Not Working

  1. Verify IRIS classes are compiled: 
    Do $System.OBJ.CompilePackage("ExecuteMCP")
  2. Check security privileges: 
    Write $SYSTEM.Security.Check("%Development","USE")
  3. Test backend directly in IRIS terminal

Path Issues

  • Use absolute paths in configuration
  • Verify virtual environment activation
  • Check Python path points to venv Python

Unit Test Issues

Test Discovery Problems
  • Symptom: Tests run but report "0 tests found"
  • Cause: Test classes not compiled in IRIS
  • Solution: 
    // Compile test classes (VS Code syncs but doesn't compile)
Do $System.OBJ.CompilePackage("ExecuteMCP.Test")
Test Spec Format
  • Supported Formats:
    • ExecuteMCP.Test - Run all tests in package
    • ExecuteMCP.Test.SampleUnitTest - Run all tests in class
    • ExecuteMCP.Test.SampleUnitTest:TestMethod - Run specific method

Advanced Usage

Combined Workflows

# Complete test workflow with compilation
1. "Compile ObjectScript package ExecuteMCP.Test"
2. "Execute unit tests for ExecuteMCP.Test.SampleUnitTest"
3. "Get global ^TestRunnerResults to see detailed results"

Understanding Test Results

The DirectTestRunner returns structured JSON with detailed test results:

{
  "status": "success",
  "summary": {
    "passed": 5,
    "failed": 1,
    "errors": 0,
    "skipped": 0,
    "total": 6
  },
  "tests": [
    {
      "class": "ExecuteMCP.Test.SimpleTest",
      "method": "TestAddition",
      "status": "passed",
      "duration": 0.001
    }
  ],
  "executionTime": 0.125
}

Contributing

Contributions welcome! Please ensure:

  • All tests pass
  • Code follows ObjectScript conventions
  • MCP tools have proper documentation
  • Changes are tested with Cline

License

MIT License - See LICENSE file for details

Version History

  • v3.1.3 (September 15, 2025): Enhanced DirectTestRunner with package-level testing support, cleaned up development files
  • v3.1.2 (September 15, 2025): Cleaned up duplicate TestManagerCreation() method in Wrapper.cls
  • v3.1.1 (September 15, 2025): Fixed ObjectScript assertion macro syntax ($$$AssertFalse → $$$AssertNotTrue), integrated Perplexity MCP for AI-powered research
  • v3.1.0 (January 11, 2025): DirectTestRunner implementation - 5,700x performance improvement!
  • v3.0.0 (January 9, 2025): Refactored to 8 development tools, removed deprecated WorkMgr async pattern
  • v2.4.0 (January 9, 2025): Added custom TestRunner MCP tool (10 tools total)
  • v2.3.1 (January 7, 2025): Added auto-prefix feature for unit test specifications
  • v2.3.0 (January 7, 2025): Fixed unit testing with WorkMgr pattern (9 tools total)
  • v2.2.0 (January 3, 2025): Added 2 compilation tools
  • v2.1.0 (December 30, 2024): Consolidated server with unit testing
  • v2.0.0: Added unit testing capabilities
  • v1.0.0: Initial 5 basic tools

Support

Status: ✅ All 8 tools operational with DirectTestRunner breakthrough
Last Updated: September 15, 2025