---

md2pkt is a Windows-first CLI that turns Markdown or text-based PDF network assignments into Cisco Packet Tracer .pkt files. it reads the instructions, normalizes the topology, plans the missing details, generates PTBuilder JavaScript and IOS config, then sends the build to a local Packet Tracer bridge.

the first target is CCNA-style lab work: routers, switches, PCs, servers, DHCP, static routing, OSPF, EIGRP, RIP, and simple LAN/WAN layouts. Packet Tracer stays the source of truth for the final .pkt file.

npm | github

why

Packet Tracer labs often start as a paragraph, rubric, or PDF assignment. md2pkt gives that text a direct path into a runnable topology without turning the workflow into a manual redraw.

• accepts .md, .txt, and text-based .pdf inputs
• uses deterministic defaults when an assignment leaves details out
• prefers codex exec for one-turn planning, with OpenAI API and deterministic fallback paths
• generates deployable PTBuilder JavaScript and per-router IOS config artifacts
• targets a small local bridge protocol instead of a full Packet Tracer replacement
• includes Windows Explorer right-click registration for .md and .pdf

quickstart

install the CLI:

npm install -g md2pkt

from a checkout:

npm install
npm run build
npm link

check the local machine:

md2pkt doctor

install the Packet Tracer bridge bootstrap:

md2pkt bridge install

open Cisco Packet Tracer, go to Extensions -> Scripting -> Configure PT Script Modules, add the printed Builder.pts path, then open Extensions -> Builder Code Editor, paste the printed bootstrap script, and run it. then build a lab:

md2pkt build assignment.md --out assignment.pkt --engine auto

inputs

md2pkt build accepts:

input	support
.md	read directly
.txt	read directly
.pdf	converted through a MarkItDown-compatible CLI

text-based PDFs are in scope for v1. scanned PDFs need OCR before md2pkt can reliably infer a topology.

command surface

command	purpose
md2pkt build <file> --out <file.pkt>	convert an assignment into a queued Packet Tracer build
md2pkt doctor	check Node.js, Codex, MarkItDown, OpenAI API, bridge, and Packet Tracer signals
md2pkt bridge install	copy Builder.pts, write the PTBuilder bootstrap script, and print setup instructions
md2pkt bridge status	check the local bridge endpoint
md2pkt bridge repair	rewrite the bootstrap script
md2pkt context-menu install	add Explorer right-click actions for .md and .pdf
md2pkt context-menu remove	remove those Explorer actions

engine selection:

md2pkt build lab.md --out lab.pkt --engine auto
md2pkt build lab.md --out lab.pkt --engine codex
md2pkt build lab.md --out lab.pkt --engine api

auto tries Codex first, then the OpenAI API when OPENAI_API_KEY is set, then deterministic inference.

bridge model

md2pkt targets a PTBuilder polling bridge on http://127.0.0.1:54321.

flowchart LR
    input[markdown or pdf]
    md2pkt[md2pkt cli]
    plan[topology spec]
    artifacts[ptbuilder js and ios config]
    bridge[local bridge :54321]
    pt[packet tracer]
    pkt[pkt file]

    input --> md2pkt
    md2pkt --> plan
    plan --> artifacts
    artifacts --> bridge
    bridge --> pt
    pt --> pkt

Loading

the bridge protocol is intentionally small:

endpoint	purpose
GET /status	reports bridge health
POST /enqueue	accepts { "script": "...", "out": "C:\\path\\file.pkt" }
GET /next	returns the next PTBuilder script for Packet Tracer to run

If a running Packet Tracer MCP bridge exposes POST /queue instead of POST /enqueue, md2pkt build falls back to posting the raw PTBuilder JavaScript to /queue.

the Packet Tracer side polls /next from the Builder Code Editor and runs returned JavaScript through $se('runCode', ...).

generated artifacts

each build writes sidecar files next to the requested .pkt path:

artifact	purpose
<out>.ptbuilder.js	Packet Tracer deployment script
<out>.ios.txt	generated IOS config blocks
<out>.md2pkt-report.json	normalized topology, assumptions, warnings, and human report

these files make the build inspectable even when Packet Tracer or the bridge is unavailable.

assumptions

v1 makes deterministic assumptions instead of asking follow-up questions:

• no router count means one router
• no switch count means one access switch per router LAN
• no host count means two PCs
• multi-router topologies use static routing unless OSPF, EIGRP, or RIP is requested
• LANs use sequential 192.168.x.0/24 networks
• inter-router links use sequential 10.0.x.0/30 networks

assumptions and warnings are written into the build report.

windows explorer

register right-click actions for .md and .pdf:

md2pkt context-menu install

after registration, right-click an assignment file and choose Build Packet Tracer .pkt. the output path uses the same basename with a .pkt extension.

remove the entries:

md2pkt context-menu remove

development

npm install
npm run typecheck
npm test
npm run build

the test suite uses a local fake bridge, so it does not require Cisco Packet Tracer.

current boundaries

• Cisco Packet Tracer 8.2+ must already be installed.
• .pkt is the canonical output. .pkz is out of scope for v1.
• the deterministic generator records VLAN, NAT, and ACL intent but does not fully configure those features yet.
• real .pkt saving depends on the PTBuilder environment exposing a save function.
• the upstream bridge reference inspected for this project is Mats2208/MCP-Packet-Tracer, which is MIT-licensed.

license

MIT, matching the package metadata.