fact_sim MCP Server (separate repo)

fact_sim_mcp is a standalone MCP server that controls the fact_sim web app from a separate repository.

Tools

1. load_example(example: string)
2. start_simulation()
3. stop_simulation()
4. run_benchmark(wallMs?: number)
5. export_timeline_csv()
6. build_share_url()
7. get_simulation_status()
8. get_kpi_summary()
9. run_scenario_matrix(examples: string[], wallMs?: number)
10. list_examples()
11. set_simulation_mode(mode: "dt" | "event")
12. set_playback_speed(speed?: number, fastest?: boolean)
13. reset_simulation_clock()
14. capture_snapshot_png(fileName?: string)
15. export_graph_json(pretty?: boolean)
16. import_graph_json(graphJson: string)
17. set_simulation_time(simTimeMs: number)
18. get_graph_overview(includeNodes?: boolean, maxNodes?: number)
19. export_embedded_html(fileName?: string)
20. save_timeline_csv(fileName?: string)
21. save_graph_json(fileName?: string, pretty?: boolean)
22. load_graph_json_file(filePath: string)
23. run_matrix_and_save_report(examples: string[], wallMs?: number, fileName?: string)
24. validate_graph_json(graphJson: string)
25. save_kpi_summary_json(fileName?: string, pretty?: boolean)
26. save_graph_overview_json(fileName?: string, includeNodes?: boolean, maxNodes?: number, pretty?: boolean)
27. evaluate_candidate_graph(graphJson: string, wallMs?: number, objective?: "throughput" | "throughput_per_node" | "balanced")
28. rank_candidate_graphs(candidates: string[], wallMs?: number, objective?: "throughput" | "throughput_per_node" | "balanced", topK?: number)
29. suggest_topology_improvements(graphJson: string, maxSuggestions?: number)
30. list_node_types()
31. add_node(nodeType: string, title?: string, x?: number, y?: number, properties?: Record<string, unknown>)
32. get_node_ports(nodeId: string | number)
33. get_node_ports_by_kind(nodeId: string | number, portKind: "work" | "signal" | "carrier" | "pallet")
34. connect_nodes_by_port_kind(fromNodeId: string | number, toNodeId: string | number, portKind: "work" | "signal" | "carrier" | "pallet", fromSlot?: number, toSlot?: number, allowDuplicate?: boolean)
35. connect_work_ports(fromNodeId: string | number, toNodeId: string | number, fromSlot?: number, toSlot?: number, allowDuplicate?: boolean)
36. connect_signal_ports(fromNodeId: string | number, toNodeId: string | number, fromSlot?: number, toSlot?: number, allowDuplicate?: boolean)
37. connect_carrier_ports(fromNodeId: string | number, toNodeId: string | number, fromSlot?: number, toSlot?: number, allowDuplicate?: boolean)
38. connect_pallet_ports(fromNodeId: string | number, toNodeId: string | number, fromSlot?: number, toSlot?: number, allowDuplicate?: boolean)
39. update_node(nodeId: string | number, title?: string, properties?: Record<string, unknown>, mergeProperties?: boolean)
40. connect_nodes(fromNodeId: string | number, toNodeId: string | number, fromSlot?: number, toSlot?: number, allowDuplicate?: boolean)
41. disconnect_nodes(linkId?: number, fromNodeId?: string | number, toNodeId?: string | number, fromSlot?: number, toSlot?: number, removeAllMatches?: boolean)
42. remove_node(nodeId: string | number)
43. clear_graph()
44. repair_graph_links()
45. run_simulation_for(wallMs: number, mode?: "dt" | "event", fastest?: boolean, includeBenchmark?: boolean, benchmarkWallMs?: number)
46. get_bottleneck_report(topN?: number, minSampleSec?: number)
47. describe_node_type(nodeType: string)
48. build_graph_from_blueprint(nodes: BlueprintNodeInput[], edges?: BlueprintEdgeInput[], clearExisting?: boolean, originX?: number, originY?: number, xPitch?: number, yPitch?: number)
49. optimize_line_by_bottleneck(iterations?: number, runWallMs?: number, bottleneckTopN?: number, minSampleSec?: number, maxNodesPerIteration?: number, processReductionRatio?: number, downReductionRatio?: number, minProcessTime?: number, minDownTime?: number)
50. set_takt_target_and_objective(taktSec: number, objectiveWeights?: { throughput?: number; taktGap?: number; cycleTime?: number; nodeCount?: number; linkCount?: number; completion?: number })
51. validate_layout_rules(minDistance?: number, forbiddenAdjacency?: string[])
52. run_design_of_experiments(paramGrid: DoeParamGridInput, wallMs?: number)
53. set_random_seed(seed: number)
54. get_random_seed()

Features

• Node.js + TypeScript
• Local stdio transport (for VSCode/Codex)
• Exception handling (tool-level, startup-level, process-level)
• Stderr logging with request ID (req:<id>)
• Minimal dependencies (@modelcontextprotocol/sdk, playwright, zod)

Directory layout

fact_sim_mcp/
  src/
    index.ts
    fact-sim-runtime.ts
  dist/                     # generated by npm run build
  .vscode/
    mcp.json                # VSCode local server definition
  package.json
  tsconfig.json
  mcp.config.example.json   # generic MCP client example
  README.md

Requirements

• Node.js 18+
• fact_sim repository with index.html available
• Chromium for Playwright

Install and build

npm install
npx playwright install chromium
npm run build

Run

npm start

The server targets fact_sim root in this order:

1. FACT_SIM_ROOT environment variable
2. sibling path ../fact_sim relative to this repository

If neither resolves to a directory containing index.html, startup fails with an explicit error.

VSCode/Codex configuration

Place fact_sim and fact_sim_mcp under the same parent directory. Then no environment variable is required.

.vscode/mcp.json (recommended)

{
  "servers": {
    "fact-sim-mcp": {
      "command": "node",
      "args": ["dist/index.js"]
    }
  }
}

Generic mcp.config.example.json

{
  "mcpServers": {
    "fact-sim-mcp": {
      "command": "node",
      "args": ["G:/マイドライブ/プログラミング/github/fact_sim_mcp/dist/index.js"]
    }
  }
}

If repositories are not siblings, set FACT_SIM_ROOT explicitly in your MCP client config.

Troubleshooting

• Playwright startup error: run npx playwright install chromium
• fact_sim root not found: set FACT_SIM_ROOT to the folder that contains index.html
• Port 8123 in use: server automatically falls back to an open local port