Skip to main content
Glama
Hollerith-Necromancer MCP Server

Hollerith-Necromancer MCP Server

by JINGJAYHUANG
README.md
# Hollerith-Necromancer v2 ☠

**Resurrecting Dead 1964 IBM 029 80-Column Punch-Card Decks & System/360 `CP037`/`COMP-3` Tapes into a Zero-Dependency Forensic Ledger CLI, Stdio MCP Server & Haunted Phosphor CRT Web Workstation**

- **Live Haunted 1964 CRT Workstation (GitHub Pages)**: [https://jingjayhuang.github.io/kirospec-resurrection/](https://jingjayhuang.github.io/kirospec-resurrection/)
- **Hackathon**: [Kiroween 2026 (`kiroween.devpost.com`)](https://kiroween.devpost.com/) — Deadline **`2026-12-04`**
- **Categories**: **`Resurrection`** (Primary Track) + **`Costume Contest`** (Bonus Spooky UI Track)
- **Open-Source License**: **Apache-2.0** ([`LICENSE`](LICENSE))
- **Zero-Float &amp; Zero-Dependency Guarantee**: `0` IEEE-754 binary floats (`decimal.Decimal` in Python, `BigInt` integer cents in JavaScript), `0` runtime `pip`/`npm` packages, formula-free (`<f> == 0`) OpenXML `.xlsx` exports, and `0` external CDN requests.
- **Benchmark Provenance**: Bundled `data/1964_trust_deck.{bin,dck}` and `data/1964_ebcdic_journal.ebc` are deterministic synthetic archival test vectors (`SYNTHETIC_DETERMINISTIC_FIXTURE`) generated by [`src/dataset_generator.py`](src/dataset_generator.py).

---

## 1. What Dead Technology Does It Resurrect?

In 1964, financial institutions migrated accounting ledgers from **IBM 029 80-column 12-row Hollerith punch cards** (`Rows 12, 11, 0, 1..9`) onto **IBM System/360 `CP037` EBCDIC magnetic tapes** using COBOL `PIC S9(8)V99 DISPLAY` trailing zoned overpunches (`{, A..I` = `+0..+9`, `}, J..R` = `-0..-9`) and `PIC S9(9)V99 COMP-3` Binary-Coded Decimal (BCD) packed fields.

Modern ad-hoc conversion scripts routinely fail on archival mainframe media due to:
1. **IEEE-754 Float Drift**: Binary `float` arithmetic silently drops or invents cents across multi-hundred-voucher trial balances.
2. **Unposted Credit Overpunches**: Misreading EBCDIC `'}'` (`0xD0`, `-0`) or `'J'..'R'` (`0xD1..0xD9`, `-1..-9`) flips credit reversals into debits.
3. **Physical &amp; Magnetic Decay**: Lace-card multi-punches (`>= 6` holes in one column), dropped/swapped sequence trays (`Cols 73–80`), and magnetic-core `0xA` BCD nibble flips halt legacy readers.

**Hollerith-Necromancer v2** cross-reconciles `.bin` card frames and `.ebc` System/360 tape records simultaneously in both **Python (`Decimal`)** and **Browser/Node.js (`BigInt`)**, quarantining corruptions ("Specters") with SHA-256 frame evidence and recovering an exact `$0.00`-variance trial balance (`$1,060,998.85 == $1,060,998.85`).

---

## 2. Kiro Feature Usage (`/.kiro/` Tracked at Root)

Per official Kiroween rules, the root [`.kiro/`](.kiro/) directory is tracked in Git and explicitly protected by `!.kiro/` and `!.kiro/**` in [`.gitignore`](.gitignore):

- **Specs ([`.kiro/specs/hollerith-necromancer/`](.kiro/specs/hollerith-necromancer/))**:
  - [`requirements.md`](.kiro/specs/hollerith-necromancer/requirements.md): EARS-formatted requirements across CLI, MCP, OpenXML `<f>==0` export, and isomorphic `BigInt` browser binary reconciliation.
  - [`design.md`](.kiro/specs/hollerith-necromancer/design.md): Architecture diagram, bit-level IBM 029 / `CP037` / `COMP-3` layouts, and 9 formal Correctness Properties (`CP-1..CP-9`).
  - [`tasks.md`](.kiro/specs/hollerith-necromancer/tasks.md): Completed `[x]` engineering tasks traced directly to automated tests.
- **Steering ([`.kiro/steering/{product,tech,structure}.md`](.kiro/steering/))**: Always-included guardrails enforcing `0` binary floats, `0` fabricated metrics, `<f>==0` OpenXML workbooks, and `< 2 MB` repository size.
- **Agent Hooks ([`.kiro/hooks/*.json`](.kiro/hooks/))**: Three automated `fileEdited` hooks running `pytest`, `node --test`, and `.gitignore` / zero-float compliance gates on save.
- **Stdio MCP Server ([`.kiro/settings/mcp.json`](.kiro/settings/mcp.json) &rarr; [`mcp_server/hollerith_mcp.py`](mcp_server/hollerith_mcp.py))**: Exposes `inspect_punch_card`, `decode_comp3_hex`, `audit_legacy_deck`, and `export_clean_ledger` over JSON-RPC 2.0 `stdin`/`stdout`.

---

## 3. Quick Start (CLI, Static Web UI &amp; Automated Tests)

```bash
# 1. Generate deterministic synthetic 1964 .bin/.dck/.ebc fixtures & reconcile via CLI
PYTHONDONTWRITEBYTECODE=1 python3 -B -m src.cli generate-fixture --data-dir data
PYTHONDONTWRITEBYTECODE=1 python3 -B -m src.cli reconcile --data-dir data --outputs-dir outputs

# 2. Inspect Card #47 (lace-card tear) or dissect COMP-3 BCD hex from CLI
PYTHONDONTWRITEBYTECODE=1 python3 -B -m src.cli inspect-card --bin data/1964_trust_deck.bin --card 47
PYTHONDONTWRITEBYTECODE=1 python3 -B -m src.cli dissect-comp3 00000142550D

# 3. Open the 100% offline Haunted 1964 Phosphor CRT Workstation
open web/index.html

# 4. Run full deterministic Node + Python verification suites
node --test tests_js/hollerith_core.test.js
PYTHONDONTWRITEBYTECODE=1 python3 -B -m pytest -p no:cacheprovider -q tests/test_kiroween_v2.py
```

## 4. Static Deployment (Working URL) &amp; Submission Guide

Pushing `main` to a public GitHub repository publishes the root static workstation + `data/` directly via **GitHub Pages** (`https://jingjayhuang.github.io/kirospec-resurrection/`). See [`docs/DEVPOST_SUBMISSION_PACK.md`](docs/DEVPOST_SUBMISSION_PACK.md) for the complete `2026-12-04` Devpost submission checklist and 3-minute demo video shotlist.