Tools for agents: Generalized modular-congruence solver

Combine integer repeating-cycle constraints into one complete solution progression or an explicit incompatibility witness.

Connect with MCP

{
  "mcpServers": {
    "super-agent-tools": {
      "url": "https://app.getsupers.com/sites/agent-congruences/mcp"
    }
  }
}
Streamable HTTP · No API key · Stateless

Use this URL in any client supporting remote Streamable HTTP MCP. Calls return structured JSON; inputs are processed without persistence.

Call solve_congruences

Each constraint is [remainder,modulus], meaning x is congruent to remainder modulo modulus. Moduli must be positive JSON integers; remainders may be negative. Booleans, floats and quoted numbers are rejected. Moduli need not be coprime. A consistent result describes every integer solution as x=remainder+k*modulus for any integer k, with the least nonnegative remainder and positive combined modulus. Output integers are decimal strings to preserve arbitrary precision in clients. Empty constraints mean every integer and return remainder 0, modulus 1. Duplicate compatible constraints do not change the solution. An inconsistent result has no solution and supplies the first conflicting input index, the already-combined prefix, the incoming normalized constraint, and their gcd; the difference is not divisible by that gcd. All moduli are validated before solving. This is exact integer arithmetic, not calendar scheduling, time-zone conversion, task execution or a cryptographic protocol.

Input and output schemas
{
  "name": "solve_congruences",
  "title": "Generalized modular-congruence solver",
  "description": "Solve simultaneous x = remainder modulo modulus constraints with positive integer moduli. Return the complete arithmetic progression or a conflicting prefix witness.",
  "inputSchema": {
    "properties": {
      "constraints": {
        "items": {
          "maxItems": 2,
          "minItems": 2,
          "prefixItems": [
            {
              "type": "integer"
            },
            {
              "type": "integer"
            }
          ],
          "type": "array"
        },
        "title": "Constraints",
        "type": "array"
      }
    },
    "required": [
      "constraints"
    ],
    "title": "solve_congruencesArguments",
    "type": "object"
  },
  "outputSchema": {
    "additionalProperties": true,
    "title": "solve_congruencesDictOutput",
    "type": "object"
  },
  "icons": null,
  "annotations": {
    "title": null,
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "meta": null,
  "execution": null
}

Run the example to see the actual result.

HTTP alternative

POST https://app.getsupers.com/sites/agent-congruences/call
Content-Type: application/json

{
  "constraints": [
    [
      2,
      6
    ],
    [
      5,
      9
    ],
    [
      14,
      15
    ]
  ]
}

The HTTP and MCP interfaces execute the same implementation. Validation errors are returned explicitly. See the tool notes above for its supported inputs and behavior.

Combining periodic integer constraints

Read the explanation

The documented sample requires x congruent to two modulo six and five modulo nine. Their shared divisor is three, and the remainder difference five minus two is also three, so the constraints are compatible. The combined progression is fourteen plus eighteen k. The period is the least common multiple, six times nine divided by three, giving eighteen. At fifteen pixels per integer period the bars show six as ninety and eighteen as two hundred seventy. This arithmetic is derived from the documented sample. The offline copy lacks its shared app script and does not demonstrate an actual server or MCP call. The third sample constraint is fourteen modulo fifteen. Fourteen already satisfies all three conditions. Combining periods eighteen and fifteen divides their product by their shared divisor three, giving ninety. At three pixels per integer period the bars grow from fifty four to two hundred seventy. Every integer solution is fourteen plus ninety k, including negative k. This is an arithmetic progression rather than a calendar schedule or task execution. Output decimal strings preserve exact integers in clients, according to the page documentation, but an offline input edit does not prove the implementation returned that result. Keep two modulo six but replace five modulo nine with four modulo nine. The remainder difference becomes two rather than three. At eighty pixels per difference unit the bars span two hundred forty and one hundred sixty. Because six and nine share divisor three, the difference must be divisible by three. Two is not, so no integer can satisfy the pair. The documented solver returns a conflict witness for incompatible inputs. This explanation proves the arithmetic condition, not a live service response. Empty constraints instead represent every integer, and positive integer moduli are required by the documented input contract.

Generalized Modular Congruence Solving

How does the solver combine modular periodicities with non-coprime moduli into a single progression or identify a conflict?

The solver iteratively reduces simultaneous modular congruence constraints x ≡ remainder (mod modulus) into a single progression x ≡ R (mod M). At each step, a new constraint is merged with the accumulated solution by checking whether the difference between remainders is divisible by the greatest common divisor of their moduli. If divisible, the algorithm calculates a modular inverse to advance the unified residue and multiplies the modulus by the reduced coprime factor; if not, it terminates early and produces an explicit conflict witness.

This endpoint executes pure integer modular arithmetic with positive integer moduli. It does not perform calendar scheduling, time-zone offset conversions, task execution, or cryptographic key exchange. Downstream bounded range queries or loop limits must be evaluated separately by calling agents.

Try a worked example

Submit the default arguments with constraints [[2, 6], [5, 9], [14, 15]] by clicking Run tool. The status message updates to 'Complete. Result returned by the live tool.' and the structured output displays consistent: true with solution remainder '14' and modulus '90'. Moduli 6, 9, and 15 have least common multiple 90, and every integer x = 14 + 90k simultaneously satisfies x ≡ 2 (mod 6), x ≡ 5 (mod 9), and x ≡ 14 (mod 15).

Pairwise Solvability and Classical Foundations

The classical Chinese Remainder Theorem establishes that simultaneous congruences with pairwise relatively prime moduli possess a unique solution modulo the product of those moduli. Chinese Remainder Theorem -- from Wolfram MathWorld

When moduli share common factors, the solver verifies compatibility before updating: for any pair of constraints, the difference between their remainders must be divisible by the greatest common divisor of their moduli. If this condition fails, no integer can simultaneously satisfy both cycles.

Iterative Merging and Conflict Witnesses

Starting with base progression residue 0 modulo 1, the solver iterates through each constraint. Given an accumulated state (R, M) and an incoming constraint (r, m), it computes g = gcd(M, m) and delta = r - R. If delta % g != 0, execution stops and returns an object detailing the conflicting constraint index, prefix values, incoming values, and gcd. When delta % g == 0, it computes the step multiplier via modular inverse pow(M // g, -1, m // g), updating the period to M * (m // g) = lcm(M, m).

Sources and further reading