Turbo C MCP Server

<!-- ────────────────────────────────────────────────────────────────────── --> <!-- TURBO C MCP SERVER · README --> <!-- ────────────────────────────────────────────────────────────────────── -->

<a href="https://bbsrguy.github.io/turboc-mcp-server/"> <img src="https://capsule-render.vercel.app/api?type=waving&color=0:0b3d2e,50:00c853,100:00e5ff&height=220&section=header&text=Turbo%20C%20MCP%20Server&fontSize=46&fontColor=eafff3&fontAlignY=38&desc=Give%20your%20AI%20a%201992%20DOS%20C%20compiler&descSize=18&descAlignY=60&animation=fadeIn" alt="Turbo C MCP Server" /> </a>

<p align="center"> <a href="https://github.com/BBSRguy/turboc-mcp-server/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-00e5ff?style=for-the-badge&labelColor=0b0f14" alt="MIT License"></a> <img src="https://img.shields.io/badge/MCP-1.x-00c853?style=for-the-badge&labelColor=0b0f14" alt="MCP"> <img src="https://img.shields.io/badge/Node-%E2%89%A518-3c873a?style=for-the-badge&labelColor=0b0f14&logo=nodedotjs&logoColor=white" alt="Node ≥18"> <img src="https://img.shields.io/badge/TypeScript-strict-3178c6?style=for-the-badge&labelColor=0b0f14&logo=typescript&logoColor=white" alt="TypeScript"> <img src="https://img.shields.io/badge/DOS-16--bit-ffb300?style=for-the-badge&labelColor=0b0f14" alt="16-bit DOS"> <a href="https://github.com/BBSRguy/turboc-mcp-server/stargazers"><img src="https://img.shields.io/github/stars/BBSRguy/turboc-mcp-server?style=for-the-badge&labelColor=0b0f14&color=ffd400" alt="Stars"></a> </p>

<p align="center"> <img src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=700&size=22&pause=900&color=00E676&center=true&vCenter=true&width=820&lines=compile_and_run+%E2%86%92+real+Borland+Turbo+C+3.0;12+tools%3A+lint%2C+benchmark%2C+disassemble%2C+explain;A+full+DOS+C+studio%2C+driven+by+your+LLM;printf(%22Hello%2C+1992!%5Cn%22)%3B+%E2%9C%94+exit+0" alt="Typing banner" /> </p>

<p align="center"> <b><a href="https://bbsrguy.github.io/turboc-mcp-server/">🌐 Website</a></b> · <b><a href="#-quick-start">🚀 Quick Start</a></b> · <b><a href="#-the-toolbox-12-tools">🧰 Tools</a></b> · <b><a href="docs/DOSBOX.md">📦 DOSBox Setup</a></b> · <b><a href="#-examples">🎮 Examples</a></b> </p>

---

💾 What is this?

Turbo C MCP Server hands your AI assistant a genuine Borland Turbo C 3.0 toolchain over the Model Context Protocol. Your LLM doesn't simulate C anymore — it compiles and runs the real thing on the same 16-bit compiler a generation of programmers grew up on, and gets back true output, real Borland diagnostics, and cycle-accurate timing.

Ask Claude to "write a prime sieve in C and run it" — and it actually does, on TCC.EXE. Errors are real. exit 0 is earned.

flowchart LR
    A["🧠 LLM / Claude"] -- MCP stdio --> B["⚙️ turboc-mcp-server"]
    B -- TCC.EXE --> C["📀 Borland Turbo C 3.0"]
    C -- .EXE --> D["🖥️ DOS runtime / DOSBox"]
    D -- stdout · exit code · timing --> B
    B -- structured result --> A
    style A fill:#00c853,stroke:#eafff3,color:#04150d
    style B fill:#0b3d2e,stroke:#00e5ff,color:#eafff3
    style C fill:#ffb300,stroke:#0b0f14,color:#0b0f14
    style D fill:#37474f,stroke:#00e5ff,color:#eafff3

---

✨ Why it goes further than "run my C"

<table> <tr> <td width="50%" valign="top">

🛠 It's a studio, not a button

Twelve composable tools: compile-only checks, a static analyzer that runs without a compiler, an error explainer, an assembly disassembler, a benchmark harness, and a self-healing doctor.

🧠 Structured, model-friendly output

Every compile is parsed into error/warning objects with file + line, so your LLM can fix code surgically instead of squinting at raw logs.

</td> <td width="50%" valign="top">

🎮 Batteries + nostalgia included

A built-in library of 12 classic programs — Fibonacci, prime sieve, Towers of Hanoi, BGI graphics, conio colors — exposed as MCP resources.

📦 Runs on modern Windows

16-bit TCC.EXE can't run on 64-bit Windows? The included DOSBox bridge wrappers make compile and run work anywhere. One env var each.

</td> </tr> </table>

---

🚀 Quick Start

1 · Prerequisites

• Node.js ≥ 18
• Borland Turbo C 3.0 at C:\TURBOC3 (or set TURBOC_ROOT)
• 64-bit Windows? Also grab DOSBox → see DOSBox setup

2 · Install & build

git clone https://github.com/BBSRguy/turboc-mcp-server.git
cd turboc-mcp-server
npm install
npm run build

3 · Wire it into your MCP client

<details open> <summary><b>Claude Desktop</b> — <code>claude_desktop_config.json</code></summary>

{
  "mcpServers": {
    "turboc": {
      "command": "node",
      "args": ["C:/path/to/turboc-mcp-server/build/server.js"],
      "env": {
        "TURBOC_ROOT": "C:\\TURBOC3"
        // On 64-bit Windows, add the DOSBox bridge (see docs/DOSBOX.md):
        // "TCC_COMMAND": "C:\\TURBOC3\\wrappers\\dosbox-tcc.bat",
        // "MCP_C_RUN_COMMAND": "C:\\TURBOC3\\wrappers\\dosbox-run.bat"
      }
    }
  }
}

</details>

<details> <summary><b>Claude Code</b> — one command</summary>

claude mcp add turboc -- node C:/path/to/turboc-mcp-server/build/server.js

</details>

4 · Say hello

You: "Use turboc to run the hello example." AI: calls run_example → Hello, Turbo C! Compiled on real DOS iron. ✔ exit 0

Not sure it's wired up? Ask it to run environment_doctor — it verifies your whole toolchain and tells you exactly what's missing.

---

🧰 The toolbox (12 tools)

#	Tool	What it does
1	🟢 compile_and_run	Compile with TCC.EXE and run the DOS .EXE; capture stdout/stderr, exit code, timing, diagnostics
2	🔎 compile_check	Compile-only syntax/semantic check — fast, no execution
3	🧪 analyze_code	Static analysis without compiling: gets(), scanf &, = in if, brace balance, missing main, malloc checks, float-I/O traps
4	📖 explain_error	Plain-English cause + fix for any Turbo C compiler / linker / runtime message
5	⚙️ generate_asm	Emit the 16-bit x86 assembly listing (TCC -S) for any snippet
6	📚 list_examples	Browse the classic-program library (filter by category)
7	📄 get_example	Fetch the full source of any example
8	▶️ run_example	Compile and run an example in one shot
9	⏱️ benchmark	Run the program N times; report min / avg / max ms
10	🎨 format_code	Re-indent by brace depth, tidy whitespace — zero deps
11	🩺 environment_doctor	Verify TCC, INCLUDE, LIB, BGI, workspace — with fix hints
12	🧹 clean_workspace	Sweep old scratch sessions; keep the N most recent

Plus MCP resources (turboc://environment, turboc://examples/*) and prompts (debug-c-error, optimize-c, explain-program).

---

🎮 Examples

The bundled library (list_examples) covers every corner of the DOS C world:

Category	Programs
🟩 basics	hello, fibonacci
🧮 algorithms	prime-sieve, bubble-sort, hanoi, matrix-multiply
🎨 graphics	bgi-graphics (concentric circles via EGAVGA.BGI)
💽 dos	file-io, conio-colors
🗂 data	student-records (structs)
🕹 fun	pascal-triangle, number-guess

▶  run_example { "id": "prime-sieve" }

Compile: ✓ success  (312 ms, exit 0)
=== Run phase ===
Result: ✓ exit 0  (44 ms)
--- program stdout ---
Primes up to 100:
2 3 5 7 11 13 17 19 23 29 31 37 41 43 47 53 59 61 67 71 73 79 83 89 97

---

⚙️ Configuration

Everything is environment-driven, so one build works on every setup.

Variable	Default	Purpose
TURBOC_ROOT	C:\TURBOC3	Turbo C install root
TCC_COMMAND	…\BIN\TCC.EXE	Compiler entry point (or a DOSBox .bat)
MCP_C_RUN_COMMAND	(unset)	Wrapper to launch the compiled .EXE (DOSBox bridge)
TURBOC_INCLUDE	…\INCLUDE	Header search path
TURBOC_LIB	…\LIB	Library search path
TURBOC_BGI	…\BGI	BGI graphics drivers
MCP_C_WORKROOT	…\mcp_work	Scratch directory for sessions
MCP_C_TIMEOUT_MS	5000	Per-run execution timeout
MCP_C_COMPILE_TIMEOUT_MS	10000	Per-compile timeout
MCP_C_MAX_OUTPUT_BYTES	65536	Output cap returned to the model

---

🏗 Architecture

graph TD
    S[server.ts<br/>tools · resources · prompts] --> T[turboc.ts<br/>compile · run · asm · doctor]
    S --> A[analyze.ts<br/>heuristic linter]
    S --> E[errors-db.ts<br/>error knowledge base]
    S --> X[examples.ts<br/>classic programs]
    S --> F[format.ts<br/>C reformatter]
    T --> D[diagnostics.ts<br/>parse TCC output]
    T --> U[util.ts<br/>spawn · timeout · shell bridge]
    T --> C[config.ts<br/>env-driven paths]
    style S fill:#00c853,stroke:#04150d,color:#04150d
    style T fill:#0b3d2e,stroke:#00e5ff,color:#eafff3

Clean, single-responsibility modules — easy to read, easy to extend.

---

🗺 Roadmap

• [ ] Multi-file / project compilation
• [ ] BGI graphics → PNG capture via DOSBox screenshots
• [ ] Turbo Assembler (TASM) round-trip
• [ ] Memory-model presets (tiny/small/large) as first-class options
• [ ] npm one-line install (npx turboc-mcp-server)
• [ ] Watch mode + hot examples gallery on the website

Ideas welcome — open an issue or PR.

---

🤝 Contributing

PRs are warmly welcome. Fork → branch → npm run build → PR. New examples and error-DB entries are especially appreciated; see CONTRIBUTING.md.

---

⭐ Star history

<a href="https://star-history.com/#BBSRguy/turboc-mcp-server&Date"> <img src="https://api.star-history.com/svg?repos=BBSRguy/turboc-mcp-server&type=Date&theme=dark" alt="Star history" width="640"> </a>

If this brought a little 1992 magic to your AI, drop a ⭐ — it genuinely helps.

---

👤 Author

BBSRguy · @BBSRguy · rasran90@yahoo.com

Built for everyone who still hears the clrscr() flicker in their dreams. 🕹️

<p align="center"> <img src="https://capsule-render.vercel.app/api?type=waving&color=0:00e5ff,50:00c853,100:0b3d2e&height=120&section=footer" alt="footer" /> </p>