SAR Test MCP Server

A Model Context Protocol (MCP) server for running and validating SAR/TAR test files for IFS Cloud ERP integration testing. Provides 32 powerful tools for code analysis, test execution, validation, pattern enforcement, auto-generation, intelligent recommendations, and self-learning - enabling code-first test generation without browser automation in most cases.

Features

• Code-First Analysis: Analyze IFS Cloud DSL files to identify server calls without browser automation
• 32 Powerful Tools: Complete code analysis, test execution, validation, pattern enforcement, auto-generation, intelligent recommendations, and self-learning
• Self-Learning System: Session learnings, user corrections, and team rules for continuous improvement
• Assertion Enforcement: Strict {%variable} syntax and exact == matching for error messages
• Debug Workflow: Comprehensive debug-fix-rerun cycle with browser verification for dropdown/LOV errors
• Pattern Validation & Enforcement: Prevent SQL/database operations, enforce API-only rule, detect direct API calls in test cases
• Auto-Generation: Generate complete utils with optional field handling (InputExists() patterns)
• Assertion Strategy Guidance: Accurate recommendations based on IFS Cloud API behavior
• Assistant Lifecycle: Full support for 7-phase IFS Cloud assistant patterns with init calls
• Fragment Support: Complete parsing and merging of fragment definitions from client and projection sections
• Smart Browser Strategy: Intelligent recommendations for when browser automation is actually needed
• Comprehensive Utils Search: Two-tier search across current and all test collections
• SAR Terminology: CREATE/GET/MODIFY/DELETE for IFS Cloud consistency
• Test Execution: Run TAR tests using ScriptARest.exe with detailed output parsing
• Enhanced Validation: No-Print enforcement, pattern detection, util structure recommendations

What's New in 1.4.0

Sequential Test Execution

• One-by-One Workflow: Execute and fix tests sequentially, not all at once
• Fix Propagation: Apply common fixes to all affected tests before proceeding
• Mandatory Verification: Re-run each fixed test to confirm it passes before moving to next
• Focused Debugging: Fix one test issue at a time to prevent cascading failures
• Clear Workflow: Test 1 → Fix → Re-run → Pass → Propagate → Test 2 → Fix → Re-run → Pass → ...

What's New in 1.2.0 (Previous Release)

Documentation & Generalization

• Generic Examples: All instructional examples now use generic placeholders (e.g., {FeatureName}, Action X, condition Y) instead of test-specific examples
• Universal Applicability: Instructions and guidance apply across all IFS Cloud modules without module-specific bias
• Validation Logic Clarity: Enhanced guidance on prioritizing acceptance criteria over code implementation, especially for validation scenarios

What's New in 1.1.0 (Previous Release)

Core Fixes

• Print Statement Enforcement: Removed all Print statements from advisor examples and delivery files
• Assertion Development Workflow: Renamed from "Print-Run-Approve" to emphasize temporary debugging only
• Print-as-Logic Detection: assertion-validator.ts now explicitly flags Print ... When patterns as fundamental violations
• Command Validation: Test Suite files no longer allow Print commands

Client-Side vs Server-Side Validation

• Acceptance Criteria Primacy: AC drives what to test; code analysis is only for endpoint discovery
• Validation Warning: code-change-analyzer.ts now issues warnings when code analysis predominantly finds client-side validation
• Test Scope Enforcement: Never test client-side validation endpoints; always test the actual server-side action from AC

Architecture

• 32 tools with self-learning capabilities and validation enforcement
• Knowledge base categories: util_pattern, failure_fix, endpoint_util_map, confidence_calibration, field_correction, user_correction, team_rule
• Enhanced code analysis with validation endpoint marking (isClientValidation flag)

What's New in 9.0.0

Pattern Validation & Auto-Generation

🛡️ API Endpoints ONLY Enforcement

• validateUtilPattern - Detects SQL/database operations and enforces REST API-only rule
• detectForbiddenPatterns - Quick validation gate for SQL (INSERT, UPDATE, DELETE, EXEC, etc.)
• Prevents utils from using database scripts - enforces SAR principle (Service Automation REST)
• Critical issues flagged before saving with fix suggestions

🤖 Intelligent Util Generation

• generateUtilTemplate - Auto-generates complete .mkd utils with all patterns implemented
• Handles optional fields automatically with InputExists() conditional logic
• Generates conditional assignments and API calls for multiple optional field combinations
• Eliminates manual pattern implementation errors

🎯 Assertion Strategy Advisor

• suggestAssertionStrategy - Provides accurate assertion recommendations based on IFS Cloud API behavior
• GET: Always returns full entity → assert-direct strategy
• CREATE/MODIFY/ACTION: Usually return status only → get-then-assert strategy
• DELETE: Always returns status only → expect-fail strategy
• Corrected response patterns prevent test failures

Architecture Improvements

📚 Intelligence Migration

• Moved 670 lines of pattern logic from SARDevAgent to MCP
• SARDevAgent reduced by 73% (1164 → 318 lines) - now pure workflow orchestration
• Technical intelligence centralized in MCP tools
• Validation rules, patterns, and generation logic programmatically enforced

✅ Complete Alignment

• MCP (22 tools), Plan (13 phases), Agent (10 parts) at that time - 100% aligned — Updated to 28 tools, 15 phases, 13 parts in v12.0.0
• No conflicting instructions across components
• All 21 user requirements implemented and verified
• Zero gaps in requirement coverage

What's New in 8.0.0

Documentation & Setup

📚 Complete Documentation Overhaul

• Comprehensive README with accurate feature descriptions
• Clear setup instructions for all integration methods
• Detailed troubleshooting guide
• Complete tool reference with examples

🎯 Streamlined Architecture

• Removed redundant instruction files
• IFS Cloud DSL pattern knowledge built into MCP code
• Cleaner project structure focused on core functionality

Features from 7.0.0 (Maintained)

🎯 Code-First Test Generation

• analyzeCodeChanges tool analyzes IFS Cloud DSL files (.client, .projection, .fragment, .plsvc)
• Identifies features and server calls from source code
• Eliminates need for browser automation in most cases (only used when confidence <95%)
• Supports SAR terminology: CREATE (POST), GET, MODIFY (PATCH), DELETE

🧩 Complete Fragment Support

• Parses fragments included in both .client and .projection files
• Extracts assistants, pages, lists, groups from CLIENT FRAGMENTS section
• Extracts entitySets, virtuals, queries from PROJECTION FRAGMENTS section
• Properly merges fragment definitions into parent clients and projections

🔄 Assistant Lifecycle Intelligence

• Full understanding of 7-phase assistant lifecycle:
  1. Default GET call
  2. CREATE virtual instance
  3. Init command calls (NEW in v7)
  4. MODIFY virtual (optional)
  5. Button execution
  6. When OK execution
  7. Cleanup call
• Extracts init command blocks and maps to GET function calls
• Handles input this pattern for child assistants
• Detects output(...) fields

📍 Smart Browser Capture Strategy

• recommendCaptureStrategy tool makes intelligent decisions
• Returns confidence scores for code analysis
• Suggests "none", "verification_only", "partial", or "full" capture strategies
• Significantly reduces time and cost

🔍 Comprehensive Utils Search

• Two-tier search strategy: current collection first, then all collections
• Searches entire inttst folder for maximum reuse
• Indicates source of found utils for context

✅ Enhanced Validation

• validateAssertions - No-Print enforcement, assertion pattern validation
• detectPattern - TAR best practices (ExpectFail, camelCase, array access)
• suggestUtilStructure - Optimal util organization for assistants

Complete Tool Set (22 Tools)

Code Analysis Tools (8)

• analyzeCodeChanges - Analyze DSL files and identify server calls
• extractNavigationPath - Parse Navigator.client for page paths
• identifyPageContext - Identify page context from .client files
• recommendCaptureStrategy - Intelligent browser capture decisions
• analyzePrerequisites - Identify required prerequisite data
• findExistingUtils - Search for reusable utils (2-tier search)
• suggestUtilStructure - Recommend util split strategy
• clearAnalysisCache - Clear file parsing cache

Enhanced Validation Tools (7)

• validateAssertions - Assertion pattern validation
• detectPattern - TAR pattern detection
• suggestUtilStructure - Assistant util structure validation
• validateUtilPattern - NEW: Enforce API-only, validate optional fields, detect patterns
• detectForbiddenPatterns - NEW: Quick SQL/database operation detection
• generateUtilTemplate - NEW: Auto-generate complete utils with all patterns
• suggestAssertionStrategy - NEW: Assertion strategy based on API call type

Test Execution Tools (4)

• configureRunner - Configure ScriptARest and credentials
• runTest - Execute TAR test files
• analyzeResults - Parse ScriptARest output
• getRunnerStatus - Check runner configuration

Core Validation Tools (3)

• validateFile - Full .mkd file validation
• validateContent - Validate TAR content from string
• checkCommands - TAR command syntax validation

Architecture

• 10 Analyzers: Complete DSL parsing (projections, clients, fragments, plsvc, navigator)
• 3 Validators: Assertion, pattern, and assistant structure validation
• File Caching: Intelligent caching with mtime-based invalidation
• Performance Telemetry: Analysis timing metrics
• Fragment Merging: Proper resolution and merging of nested includes

Backward Compatibility

✅ Fully backward compatible with v6.0.0 and v7.0.0

• All existing tools continue to work
• New tools are additive enhancements
• No breaking changes

Prerequisites

• Node.js v20.0.0 or higher
• npm or pnpm package manager
• ScriptARest.exe (for test execution)
• Access to Cloud ERP server (for test execution)

Package Information

This package is fully bundled - all internal dependencies are included.

| Property | Value | |----------|-------| | Bundle Size | ~87 KB | | Node.js | ≥20.0.0 | | Module Type | ESM | | TypeScript | Included |

Peer Dependencies

The following dependencies are required and must be installed separately (or will be auto-installed):

# Auto-installed when using npx
@modelcontextprotocol/sdk ^1.0.0

Integration Options

Choose the integration method that works best for your workflow:

Option 1: VS Code Integration

Integrate the MCP server into VS Code to use test tools directly in your editor.

Step 1: Create the MCP configuration folder

In your project root directory, create a .vscode folder:

mkdir .vscode

Step 2: Create the MCP configuration file

Inside the .vscode folder, create a file named mcp.json with the following content:

{
  "servers": {
    "sar-test": {
      "command": "npx",
      "args": [
        "-y",
        "@dilina0914/[email protected]"
      ],
      "env": {
        "SAR_SCRIPT_A_REST_PATH": "C:\\Path\\To\\ScriptARest.exe",
        "SAR_SERVER_URL": "https://your-erp-server.com",
        "SAR_USERNAME": "your_username",
        "SAR_PASSWORD": "your_password"
      }
    }
  }
}

Step 3: Configure environment variables

| Variable | Description | Required | |----------|-------------|----------| | SAR_SCRIPT_A_REST_PATH | Full path to ScriptARest.exe | Yes (for running tests) | | SAR_SERVER_URL | Cloud ERP server URL | Yes (for running tests) | | SAR_USERNAME | Authentication username | Yes (for running tests) | | SAR_PASSWORD | Authentication password | Yes (for running tests) | | SAR_TIMEOUT_MS | Timeout in milliseconds | No (default: 600000) | | LOG_LEVEL | Logging level (debug, info, warn, error) | No (default: info) |

Step 4: Restart VS Code

Close and reopen VS Code to load the MCP server configuration.

Option 2: Cursor IDE Integration

Cursor IDE has built-in support for MCP servers, making integration straightforward.

Step 1: Open Cursor Settings

1. Open Cursor IDE
2. Go to Settings (File > Preferences > Settings or Ctrl/Cmd + ,)
3. Search for "MCP" or navigate to the MCP configuration section

Step 2: Add MCP Server Configuration

In the MCP settings, add a new server with the following configuration:

{
  "mcpServers": {
    "sar-test": {
      "command": "npx",
      "args": [
        "-y",
        "@dilina0914/[email protected]"
      ],
      "env": {
        "SAR_SCRIPT_A_REST_PATH": "C:\\Path\\To\\ScriptARest.exe",
        "SAR_SERVER_URL": "https://your-erp-server.com",
        "SAR_USERNAME": "your_username",
        "SAR_PASSWORD": "your_password",
        "SAR_TIMEOUT_MS": "600000"
      }
    }
  }
}

Step 3: Save and Restart

Save the configuration and restart Cursor IDE to activate the MCP server.

Option 3: Claude Desktop Integration

Add to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sar-test": {
      "command": "npx",
      "args": ["-y", "@dilina0914/[email protected]"],
      "env": {
        "SAR_SCRIPT_A_REST_PATH": "C:\\Path\\To\\ScriptARest.exe",
        "SAR_SERVER_URL": "https://your-erp-server.com",
        "SAR_USERNAME": "your_username",
        "SAR_PASSWORD": "your_password"
      }
    }
  }
}

Option 4: Local Development

Run the server directly for development or testing.

Step 1: Install the package

npm install @dilina0914/sar-test-mcp

Step 2: Configure environment variables

Windows (PowerShell):

$env:SAR_SCRIPT_A_REST_PATH = "C:\Path\To\ScriptARest.exe"
$env:SAR_SERVER_URL = "https://your-erp-server.com"
$env:SAR_USERNAME = "your_username"
$env:SAR_PASSWORD = "your_password"

Windows (Command Prompt):

set SAR_SCRIPT_A_REST_PATH=C:\Path\To\ScriptARest.exe
set SAR_SERVER_URL=https://your-erp-server.com
set SAR_USERNAME=your_username
set SAR_PASSWORD=your_password

Linux/macOS:

export SAR_SCRIPT_A_REST_PATH="/path/to/ScriptARest"
export SAR_SERVER_URL="https://your-erp-server.com"
export SAR_USERNAME="your_username"
export SAR_PASSWORD="your_password"

Step 3: Run the server

npx @dilina0914/sar-test-mcp

Quick Troubleshooting

ScriptARest Not Found

Error: ScriptARest.exe not found at: <path>

Solution:

• Verify the path in SAR_SCRIPT_A_REST_PATH is correct
• Use absolute paths, not relative paths
• On Windows, use double backslashes (\\) or forward slashes (/)
• Ensure ScriptARest.exe has execute permissions

Connection Issues

Error: Connection failed: Invalid credentials or 401 Unauthorized

Solution:

• Verify SAR_USERNAME and SAR_PASSWORD are correct
• Check if the user has access to the Cloud ERP server
• Verify the server URL is correct and accessible

Test File Not Found

Error: Test file not found: <path>

Solution:

• Verify the file path is correct
• Use absolute paths for test files
• Check file permissions

Timeout Errors

Error: Test execution timed out

Solution:

• Increase SAR_TIMEOUT_MS (default: 600000 = 10 minutes)
• Check if the server is responding slowly
• Verify network connectivity

Environment Variable Issues

Error: Test runner not configured

Solution:

• Restart your IDE after setting environment variables
• For VS Code/Cursor: Ensure variables are in the mcp.json file
• Verify the JSON syntax in your configuration file
• Use getRunnerStatus tool to check configuration

What's Included

MCP Tools (18 total)

Code Analysis Tools (NEW in 7.0.0)

| Tool | Description | |------|-------------| | analyzeCodeChanges | Analyze IFS Cloud DSL files to identify features, server calls, and prerequisites | | extractNavigationPath | Extract step-by-step navigation path from Navigator.client | | identifyPageContext | Identify page context and required context keys from .client files | | recommendCaptureStrategy | Get intelligent browser capture strategy recommendations | | clearAnalysisCache | Clear internal file-parsing cache after git pull or branch switch |

Enhanced Validation Tools (NEW in 7.0.0)

| Tool | Description | |------|-------------| | validateAssertions | Validate assertion patterns, detect Print violations | | detectPattern | Detect and validate common TAR patterns (ExpectFail, Connect, etc.) | | suggestUtilStructure | Suggest optimal util structure for assistants and complex features |

Test Execution Tools

| Tool | Description | |------|-------------| | configureRunner | Configure ScriptARest path and server credentials | | runTest | Execute a TAR test file and get parsed results | | analyzeResults | Analyze raw ScriptARest output | | getRunnerStatus | Check runner configuration status |

Validation Tools

| Tool | Description | |------|-------------| | validateFile | Full validation of a .mkd file against SAR/TAR standards | | validateContent | Validate TAR content from string input | | validateSuite | Validate all .mkd files in a directory | | checkAaaStructure | Check Arrange-Act-Assert structure (Test Cases) | | checkCommands | Validate TAR command syntax and usage | | getValidationRules | Get current validation rules and settings |

Supported TAR File Types

| Type | Description | AAA Required | |------|-------------|--------------| | Test Data | Setup/cleanup data scripts | No | | Test Util | Reusable utility scripts | No | | Test Case | Individual test with assertions | Yes | | Test Suite | Collection of test cases | No | | Test Collection | Collection of test suites | No |

Error Detection

The MCP detects and provides suggestions for:

| Error Type | HTTP Code | Description | |------------|-----------|-------------| | Not Found | 404 | Missing entities or incorrect URLs | | Unauthorized | 401 | Authentication failures | | Validation | 422 | Business rule violations | | Server Error | 500 | Backend issues | | Assert Failed | - | Test assertion mismatches | | High Failure Rate | - | Data dependency issues (>10% failures) |

Output Parsing

Parses ScriptARest output to extract:

• Test name, status, and execution time
• Server call counts (total, failed)
• Assert counts (total, failed)
• Exception counts
• Individual command results with HTTP status codes
• Server call performance statistics (count, avg, min, max)

Tool Examples

Run a Test

{
  "tool": "runTest",
  "arguments": {
    "filePath": "C:\\tests\\CreateCustomer.mkd"
  }
}

Response:

{
  "success": true,
  "report": {
    "testName": "CreateCustomer",
    "status": "Passed",
    "timeSeconds": 12.5,
    "serverCalls": 5,
    "failedServerCalls": 0,
    "asserts": 2,
    "failedAsserts": 0,
    "exceptions": 0
  },
  "errors": [],
  "warnings": [],
  "analysis": {
    "summary": "Test CreateCustomer passed successfully in 12.50s with 5 server calls.",
    "issues": []
  }
}

Validate a File

{
  "tool": "validateFile",
  "arguments": {
    "filePath": "C:\\tests\\CreateCustomer.mkd",
    "strictMode": true
  }
}

Analyze Test Output

{
  "tool": "analyzeResults",
  "arguments": {
    "rawOutput": "IFS Script-A-Rest v 2.4.0\n..."
  }
}

Check Runner Status

{
  "tool": "getRunnerStatus",
  "arguments": {}
}

Response:

{
  "configured": true,
  "config": {
    "scriptARestPath": "C:\\Path\\To\\ScriptARest.exe",
    "serverUrl": "https://your-erp-server.com",
    "username": "your_username",
    "hasPassword": true,
    "timeoutMs": 600000
  },
  "validation": {
    "valid": true,
    "errors": []
  }
}

Security Features

• Credential Protection: Passwords are never exposed in responses or logs
• Input Validation: File paths and parameters are validated
• Audit Logging: Complete audit trail of tool invocations
• Timeout Protection: Configurable timeouts prevent runaway processes

License

MIT

Links

• GitHub Repository: https://github.com/dilinaweerasinghe/integration-testing-mcp
• npm Package: https://www.npmjs.com/package/@dilina0914/sar-test-mcp
• Issues: https://github.com/dilinaweerasinghe/integration-testing-mcp/issues

Support

Open an issue on the GitHub repository for support.