Solver Mcp

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:

./gradlew build

Run the server:

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:

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:

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

Docker alternative:

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:

{
  "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:

{
  "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.

{
  "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  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:

./gradlew build

Build the container:

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).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: maciejewskii
• Source: maciejewskii/solver-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.