MCP FET Integration

Model Context Protocol (MCP) server that exposes FET — Liviu Lalescu’s free school/university timetable generator — as tools for ChatGPT, Claude, Gemini, Cursor, and other MCP clients.

This repository is the integration layer (TypeScript MCP server + docs). FET itself remains upstream software under AGPL-3.0.

Why TypeScript?

FET’s heavy solver stays in C++/Qt (fet-cl). This MCP server owns the editable .fet XML model and orchestrates generation around that binary.

Related MCP server: P6-MCP

FET upstream pin

The GitHub repo stores release archives, not an incremental source tree. Use npm run fetch-fet (see vendor/README.md). Do not commit the multi‑GB archive history.

Configurable feature map: docs/fet-configurable-features.md. Assignment text → .fet: docs/fet-from-assignments.md. Natural language → timetable: docs/fet-nl-timetable.md. Private-sample NL coverage notes: docs/private-sample-nl-coverage.md (real .fet only outside the repo, never published). Constraint advisor: docs/fet-advise.md. ChatGPT packaging + Streamable HTTP bridge: docs/chatgpt-mcp-plugin.md. Failed generate diagnosis: docs/fet-diagnose.md.

MCP tool surface (v0.7 — intelligent constraint advisor)

Design: a small meta-tool set over a round-trip XML document model, plus fet-cl job tools. All 275 time + 82 space + 1 generation-option constraint types from FET 7.12 are addressable by name (no 357 hard-coded handlers). v0.3 adds generation from structured Italian assignment lines. v0.4 explains blocking constraints when generation fails (fet_diagnose). v0.5 adds fet_nl_build / fet_nl_patch. v0.6 adds full NL phrase coverage (358 live) + ChatGPT packaging. v0.7 adds fet_advise / fet_advise_apply: heuristics grounded in IT school practice recommend MinDays, SameStartingTime, PreferredRoom, BreakTimes, MaxHoursDaily, NotAvailable, Consecutive, … even when the user does not know the FET type name. The advisor proposes; FET still generates the timetable. The MCP is not the chat LLM — ChatGPT/Claude/Gemini/Cursor call these tools. Real institute .fet stay outside this repository (never committed, never advertised to ChatGPT).

Documents (workspace)

Entities (CRUD by kind)

students uses the FET hierarchy: Year → Group → Subgroup (nested in fields).

Constraints (schema-driven, full catalog)

fields mirrors FET XML: leaf tags → strings, repeated tags → arrays, nested blocks → objects/arrays of objects. Common tags: Weight_Percentage, Active, Comments.

From teacher assignments (v0.3)

Sample: examples/from-assignments/. Mapping rules: docs/fet-from-assignments.md.

Natural language timetable (v0.5–v0.6)

Sample: examples/from-nl/ (Antonio scenario). Mapping + known gaps: docs/fet-nl-timetable.md.

Constraint advisor (v0.7)

Sample: examples/advise/. Guide: docs/fet-advise.md. Reminder: advisor proposes constraints; fet_generate still builds the timetable.

Diagnose blockers (v0.4)

Sample conflict: examples/diagnose/. Guide: docs/fet-diagnose.md.

Generation / I/O

Typical flows

A. From linguaggio naturale (classi spezzate, modifiche)

1. fet_nl_build with Italian prose (or fet_nl_parse first)

2. If gaps → ask the user using gaps[].ask, then fet_nl_patch / rebuild with filled intent

3. Optional: fet_advise → review suggestions → fet_advise_apply

4. fet_document_save → fet_generate → fet_diagnose if needed

B. From incarichi riga-per-riga

1. fet_from_assignments with Italian assignment text (ask on ambiguities if needed)

2. fet_document_summary / refine with fet_entity_* / fet_constraint_*

3. fet_document_save → fet_generate

4. If failed: read diagnosis or call fet_diagnose

C. Manual edit → generate

1. fet_document_new or fet_document_open

2. fet_entity_upsert (subjects, teachers, students, activities, rooms, …)

3. fet_constraint_schema → fet_constraint_add as needed

4. fet_document_save → data/input/….fet

5. fet_generate → fet_job_status / fet_export / fet_diagnose

npm run smoke:nl      # examples/from-nl → antonio-from-nl.fet
npm run smoke:advise  # stripped Antonio sample → advise + apply

Quick start (Windows)

cd "C:\path\to\MCPFETIntegration"
npm install
npm run fetch-fet   # if vendor/fet-src is missing
npm run generate-catalog   # regenerate constraint catalog from FET headers (already committed)
npm run build

Install fet-cl (Windows)

Official Liviu package (no Qt toolchain required):

npm run fetch-fet-windows
# → vendor\bin\fet-7.12.0\fet-cl.exe
$env:FET_CL_PATH = "C:\path\to\MCPFETIntegration\vendor\bin\fet-7.12.0\fet-cl.exe"

Alternatively build from vendor/fet-src/fet-7.12.0/ (CMake + Qt 6, C++17) per FET’s README.

Run the MCP server (stdio)

npm run start
# or during development:
npm run dev

The process waits on stdin for an MCP client. Logs go to stderr only.

Run the Streamable HTTP bridge (ChatGPT / remote MCP)

ChatGPT cloud cannot speak stdio to this PC. Run the local bridge on loopback, then connect ChatGPT via Secure MCP Tunnel (tunnel_id) or an opt-in HTTPS tunnel — not by pasting http://127.0.0.1… (ChatGPT rejects it).

$env:FET_CL_PATH = "C:\path\to\MCPFETIntegration\vendor\bin\fet-7.12.0\fet-cl.exe"
$env:MCP_HTTP_TOKEN = "long-secret"   # required if MCP_HTTP_ALLOWED_HOSTS is set
npm run mcp:http
# health (local only): http://127.0.0.1:3847/health
# opt-in public HTTPS URL helper: npm run mcp:http:tunnel -- -IUnderstandPublicExposure

See docs/chatgpt-mcp-plugin.md (rejected-settings error, Tunnel vs URL). Smoke: npm run smoke:http.

Connect clients

Example configs live in config/. Replace the absolute path with your machine path.

Claude Desktop / Claude MCP

{
  "mcpServers": {
    "fet": {
      "command": "node",
      "args": [
        "C:\\path\\to\\MCPFETIntegration\\build\\index.js"
      ],
      "env": {
        "FET_CL_PATH": "C:\\path\\to\\fet-cl.exe"
      }
    }
  }
}

See config/mcp.claude.example.json, config/mcp.chatgpt.example.json, config/mcp.gemini.example.json.

Cursor

Ready snippet: config/mcp.cursor.json (merge fet into %USERPROFILE%\.cursor\mcp.json).

Repository layout

MCPFETIntegration/
  src/                 TypeScript MCP server + FetDocument model
  src/fet/catalog/     Generated constraint catalog (358 types)
  scripts/             fetch-fet, generate-catalog, copy-catalog
  vendor/              FET pin docs (+ local extracted sources, gitignored)
  examples/            Sample .fet + from-assignments + from-nl + advise + diagnose conflict
  data/                Runtime input/output/jobs (gitignored contents)
  docs/                Feature catalog + NL + advise + diagnose guides
  config/              Example MCP client configs
  LICENSE              AGPL-3.0
  NOTICE               Attribution
  CONTRIBUTING.md

License and attribution

• This project: AGPL-3.0-only (LICENSE)

• FET: AGPL-3.0 by Liviu Lalescu — see NOTICE and THIRD_PARTY.md

If you deploy this as a network service that users interact with, AGPL requires you to offer Corresponding Source.

GitHub

Public repository: https://github.com/marconodio-ux/MCPFETIntegration

Real institute .fet are kept outside this repo (and private/ is gitignored with no tracked exceptions). node_modules/, vendor/bin|archives|fet-src/, and secrets stay gitignored and are not published. Public main has no real institute .fet blobs.

Status

v0.7.0 — Constraint advisor: fet_advise / fet_advise_apply recommend and optionally write catalog constraints (MinDays, SameStartingTime, PreferredRoom, …) from school heuristics. Advisor proposes; FET generates. Built on v0.6 full-catalog NL, v0.5 NL build/patch, v0.4 diagnose, v0.3 from-assignments.