<!-- ────────────────────────────────────────────────────────────────────── -->
<!--  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](https://modelcontextprotocol.io).
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.

```mermaid
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](https://www.dosbox.com/)** → see [DOSBox setup](docs/DOSBOX.md)

### 2 · Install & build
```bash
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>

```jsonc
{
  "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>

```bash
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` |

```text
▶  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

```mermaid
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](https://github.com/BBSRguy/turboc-mcp-server/issues) 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](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`](https://github.com/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>