SESL MCP Server - User Guide

{
  "tool": "generate_sesl",
  "arguments": {
    "prompt": "Create rules to approve a loan if credit score > 700 and income > 50000"
  }
}

📤 Example Response:

Returns a comprehensive template (2000+ characters) that you can send to an LLM like ChatGPT or Claude. The template includes:

• Complete SESL specification (10 sections): File structure, rule syntax, YAML formatting rules, condition syntax, LET variables, field references, THEN blocks, data types, priorities, and facts
• Error prevention checklist: Common mistakes to avoid (YAML syntax errors, condition formatting, variable usage, required fields)
• Working example: A complete, runnable SESL model demonstrating all features
• Your prompt: Integrated into the template as the goal for code generation

Typical usage flow:

1. Call generate_sesl with your requirements
2. Copy the returned template
3. Send it to ChatGPT/Claude (e.g., "Here's a SESL template. Generate the code: [paste template]")
4. LLM returns valid SESL YAML that you can save with add_model

Sample output snippet:

Generate SESL YAML for the following requirement:

Create rules to approve a loan if credit score > 700 and income > 50000

=== SESL SPECIFICATION ===

1. FILE STRUCTURE
Every SESL file must have this structure:
  const:        # Optional: define reusable constants
  rules:        # Required: list of rules
  facts:        # Optional: test scenarios

2. RULE STRUCTURE
Each rule must have:
  - rule: unique_name
    priority: number (higher = fires first)
    if: [conditions]
    then: [actions]
    because: "explanation"

...

{
  "tool": "lint_sesl",
  "arguments": {
    "contents": [
      {
        "type": "text",
        "text": "const:\\n  MIN_SCORE: 700\\nrules:\\n  - rule: approve_loan\\n..."
      }
    ]
  }
}

📤 Example Response (with errors):

[
  {
    "type": "text",
    "text": {
      "issues": [
        {
          "level": "ERROR",
          "message": "Missing required field 'priority'",
          "rule": "approve_loan",
          "details": {
            "error_type": "ValidationError",
            "field": "priority",
            "suggestion": "Add 'priority: 100' to the rule definition"
          }
        },
        {
          "level": "WARNING",
          "message": "Rule has no 'because' field",
          "rule": "check_income",
          "details": {
            "suggestion": "Add explanatory text for documentation"
          }
        }
      ]
    }
  }
]

📤 Example Response (no errors):

[
  {
    "type": "text",
    "text": {
      "issues": []
    }
  }
]

Understanding the response:

• Empty issues array: Your SESL is valid and ready to execute
• ERROR level: Critical issues that will prevent execution - must fix these
• WARNING level: Best practice violations - code will run but may not be optimal
• details object: Additional context including error type and actionable suggestions

{
  "tool": "run_sesl",
  "arguments": {
    "contents": ["const:\\n  MIN_SCORE: 700\\n..."],
    "facts": {
      "credit_score": 750,
      "annual_income": 60000
    }
  }
}

📤 Example Response (successful execution):

[
  {
    "type": "text",
    "text": {
      "results": {
        "credit_score": 750,
        "annual_income": 60000,
        "debt_to_income": 0.35,
        "loan_approved": true,
        "approval_reason": "Meets credit and income requirements",
        "max_loan_amount": 250000
      },
      "metadata": {
        "rules_fired": ["calculate_dti", "approve_loan", "calculate_max_loan"],
        "execution_stages": ["lint", "load", "build_facts", "execute"],
        "total_rules": 5,
        "rules_evaluated": 5,
        "execution_time_ms": 45,
        "success": true
      }
    }
  }
]

Understanding the response:

• results object: Contains both your original input facts AND new facts added by rules
• rules_fired array: Shows which rules executed, in the order they fired (useful for debugging)
• execution_stages: Confirms all processing stages completed successfully
• New fields: Any field that appears in results but wasn't in your input facts was created by a rule (e.g., loan_approved, max_loan_amount)

📤 Example Response (execution error):

[
  {
    "type": "text",
    "text": {
      "error": "Execution failed during stage: execute",
      "error_type": "RuntimeError",
      "stage": "execute",
      "details": "Division by zero in rule 'calculate_ratio'",
      "suggestion": "Add condition to check denominator is not zero",
      "metadata": {
        "rules_fired_before_error": ["validate_input"],
        "failed_at_rule": "calculate_ratio"
      }
    }
  }
]

{
  "tool": "add_model",
  "arguments": {
    "sesl_yaml": "const:\\n* MIN_SCORE: 700\\nrules:\\n* rule: approve\\n...",
    "name": "loan_approval",
    "auto_fix": true
  }
}

📤 Example Response (success):

{
  "success": true,
  "file_path": "C:\\Users\\vince\\Documents\\sesl-mcp\\loan_approval.sesl",
  "file_name": "loan_approval.sesl",
  "content_length": 342,
  "auto_fixed": true,
  "message": "SESL model saved to loan_approval.sesl"
}

Field explanations:

• file_path: Absolute path where the file was saved (current working directory)
• content_length: Size of saved content in bytes
• auto_fixed: true if ChatGPT bullet points were converted to YAML syntax, false if no changes needed

📤 Example Response (error - invalid YAML):

{
  "success": false,
  "error": "Invalid YAML syntax",
  "error_type": "YAMLError",
  "details": "mapping values are not allowed here\n  in \"\", line 5, column 15",
  "suggestion": "Check YAML formatting: indentation, colons, dashes. Line 5 likely has incorrect spacing or missing colon."
}

Common errors and fixes:

• "mapping values are not allowed": Missing space after colon (should be key: value not key:value)
• "expected <block end>": Indentation problem - ensure consistent spaces (not tabs)
• File already exists: The tool will overwrite existing files - use different names or backup first

{
  "tool": "add_scenario",
  "arguments": {
    "model_file": "loan_approval.sesl",
    "scenario_yaml": "credit_score: 800\\nannual_income: 75000"
  }
}

📤 Example Response (success):

{
  "success": true,
  "file_path": "C:\\Users\\vince\\Documents\\sesl-mcp\\loan_approval.sesl",
  "scenarios_added": 1,
  "total_scenarios": 3,
  "message": "Added 1 scenario(s) to loan_approval.sesl"
}

Understanding the response:

• scenarios_added: How many test scenarios were added in this operation (can be >1 if you provide a YAML list)
• total_scenarios: Total count of scenarios in the file after adding (helps track test coverage)

What happens to the file: The tool loads your existing model, parses the scenario YAML, appends it to the facts array, and writes the updated model back to disk. Original formatting is preserved where possible.

📤 Example Response (error - file not found):

{
  "success": false,
  "error": "Model file not found: loan_approval.sesl",
  "suggestion": "Use add_model first to create the SESL model file",
  "searched_path": "C:\\Users\\vince\\Documents\\sesl-mcp\\loan_approval.sesl"
}

Tip: You can add multiple scenarios at once by providing a YAML list:

scenario_yaml: |-
  - credit_score: 800
    annual_income: 100000
  - credit_score: 650
    annual_income: 45000
  - credit_score: 720
    annual_income: 62000

{
  "tool": "add_rule",
  "arguments": {
    "model_file": "loan_approval.sesl",
    "rule_yaml": "rule: high_value_approval\\npriority: 10\\nif:\\n  - credit_score > 800\\nthen:\\n  - approved: true"
  }
}

📤 Example Response (success):

{
  "success": true,
  "file_path": "C:\\Users\\vince\\Documents\\sesl-mcp\\loan_approval.sesl",
  "rules_added": 1,
  "total_rules": 5,
  "message": "Added 1 rule(s) to loan_approval.sesl"
}

Understanding the response:

• rules_added: How many rules were added in this operation
• total_rules: Total count of rules in the model after adding

📤 Example Response (error - invalid rule format):

{
  "success": false,
  "error": "Invalid rule format: must have 'rule' key",
  "suggestion": "Each rule must have: rule, priority, if, then, because"
}

Required rule structure: Every SESL rule must be a dictionary with these fields:

rule: unique_rule_name        # Required: identifier for the rule
priority: 100                 # Required: number (higher fires first)
if:                          # Required: list of conditions
  - condition1
  - condition2
then:                        # Required: list of actions
  - field: value
because: "explanation"        # Required: human-readable reason

Priority guidelines:

• 1000+: Critical overrides and exceptions
• 500-999: High-priority business logic
• 100-499: Standard rules
• 1-99: Default/fallback rules

{
  "tool": "server_info",
  "arguments": {}
}

📤 Example Response:

{
  "name": "sesl-mcp-server",
  "version": "0.1.0",
  "status": "running",
  "tools": [
    "generate_sesl",
    "lint_sesl",
    "run_sesl",
    "add_model",
    "add_scenario",
    "add_rule",
    "server_info"
  ],
  "sesl_engine": "https://github.com/vpowell4/sesl"
}