Skip to main content
Glama
S9 Protocol MCP Server

S9 Protocol MCP Server

by jpdwebBRPT
README.md
# S9 Protocol (Beta) — Token-Efficient Web Compiler & Agent Skill

> **Status:** `Beta` · **License:** `MIT` · **Zero Dependencies** · **Language:** English | [Português (Brasil)](README.pt-BR.md)

**S9 Protocol (Semantic 9)** is a modular **microkernel DSL compiler**, **MCP server**, and **Agent Skill / Plugin** built to cut LLM output and context-window token usage when AI coding agents generate or iteratively edit web interfaces.

Instead of making an LLM stream hundreds of lines of repetitive `<div>`, `class="..."`, and closing `</div>` tags, the agent writes compact `.s9` semantic markup and compiles it locally—at **zero LLM token cost**—into **HTML5**, **Tailwind CSS**, or interactive **React JSX** (with automatic `useState` for tabs and modals).

---

## Where S9 Actually Pays Off (and Where It Doesn't)

We benchmarked `.s9` against compiled outputs while **explicitly accounting for the Tier-2 input token cost of reading `SKILL.md` (1,163 tokens)** using [`benchmarks/token-benchmark.js`](benchmarks/token-benchmark.js) (BPE pre-tokenizer estimator; install optional `js-tiktoken` for exact `cl100k_base`, or pass `--json` for CI telemetry):

| Sample File | `.s9` Source | Compiled HTML5 | Compiled Tailwind | Compiled React JSX | Net Saved (TW, 1st page) | 3-Turn Net (TW) |
| :--- | ---: | ---: | ---: | ---: | ---: | ---: |
| [`examples/saas-demo.s9`](examples/saas-demo.s9) | 1,144 | 3,198 (-64.2%) | 6,369 (-82.0%) | 2,418 (-52.7%) | **+4,062 tokens** | **+14,512 tokens** |
| [`examples/master.s9`](examples/master.s9) | 1,520 | 3,497 (-56.5%) | 6,692 (-77.3%) | 2,777 (-45.3%) | **+4,009 tokens** | **+14,353 tokens** |
| [`examples/pitch.s9`](examples/pitch.s9) | 775 | 1,313 (-41.0%) | 2,659 (-70.9%) | 1,213 (-36.1%) | **+721 tokens** | **+4,489 tokens** |
| [`examples/landing.s9`](examples/landing.s9) | 1,107 | 1,552 (-28.7%) | 2,777 (-60.1%) | 1,497 (-26.1%) | **+507 tokens** | **+3,847 tokens** |

### ✅ Use S9 when:
- **Building landing pages, marketing sites, docs, prototypes, dashboards, or HTML emails** rich in repetitive structural blocks (`nav`, `hero`, `stats`, `features`, `grid`, `pricing`, `table`, `tabs`, `modal`, `faq`).
- **Generating Tailwind CSS pages:** S9 removes the massive Tailwind utility-class repetition (`60%–82%` reduction), paying off the `SKILL.md` prompt cost on the **first page**.
- **Iterating across multiple turns:** When an agent re-reads a page to edit it, reading compact `.s9` saves input context on every single turn.
- **Compressing legacy HTML into context:** Use `audit` to convert verbose HTML5 into compact `.s9` before refactoring.

### ❌ Do NOT use S9 when:
- **Building complex stateful React/TypeScript applications** (custom hooks, Context/Redux, complex event handlers, business logic) — standard TSX/JSX is more expressive and avoids leaky abstractions.
- **Making a tiny 5-line HTML tweak:** The upfront `SKILL.md` read cost (~1.1k tokens) won't break even on a 10-line snippet.

---

## Installation & Agent Integration

### 1. Antigravity Plugin (Full Bundle)
- **Global (all projects):**
  ```bash
  git clone https://github.com/jpdwebBRPT/s9-protocol.git ~/.gemini/config/plugins/s9-protocol
  ```
- **Per-workspace (shared with your team via Git):**
  ```bash
  git clone https://github.com/jpdwebBRPT/s9-protocol.git .agents/plugins/s9-protocol
  ```

### 2. Claude Code / Cursor / Codex / Gemini CLI (Portable Agent Skill)
The [`skills/s9-protocol/`](skills/s9-protocol/SKILL.md) folder is **100% self-contained** (`s9-engine.js`, `s9-cli.js`, `s9-mcp.js`, `assets/s9-core.css`). Copy just `skills/s9-protocol/` into your agent's skills directory (and optionally reference [`rules/AGENTS.md`](rules/AGENTS.md)).

### 3. Optional MCP Server (Zero Expanded-HTML Context Overhead)
With the stdio MCP server (`s9_compile`, `s9_validate`, `s9_audit`), the agent sends compact `.s9` to `s9_compile` with an `outputPath`. The compiled HTML/Tailwind/JSX is written straight to disk without entering the LLM's context window.

Generate a ready-to-paste `mcp_config.json` snippet for your machine:
```bash
node skills/s9-protocol/scripts/s9-cli.js mcp-config
```

---

## CLI Usage

```bash
# Compile .s9 to HTML5 with strict validation & token telemetry
node skills/s9-protocol/scripts/s9-cli.js compile examples/saas-demo.s9 -o out.html --target html --strict --stats

# Compile to standalone dark-mode Tailwind CSS HTML
node skills/s9-protocol/scripts/s9-cli.js compile examples/saas-demo.s9 -o out.tw.html --target tailwind --strict

# Compile to interactive React JSX (auto-generates useState for tabs & modals)
node skills/s9-protocol/scripts/s9-cli.js compile examples/saas-demo.s9 -o SaasDemo.jsx --target react --name SaasDemo --strict

# Audit an existing HTML5 file and convert it to compact .s9
node skills/s9-protocol/scripts/s9-cli.js audit examples/benchmark_base.html --s9-out dist/benchmark.s9
```

---

## The 3-6-9 Language & Microkernel Architecture

- **`<3>` (Foundation):** Head metadata (`title`, `meta-desc`, `meta-og`, `font`, `style`), config, and variables (`set`).
- **`<6>` (Architecture):** Layout and content (`section`, `grid`, `table`, `stats`, `features`, `pricing`, `each`, `if`, plus any native HTML5 tag).
- **`<9>` (Peak Impact):** Isolated components (`props`, `state`, `css`, `template` with `[data-component-id]` CSS scoping and copy-on-write variable isolation) and interactive widgets (`hero`, `nav`, `tabs`, `modal`, `carousel`, `accordion`, `faq`).

Built on a **Microkernel (`src/kernel.js`)** so contributors can register custom macros (`kernel.registerMacro`) and new compilation targets (`kernel.registerTarget`) without editing the core, with `kernel.inspect()` override telemetry, `parseToAST()` structural metrics, left-associative prototype-guarded expressions, and path-sandboxed `include:` directives. See [`ARCHITECTURE.md`](ARCHITECTURE.md) for contributor details.

---

## Development & Verification

```bash
node scripts/build-dist.js          # Rebuild UMD root bundles & self-contained skill engine
node tests.js                       # Run full test suite (Kernel, Security, React/TW, CLI, MCP)
node benchmarks/token-benchmark.js  # Run token & break-even benchmark
node server.js                      # Start local preview server on http://localhost:3000
```

Interactive browser tools included in the repo:
- [`s9-benchmark.html`](s9-benchmark.html) — Live `.s9` editor, preview, and token telemetry
- [`check.html`](check.html) — HTML5 Semantic Auditor & `.s9` / JSX / Tailwind converter

## License & Contact

MIT — see [`LICENSE`](LICENSE). Contributions, issues, and experiments welcome during this Beta release!

- **GitHub:** [jpdwebBRPT/s9-protocol](https://github.com/jpdwebBRPT/s9-protocol)
- **Contact:** `jpdweb@yahoo.com`