shopfloor-mcp

An MCP server that lets AI assistants such as Claude and Cursor read and schedule manufacturing work orders, without double-booking a machine or quietly changing data.

I built a React/FastAPI scheduling platform during my internship at Micro-ant. This project asks the next question: what does it take to let an AI agent work with a production schedule safely?

You:     Which orders are at risk this week, and can you fit the gearbox housing on a mill on Monday?
Claude:  → late_risk_report → list_resources → find_next_slot(resource 1, 6h) → schedule_work_order(...)
         "Order #3 (Mesa Drones, due Nov 3) had nothing booked. I scheduled it on CNC Mill 1, Nov 2 08:00–14:00."

Tools

Related MCP server: MCP Calendar Assistant

Guardrails for agents

• Typed, validated inputs. Pydantic constraints (for example 0 < hours ≤ 24, positive IDs, ISO datetimes) are published in each tool's JSON schema, so bad calls are rejected before any code runs.

• No silent conflicts. Scheduling checks the resource's existing bookings and fails with the clashing block, so the agent can explain the problem or pick another slot.

• Errors the model can act on. Expected failures come back as tool errors with a plain reason (Resource 4 is already booked: …), not a stack trace.

• Tool annotations. Each tool declares read_only_hint and destructive_hint, so clients can ask the user before a destructive call.

• Read-only mode. Set SHOPFLOOR_READ_ONLY=1 to expose the data while blocking every write.

Run it

git clone https://github.com/champion-buzz/shopfloor-mcp && cd shopfloor-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q            # 13 tests
shopfloor-mcp        # starts the server on stdio (creates shopfloor.db with demo data)

Use it from Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "shopfloor": {
      "command": "/absolute/path/to/shopfloor-mcp/.venv/bin/shopfloor-mcp",
      "env": { "SHOPFLOOR_DB": "/absolute/path/to/shopfloor.db" }
    }
  }
}

Restart Claude and ask: "Show me open work orders due before Nov 6 and schedule the most urgent one on the first free mill."

You can also inspect it with the MCP Inspector: npx @modelcontextprotocol/inspector shopfloor-mcp

Design

src/shopfloor_mcp/
├── db.py          SQLite schema and demo seed data
├── scheduling.py  pure scheduling logic: overlaps, next free slot, utilization, late risk
└── server.py      MCP layer: tool definitions, validation, annotations, read-only guard
tests/
├── test_scheduling.py  logic tests
└── test_server.py      tests through the MCP tool interface

The scheduling logic doesn't depend on MCP, so it's tested on its own and could sit behind a REST API (for example FastAPI) unchanged.

Ideas for next steps

• Split jobs longer than one workday across several days automatically

• Streamable HTTP transport with auth, for a shared deployment

• An eval set of natural-language requests to measure how well an LLM picks tools

License

MIT