A complete, production-grade command-line interface and Model Context Protocol (MCP) server for controlling and automating JFLAP 7.1 (JFLAP7.1.jar).
Standard JFLAP is a legacy Java Swing application without native command-line or headless automation support. This repository bridges directly into JFLAP's internal classes (file.XMLCodec, automata.*, grammar.*) to provide fast, robust, headless execution, simulation, conversion, batch testing, and AI-driven control without popping up Swing dialogs.
- Highlights
- Quick Start
- CLI Command Overview
- Model Context Protocol (MCP) Integration
- Documentation Index
- Architecture & Quirks Resolved
- License & Acknowledgments
- โก Headless Execution: Fast simulation of DFAs, NFAs, Pushdown Automata (PDA), Turing Machines (single and multi-tape), Mealy, and Moore machines.
- ๐ฌ Formal Language Transformations:
- NFA
$\rightarrow$ DFA conversion (nfa-to-dfa) - DFA minimization to canonical states (
minimize) - Language Equivalence checking (
equals) using minimization & isomorphism algorithms - FSA to Regular Expression extraction (
convert fsa-to-re) - Combine multiple automata into composite machines (
fsa combine)
- NFA
- ๐ Grammar Parsing & Transformation:
- FIRST and FOLLOW set computation with LL(1) parseability checking (
grammar first-follow) - CYK Parser for Chomsky Normal Form (CNF) with derivation tracing
- Brute-Force derivation parser
- Production cleaner (eliminates
$\lambda$ /$\epsilon$, unit, and useless rules)
- FIRST and FOLLOW set computation with LL(1) parseability checking (
- ๐ฟ L-System (Lindenmayer System) Engine:
- Deterministic and stochastic parallel rewriting string expansion at arbitrary derivation depth (
lsystem expand)
- Deterministic and stochastic parallel rewriting string expansion at arbitrary derivation depth (
- ๐ Cross-Model Conversions:
- FSA
$\rightarrow$ Regular Expression - FSA
$\leftrightarrow$ Regular Grammar (Right-Linear) - CFG
$\rightarrow$ Pushdown Automaton (LL / LR) - PDA
$\rightarrow$ Context-Free Grammar (CFG)
- FSA
- ๐ ๏ธ Programmatic Model Builder: Create valid JFLAP
.jffXML files via CLI flags or JSON definitions. - ๐ Graphviz Export: Export any automaton to standard Graphviz
.dotformat. - ๐ค Native MCP Server: Ready-to-use Model Context Protocol server exposing 10 tools to Claude Desktop, Antigravity, Cursor, and other agentic systems.
- Java: JRE/JDK 8 or higher (
java -version). - Python: Python 3.8 or higher (
python --version).
Clone the repository:
git clone https://github.com/MatMridul/jflap-cli.git
cd jflap-cliOptional: Install as a Python package to put jflap on your PATH:
pip install -e .Note: On first run, jflap will automatically compile the Java bridge (JFLAPBridge.java) if .class files are missing.
Run commands with jflap (or python jflap_cli.py):
jflap inspect examples/contains_ab_nfa.jffOutputs an ASCII table showing state coordinates, initial/final flags, transition rules, and determinism.
jflap simulate examples/contains_ab_nfa.jff ab aabb bab bba xyzOutputs:
Simulation Results for: contains_ab_nfa.jff
Input String | Result
-------------+---------
'ab' | ACCEPTED
'aabb' | ACCEPTED
'bab' | ACCEPTED
'bba' | REJECTED
'xyz' | REJECTED
# Step-by-step trace showing stack evolution on a Pushdown Automaton
jflap trace examples/an_bn_pda.jff aabb
# Step-by-step trace showing tape transformations on a Turing Machine
jflap trace examples/an_bn_cn_turing.jff abcFormally prove whether a student's submission or alternative machine accepts the exact same language:
jflap fsa equals examples/contains_ab_nfa.jff examples/contains_ab_min_dfa.jff
# Result: The two automata ARE EQUIVALENT (accept the exact same language).# Convert NFA to DFA
jflap fsa nfa-to-dfa examples/contains_ab_nfa.jff dfa.jff
# Minimize DFA
jflap fsa minimize dfa.jff min_dfa.jff
# Extract Regular Expression from FSA
jflap convert fsa-to-re examples/contains_ab_dfa.jff
# Output: Regular Expression: b*(aa*bb*+aa*bb*a(a+bb*a)*(?+bb*))
# Combine Two Automata into One
jflap fsa combine dfa1.jff dfa2.jff combined.jff
# Convert CFG to PDA (LL Mode)
jflap convert cfg-to-pda examples/an_bn_cfg.jff pda.jff --mode ll
# Convert Regular Grammar to FSA
jflap convert rg-to-fsa examples/regular_grammar_ab.jff fsa.jff# Parse string with CYK or Brute-Force
jflap grammar parse examples/regular_grammar_ab.jff aab
# Compute FIRST & FOLLOW Sets and test LL(1) parseability
jflap grammar first-follow examples/an_bn_cfg.jff# Expand L-System to level 4
jflap lsystem expand examples/fibonacci_lsystem.jff 4
# Output: ABAABABA (length 8)jflap dot examples/contains_ab_min_dfa.jff -o machine.dot# Create an FSA directly
jflap create fa --states q0,q1,q2 --initial q0 --finals q2 --transitions "q0,q1,0; q1,q2,1; q2,q2,0,1" -o parity.jff
# Or build from a JSON definition
jflap create --from-json examples/sample_spec.json -o generated.jff# Launch the standard JFLAP 7.1 graphical desktop interface
jflap gui examples/contains_ab_min_dfa.jffThe built-in MCP server (jflap_mcp.py / jflap mcp) allows AI assistants and autonomous agents to inspect, simulate, convert, and construct automata models directly.
{
"mcpServers": {
"jflap": {
"command": "python",
"args": ["<PATH_TO_REPO>/jflap_mcp.py"]
}
}
}{
"mcpServers": {
"jflap": {
"command": "python",
"args": ["<PATH_TO_REPO>/jflap_mcp.py"]
}
}
}{
"mcpServers": {
"jflap": {
"command": "python",
"args": ["<PATH_TO_REPO>/jflap_mcp.py"]
}
}
}For Windsurf, Zed, and headless subagent shell execution, see the Agent Setup Guide.
-
jflap_inspect: Inspect.jfffile structure, determinism, completeness, unreachable states, and dead states. -
jflap_simulate: Simulate input strings on any automaton with explicit PDA acceptance mode (final_stateorempty_stack). -
jflap_simulate_batch: High-performance batch simulation of hundreds or thousands of inputs in a single call. -
jflap_trace: Step-by-step configuration trace (state, stack, tape, accept verdict). -
jflap_export_table: Export a plain JSON transition table for DFA/NFA runtime executors. -
jflap_equivalence_check: Check language equivalence between two FSAs, returning shortest distinguishing string on mismatch. -
jflap_fsa_operation: NFA$\rightarrow$ DFA, minimization, language equivalence check, and automata combination (combine). -
jflap_grammar_operation: CYK / Brute-force grammar parsing, rule cleaning, and FIRST / FOLLOW set analysis (first_follow). -
jflap_convert_model: Cross-formalism conversion (FSA$\rightarrow$ RE, FSA$\leftrightarrow$ RG, CFG$\leftrightarrow$ PDA). -
jflap_lsystem_expand: Parallel L-System symbol rewriting and derivation to depth$n$ . -
jflap_create_model: Programmatically build a.jfffile from JSON. -
jflap_export_dot: Export an automaton to Graphviz DOT. -
jflap_launch_gui: Open the model in the interactive JFLAP 7.1 desktop window.
See docs/MCP_SPECIFICATION.md for full schemas and sample payloads.
To meet the zero-latency safety requirements of build-time verification (such as the Chimeric Automaton verifier), the bridge features a warm, long-lived background JVM worker process communicating via line-delimited JSON over stdio pipes.
| Mode | Calls / Inputs | Total Time | Latency per Call / Input | Speedup |
|---|---|---|---|---|
| Spawn-per-call (previous baseline) | 10 calls | 2,743 ms | 274.3 ms (min 252.0ms, max 309.2ms) | 1.0x (baseline) |
| Persistent JVM Bridge | 10 calls | 38.9 ms | 3.89 ms (min 1.83ms, max 6.66ms) | ~70x faster |
Batch Mode (jflap_simulate_batch) |
1,000 inputs | 628.71 ms | 0.628 ms per input | >400x faster |
All figures are directly measured using time.perf_counter() on the test automaton contains_ab_dfa.jff.
- AI Agent Setup Guide: Configuration instructions for Antigravity, Claude, Cursor, Windsurf, Zed, and subagents.
- Architecture & Technical Design: How the Java headless bridge works and how Swing modal blocks were neutralized.
- MCP Specification: Tool-by-tool JSON schema, request parameters, and response structures.
- CLI Reference Manual: Comprehensive documentation of all subcommands, arguments, and flags.
-
Bypassing Embedded
JOptionPaneDialogs:- In JFLAP's
PDAStepByStateSimulator, the constructor pops up a modal dialog asking whether to accept by "Final State" or "Empty Stack". We engineered aHeadlessPDASimulatorextendingAutomatonSimulatorthat operates silently without GUI requirements. - In
TransducerFactory, single-tape Turing machines prompt a modal dialog asking whether to open as standard TM or Building Blocks. We preemptively detect Turing models in DOM and instantiateTMTransducerdirectly.
- In JFLAP's
-
Explicit PDA Acceptance Modes:
- PDA simulation evaluates strictly one acceptance criterion:
"final_state"(input consumed AND current state in$F$ ) or"empty_stack"(input consumed AND stack height is 0). Both criteria are never conflated into an unsound "either/or" check.
- PDA simulation evaluates strictly one acceptance criterion:
-
Infinite Loop Prevention:
- Bounded BFS state exploration ensures that non-deterministic pushdown automata with
$\lambda$ -transitions or non-terminating Turing machines do not hang or exhaust system memory.
- Bounded BFS state exploration ensures that non-deterministic pushdown automata with
-
Automated On-Demand Build:
- The CLI and MCP server automatically invoke
javacifJFLAPBridge.classis absent or older thanJFLAPBridge.java.
- The CLI and MCP server automatically invoke
This repository maintains a clean, transparent license split:
-
CLI, MCP Server, Python Utilities & Java Bridge Wrappers:
- Licensed under the open-source MIT License.
- Copyright (c) 2026 Mridul Mathur. Free for commercial and non-commercial use, modification, and integration.
-
JFLAP 7.1 Upstream Binary & License (
third_party/jflap/):- JFLAP 7.1 is academic software developed by Prof. Susan H. Rodger and student contributors at Duke University (https://www.jflap.org/).
- Isolated cleanly in
third_party/jflap/JFLAP7.1.jar. - Covered by the verbatim third_party/jflap/LICENSE-JFLAP:
- Copyright (c) 2002โ2009 Susan H. Rodger, Duke University. All rights reserved.
- Key Terms:
- The verbatim license text is bundled at
third_party/jflap/LICENSE-JFLAP. - No fee may be charged for any product containing JFLAP in source or binary form.
- Duke University and author names may not be used to endorse or promote derived products without prior written permission.
- The verbatim license text is bundled at