spintax.net MCP server

Static validation: returns diagnostics with severity, stable code, message and 1-based line/column. No "error"-severity diagnostic means the template is structurally sound — read the warnings before rendering, because some of them (plural.locale-missing) mean a block will not resolve. Pass knownVariables for names you will supply at render time to silence their variable.undefined warnings.

{
  "type": "object",
  "properties": {
    "template": {
      "type": "string",
      "maxLength": 8192,
      "description": "Spintax template source (max 8192 characters). #include is disabled on this server."
    },
    "locale": {
      "type": "string",
      "description": "Locale for {plural …} arity, e.g. \"en\" (2-form) or \"ru\" (3-form: ru/uk/be/sr/hr/bs). Omit for the 2-form default."
    },
    "knownVariables": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Variable names the caller will supply at render time (case-insensitive)."
    }
  },
  "required": [
    "template"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "valid": {
      "type": "boolean",
      "description": "True when no error-severity diagnostics."
    },
    "errorCount": {
      "type": "integer"
    },
    "warningCount": {
      "type": "integer"
    },
    "diagnostics": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning"
            ]
          },
          "code": {
            "type": "string",
            "description": "Stable machine code, e.g. plural.arity"
          },
          "message": {
            "type": "string"
          },
          "line": {
            "type": "integer",
            "description": "1-based"
          },
          "column": {
            "type": "integer",
            "description": "1-based"
          },
          "endLine": {
            "type": "integer"
          },
          "endColumn": {
            "type": "integer"
          },
          "data": {
            "type": "object"
          }
        },
        "required": [
          "severity",
          "code",
          "message",
          "line",
          "column"
        ]
      }
    }
  },
  "required": [
    "valid",
    "errorCount",
    "warningCount",
    "diagnostics"
  ]
}

Renders up to 20 variants. With a seed the output is deterministic (variant i uses seed "<seed>#<i>"); without one it is random. The engine is lenient: structural mistakes never throw, they surface in the output — run validate_spintax first.

{
  "type": "object",
  "properties": {
    "template": {
      "type": "string",
      "maxLength": 8192,
      "description": "Spintax template source (max 8192 characters). #include is disabled on this server."
    },
    "count": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 3,
      "description": "Number of variants (1–20)."
    },
    "seed": {
      "type": [
        "string",
        "number"
      ],
      "description": "Deterministic RNG seed; omit for random output."
    },
    "locale": {
      "type": "string",
      "description": "Locale for {plural …} arity, e.g. \"en\" (2-form) or \"ru\" (3-form: ru/uk/be/sr/hr/bs). Omit for the 2-form default."
    },
    "context": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Variable map, e.g. {\"CITY\": \"Prague\"}. Overrides #set/#def definitions."
    }
  },
  "required": [
    "template"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "variants": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "variants"
  ]
}

Reports what the template needs and contains: refs (variables referenced), sets (#set macros, re-picked per reference), defs (#def, rolled once per render), includes, diagnostics, and best-effort construct counts. Answers "what variables must I supply" — it is NOT a variant-cardinality counter.

{
  "type": "object",
  "properties": {
    "template": {
      "type": "string",
      "maxLength": 8192,
      "description": "Spintax template source (max 8192 characters). #include is disabled on this server."
    },
    "locale": {
      "type": "string",
      "description": "Locale for {plural …} arity, e.g. \"en\" (2-form) or \"ru\" (3-form: ru/uk/be/sr/hr/bs). Omit for the 2-form default."
    },
    "knownVariables": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "template"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "refs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "sets": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "defs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "includes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "diagnostics": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning"
            ]
          },
          "code": {
            "type": "string",
            "description": "Stable machine code, e.g. plural.arity"
          },
          "message": {
            "type": "string"
          },
          "line": {
            "type": "integer",
            "description": "1-based"
          },
          "column": {
            "type": "integer",
            "description": "1-based"
          },
          "endLine": {
            "type": "integer"
          },
          "endColumn": {
            "type": "integer"
          },
          "data": {
            "type": "object"
          }
        },
        "required": [
          "severity",
          "code",
          "message",
          "line",
          "column"
        ]
      }
    },
    "constructs": {
      "type": "object",
      "additionalProperties": {
        "type": "integer"
      }
    }
  },
  "required": [
    "refs",
    "sets",
    "defs",
    "includes",
    "diagnostics",
    "constructs"
  ]
}

Read this BEFORE writing or editing a spintax template — it is the canonical authoring guide the whole spintax toolchain is written against, not a tutorial. Pass the locale you will author in: for ru/uk/be and sr/hr/bs it carries the agreement and case rules that decide whether the variants read as human writing, which is the hard part and the part a valid template can still get wrong. Returns text to read, not a template.

{
  "type": "object",
  "properties": {
    "locale": {
      "type": "string",
      "description": "Language you will author in, e.g. \"en\" or \"ru\". Selects the grammar rules and the worked examples. Omit for the language-neutral rules only."
    },
    "variationLevel": {
      "type": "string",
      "enum": [
        "conservative",
        "balanced",
        "aggressive"
      ],
      "description": "How much markup to use. Omit to decide for yourself — the guide then states no level."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "rules": {
      "type": "string",
      "description": "The authoring rules, as text to read."
    },
    "promptVersion": {
      "type": "string",
      "description": "Version of the rules TEXT (@spintax/authoring-prompt PROMPT_VERSION). Moves when the wording changes in a way that can change what a model writes."
    },
    "locale": {
      "type": "string"
    }
  },
  "required": [
    "rules",
    "promptVersion"
  ]
}