maciejewskii/solver-mcp

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.