git404hub

what is solver-mcp fr?

maciejewskii/solver-mcp — explained in plain English

Analysis updated 2026-05-18

4KotlinAudience · developerComplexity · 3/5LicenseSetup · moderate

tl;dr

A local MCP server that lets AI agents describe scheduling and assignment problems in JSON and get real, computed solutions from Timefold Solver.

vibe map

mindmap
  root((solver-mcp))
    What it does
      Solves assignment specs
      Validates JSON specs
      Explains solutions
    Tech stack
      Kotlin
      Timefold Solver
      MCP protocol
      Docker
    Use cases
      Exam timetabling
      Graph coloring
      Seating and task assignment
    Tools
      validate_spec
      solve
      diagnose_infeasible

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

what do people make with this?

VIBE 1

Let an AI agent solve real scheduling problems like exam timetabling by writing a JSON spec instead of code.

VIBE 2

Validate and repair an infeasible assignment problem by diagnosing which constraint is breaking it.

VIBE 3

Solve constraint problems like graph coloring, seating charts, or task-to-machine assignment through an MCP client.

what's the stack?

KotlinTimefold SolverMCPDocker

how it stacks up fr

maciejewskii/solver-mcpadhithya90/design-lens-composeblindman81/snippets
Stars444
LanguageKotlinKotlinKotlin
Setup difficultymoderatemoderatemoderate
Complexity3/54/52/5
Audiencedeveloperdevelopergeneral

Figures from each repo's GitHub metadata at analysis time.

how do i run it?

Difficulty · moderate time til it works · 30min

Requires JDK 21 and an MCP-capable client, can also run via the provided Docker image.

Free to use, modify, and distribute for any purpose, including commercial use, as long as the copyright notice and license are kept.

in plain english

solver-mcp is a local server that gives AI coding assistants a real optimization engine to solve scheduling and assignment style problems, instead of trying to work them out by guessing. An AI agent writes a plain description of the problem as a JSON file, listing generic entities, the possible values they can be assigned, their attributes, and a set of rules the assignment must follow. The server checks that description for mistakes, actually solves it using an optimization engine called Timefold Solver, and returns the resulting assignments along with a breakdown of how well each rule was satisfied. The project positions itself around one key idea: the AI writes a description of the problem, never code to solve it, so the assignment answer comes from real computation rather than being made up by the language model. It is an independent, unofficial project built on top of the open source Timefold Solver. To use it, you need a recent Java version and a client, such as Claude Code or Claude Desktop, that can start local command line servers using the MCP protocol. You build the project into a single runnable file, or use the provided Docker image, then register it with your AI assistant using a short command or a small configuration snippet. Once connected, the assistant gains five tools: one that explains how to write a valid problem description, one that checks a description for errors, one that solves it, one that explains why a given solution scores the way it does, and one that helps figure out which rule is causing an unsolvable problem. The current version only supports one type of problem, where every entity gets exactly one value from a list, such as assigning exam sessions to time slots and rooms, or seats at a wedding table while avoiding conflicts. Several example problems are included, covering things like the eight queens puzzle, graph coloring, and task scheduling with capacity limits. Future plans include support for ordered sequences of assignments and an alternative solving backend for proving a solution is truly optimal. The project is released under the Apache 2.0 license.

prompts (copy fr)

prompt 1
Add solver-mcp to Claude Code and ask it to solve the included exam timetabling example spec.
prompt 2
Write a JSON assignment spec for a wedding seating problem with incompatible pairs and validate it with solver-mcp.
prompt 3
Use solver-mcp's diagnose_infeasible tool to find which hard constraint is making my spec unsolvable.
prompt 4
Build solver-mcp's Docker image and configure it as a stdio MCP server in Claude Desktop.

Frequently asked questions

what is solver-mcp fr?

A local MCP server that lets AI agents describe scheduling and assignment problems in JSON and get real, computed solutions from Timefold Solver.

What language is solver-mcp written in?

Mainly Kotlin. The stack also includes Kotlin, Timefold Solver, MCP.

What license does solver-mcp use?

Free to use, modify, and distribute for any purpose, including commercial use, as long as the copyright notice and license are kept.

How hard is solver-mcp to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is solver-mcp for?

Mainly developer.

peek the repo → explain another one

This repo across BitVibe Labs

double-check against the repo, no cap.