solver-mcp

solver-mcp is a local MCP server that gives AI agents a real Timefold Solver backend for assignment problems. The agent writes a declarative JSON spec with generic entities, values, attributes, and constraint primitives; the server validates it, solves it, and returns assignments with a score breakdown. The LLM writes a declarative spec, never code; Timefold computes the answer; nothing is hallucinated.

Unofficial project powered by Timefold Solver Community (Apache 2.0).

Quickstart

Prerequisites:

• JDK 21
• A local MCP client that can start stdio servers

Build the runnable fat jar:

bash
./gradlew build

Run the server:

bash
java -jar build/libs/solver-mcp-1.0.0-all.jar

For MCP clients, use the jar command above. Do not launch the MCP server through ./gradlew run; Gradle writes progress output to stdout, and stdio MCP requires stdout to contain protocol frames only.

Or build and run the Docker image:

bash
docker build -t solver-mcp:1.0.0 .
docker run -i --rm solver-mcp:1.0.0

Docker MCP clients must keep stdin open with -i; the server speaks MCP over stdio.

Claude Code

From this repository:

bash
claude mcp add solver-mcp -- java -jar /absolute/path/to/solver-mcp/build/libs/solver-mcp-1.0.0-all.jar

Docker alternative:

bash
claude mcp add solver-mcp -- docker run -i --rm solver-mcp:1.0.0

Then start Claude Code and ask it to use solver-mcp to validate and solve a spec.

Claude Desktop

Add a stdio server entry to your Claude Desktop MCP config:

json
{
  "mcpServers": {
    "solver-mcp": {
      "type": "stdio",
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/solver-mcp/build/libs/solver-mcp-1.0.0-all.jar"
      ]
    }
  }
}

Restart Claude Desktop after editing the config.

Docker alternative:

json
{
  "mcpServers": {
    "solver-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "solver-mcp:1.0.0"]
    }
  }
}

Tools

| Tool | Purpose |
| --- | --- |
| modeling_guide | Returns the DSL guide, expression syntax, primitive examples, full examples, and repair workflow. |
| validate_spec | Checks JSON shape, expression parsing, attribute references, primitive compatibility, and size warnings. |
| solve | Solves the ASSIGNMENT spec with a bounded Timefold run and returns the best-found assignment. |
| explain_solution | Rebuilds a supplied assignment and returns deterministic per-constraint totals and top matches. |
| diagnose_infeasible | Lists broken hard constraints and briefly re-solves with one hard constraint relaxed at a time. |

Spec

The v1.0 schema is published at [spec-schema.json](spec-schema.json). The current archetype is ASSIGNMENT: every entity gets one value from the values list.

json
{
  "name": "exam timetabling",
  "archetype": "ASSIGNMENT",
  "entities": [
    { "id": "examA", "attrs": { "students": 120, "teacher": "kim" } }
  ],
  "values": [
    { "id": "slot1_roomX", "attrs": { "day": 1, "slot": 1, "capacity": 150 } }
  ],
  "constraints": [
    {
      "id": "capacity",
      "type": "require",
      "when": "entity.attrs.students <= value.attrs.capacity",
      "level": "HARD"
    }
  ]
}

Constraint weights use the canonical schema:

json
{ "level": "HARD" }

json
{ "level": "SOFT", "weight": 3 }

Expression Language

Expressions are parsed by a small hand-rolled parser and evaluated against the generic model. They support identifiers entity, value, a, b, and group; paths such as entity.attrs.load, value.id, and a.value.attrs.day; number, string, boolean, and null literals; arithmetic, comparisons, &&, ||, !, and parentheses.

There are no method calls, loops, reflection, or arbitrary code execution.

Primitive Reference

| Primitive | Level | Required fields | Meaning |
| --- | --- | --- | --- |
| require | HARD or SOFT | when | Penalizes each assignment where when is false. |
| forbid | HARD or SOFT | when | Penalizes each assignment where when is true. |
| all_different | HARD or SOFT | expr | Penalizes entity pairs with equal expr values. |
| pair_rule | HARD or SOFT | forbid or penalizeIf | Penalizes entity pairs selected by optional pairFilter when the pair condition is true. |
| group_count | HARD or SOFT | groupBy, min or max | Bounds the number of assigned entities per group. |
| group_sum | HARD or SOFT | groupBy, sumExpr, min or max | Bounds a numeric sum per group. |
| cardinality | HARD or SOFT | min or max | Bounds how many entities are assigned to each value, optionally limited by valueFilter. |
| balance | SOFT | groupBy | Penalizes (group count)^2 for each group. |
| objective | SOFT | expr | minimize penalizes the sum; maximize rewards the sum. |

Examples

The repository includes five complete specs:

• [N-queens 8](examples/n-queens-8.json)
• [Graph coloring](examples/graph-coloring.json)
• [Task to machine with capacities](examples/task-machine-capacity.json)
• [Wedding seating with incompatible pairs](examples/wedding-seating.json)
• [Exam timetabling](examples/exam-timetabling.json)

See [examples/demo.md](examples/demo.md) for a transcript of the intended agent loop:

text
validate_spec -> solve -> explain_solution -> repair the spec if hard infeasible

Architecture

solver-mcp deliberately avoids domain classes such as employees, shifts, rooms, or jobs. The Timefold model has generic Element facts, generic planning entities, and constraint spec items stored on the planning solution as problem facts.

The ConstraintProvider contains always-present streams for every primitive and score level. Each stream starts from ConstraintSpecItem, filters by primitive and level, joins generic entities or values, and evaluates the cached expression AST. This keeps the solver data-driven without static registries or generated code.

solve returns the best-found solution within the requested time limit. explain_solution rebuilds the solution from { spec, assignments } and produces deterministic constraint totals and top matches so every score contribution is traceable.

Limitations

• v1.0 supports ASSIGNMENT only. SEQUENCE is planned for a future release.
• Timefold returns the best-found solution within the time limit unless configured otherwise; this project does not prove optimality.
• The expression language is intentionally small and bounded.
• The generic constraint streams are flexible, not a replacement for a hand-tuned domain solver on large production instances.
• validate_spec warns above 500 entities or 50,000 estimated pairs.

Roadmap

• SEQUENCE archetype with list-variable shadow variables: @IndexShadowVariable, @PreviousElementShadowVariable, and @CascadingUpdateShadowVariable.
• CP-SAT backend for optimality proofs where the DSL can be compiled exactly.
• More primitive constraints and stronger static type checks.
• Packaged desktop extension distribution.

Development

Run the full suite:

bash
./gradlew build

Build the container:

bash
docker build -t solver-mcp:1.0.0 .

The tests cover expression parsing and evaluation, every assignment primitive via Timefold ConstraintVerifier, end-to-end N-queens and graph coloring, infeasible diagnosis, validation errors, stdout discipline, and all checked-in examples.

License

Apache License 2.0. See [LICENSE](LICENSE).

Collapse