Home Applications iris-execute-mcp

iris-execute-mcp

InterSystems does not provide technical support for this project. Please contact its developer for the technical assistance.
0
0 reviews
0
Awards
48
Views
0
IPM installs
0
0
Details
Releases (2)
Reviews
Issues
MCP Server for executing methods, compiling classes and executing unit test in InterSystems IRIS

What's new in this version

Refactored to 8 development tools, removed deprecated WorkMgr async pattern

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

Made with
Version
3.0.010 Sep, 2025
Ideas portal
Category
Developer Environment
Works with
InterSystems IRISInterSystems IRIS for HealthHealthShare
First published
08 Sep, 2025
Last edited
10 Sep, 2025