@bytescope/mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+Fully offline: this server never touches the network — no telemetry, no API calls, no keys, no account.
+
+# @bytescope/mcp
+
+The [ByteScope](https://bytescope.dev) tools as an MCP server for coding agents: real byte-level
+file analysis (pcap, ELF, X.509, Intel HEX / UF2, HID descriptors, EXIF, SQLite), real test files
+(`generate_fixture`: PNG, ZIP, pcap, a certificate that expires in two days, MP4, SQLite, PDF, …)
+and reference lookups (USB ids, BLE UUIDs, HID usages, MIDI, ports, HTTP status codes, file
+signatures) that answer from real tables and say `found: false` instead of guessing.
+
+It is the same code as the website — the `core-*` packages behind every ByteScope page — bundled
+into one file with zero runtime dependencies. It speaks MCP over stdio.
+
+## Install
+
+Claude Code:
+
+```sh
+claude mcp add bytescope -- npx -y @bytescope/mcp
+```
+
+Any client that reads `.mcp.json` (Claude Code project scope, Cursor, …):
+
+```json
+{
+  "mcpServers": {
+    "bytescope": {
+      "command": "npx",
+      "args": ["-y", "@bytescope/mcp"]
+    }
+  }
+}
+```
+
+Requires Node.js 20 or newer.
+
+### Hosted endpoint (best effort)
+
+The same tool list is also served over streamable HTTP at `https://bytescope.dev/api/mcp` —
+stateless, anonymous, nothing stored:
+
+```sh
+claude mcp add --transport http bytescope https://bytescope.dev/api/mcp
+```
+
+Use it to try the tools, or for small inputs. It runs on Cloudflare Workers Free, so it has limits
+the local server does not:
+
+- **4 MB per call** — input, and a `generate_fixture` output — against 8 MB locally. Anything
+  larger gets an error that points back to `npx @bytescope/mcp`.
+- **About 10 ms of CPU per request.** Lookups, small binaries and most default fixtures fit. Calls
+  that do real work may be cut off: hashing more than a few kilobytes, RSA certificate fixtures,
+  audio/video fixtures, large images or databases, and the first `sqlite_schema` or
+  `lookup_usb_vendor` call on a fresh instance (engine start-up, table parse).
+- **Rate limited** per client IP (60 requests a minute). Over it you get HTTP 429 with a JSON-RPC
+  error and `Retry-After`.
+
+The local `npx` server is the real product: offline, no CPU cap, and your bytes never leave the
+machine. The hosted endpoint receives whatever you send it, so do not send it anything confidential.
+
+## Input convention
+
+Binary input is always a string in `data` plus `encoding`: `"base64"` (default; standard or
+URL-safe, line breaks and `data:` URIs accepted) or `"hex"` (spaces, `:` and `,` separators
+accepted). **File paths are never accepted.** One call may carry at most 8 MB of decoded input
+(4 MB on the hosted endpoint); larger inputs get an explicit error instead of exhausting memory.
+
+## Tools
+
+| Tool | What it does | Source package |
+|---|---|---|
+| `detect_file_type` | Real file type from magic bytes, with confidence, MIME and an extension check | `core-magic` |
+| `hash_bytes` | MD5, SHA-1, SHA-256, SHA-512, CRC-32 | `core-flash` (MD5), WebCrypto (SHA), `core-crc` (CRC-32) |
+| `crc_calculate` | Any reveng-catalogue CRC model, or custom Rocksoft parameters | `core-crc` |
+| `crc_reverse` | Recover the CRC model from known message/checksum pairs | `core-crc` |
+| `decode_certificate` | PEM / DER X.509 and CSRs: subject, SANs, validity, signature, key, fingerprints | `core-cert` |
+| `subnet_calc` | IPv4/IPv6 CIDR → network, hosts, masks, classification, subnet split | `core-ipcalc` |
+| `parse_pcap` | pcap / pcapng → packet list, streams, statistics, display filters | `core-pcap` |
+| `inspect_elf` | ELF header, program/section headers, symbols, dynamic section, notes | `core-elf` |
+| `parse_intel_hex` | Intel HEX, S-record, UF2 → address segments, gaps, record errors | `core-ihex` |
+| `decode_hid_descriptor` | HID report descriptor → annotated items, collections, reports | `core-hid` |
+| `parse_exif` | JPEG / PNG / TIFF metadata; **GPS is masked unless `includeGps: true`** | `core-image` |
+| `sqlite_schema` | SQLite file → tables, columns (type, PK, NOT NULL, default, FK), row counts, indexes, views, triggers, page size, versions | SQLite itself (sql.js WebAssembly, the engine /sqlite-viewer runs) |
+| `convert_subtitle` | SRT ↔ WebVTT ↔ ASS, with a report of what the target cannot carry | `core-subtitle` |
+| `generate_fixture` | Real test files (see below) | `core-fixture` |
+| `lookup_usb_vendor` | VID → vendor and products (linux-usb.org `usb.ids`) | `core-usb-ids` |
+| `lookup_usb_product` | VID:PID → vendor and product | `core-usb-ids` |
+| `lookup_ble_uuid` | 16/32/128-bit UUID → GATT service, characteristic or descriptor | `core-ble` |
+| `lookup_hid_usage` | Usage page + id → HID Usage Tables names | `core-hid` |
+| `lookup_midi_cc` | CC 0-127 → MMA controller assignment | `core-midi` |
+| `lookup_midi_manufacturer` | SysEx manufacturer id → company | `core-midi` |
+| `lookup_port` | Port number → service, transport, security notes | ByteScope port reference |
+| `lookup_http_status` | Status code → meaning and common confusions | ByteScope HTTP status reference |
+| `lookup_file_signature` | Leading bytes → formats whose magic numbers match | `core-magic` |
+
+Every `lookup_*` answer that is found carries `url` (the ByteScope page for that item) and `md`
+(its Markdown), so an agent can cite a source. When a table has no entry the answer is exactly
+`{ "found": false, … }` with the normalised query.
+
+## `generate_fixture`
+
+`generate_fixture({ kind, options })` returns `{ kind, files: [{ name, mime, bytes, base64 }] }`.
+Usually that is one file; a certificate comes with its private key, a split ZIP with one file per
+volume. Every generator is checked by reading its output back with an independent parser.
+
+| Kind | Options (all optional) |
+|---|---|
+| `png` `jpeg` `bmp` `webp` | `width`, `height`, `color`; `withExif` (JPEG, PNG) |
+| `gif` | size and colour, `frames`, `frameColors`, `delayMs`, `loop` |
+| `zip` | `fileCount`, `names`, `contents`, `method`, `encrypted`, `volumeSize` (split), `corrupt` (one named field) |
+| `pcap` `pcapng` | `packetCount`, `protocol` (TCP handshake, DNS query, HTTP GET), `host`, `startTime` |
+| `x509` | `commonName`, `subjectAltNames`, `validity` (`valid`, `expires-soon`, `expired`, `not-yet-valid`, `custom`), `days`, `keyAlgorithm`, `isCa`, `format` |
+| `mp4` `wav` `mp3` | `durationSeconds` and encoding; MP4 `moov` before or after the media data |
+| `sqlite` | `tables` with columns and row counts |
+| `elf` `intel-hex` `uf2` | minimal valid images: machine/class, address, payload size |
+| `pdf` | `pageCount`, `encrypted`, `embeddedFile` |
+
+The full schema of each kind is in the tool's input schema (`options.anyOf`, one entry per kind,
+titled with the kind). Certificate validity is relative to `now`, which defaults to the current
+time; pass `now` for a reproducible certificate.
+
+## Resources
+
+- `bytescope://tools` — the tool directory, identical to <https://bytescope.dev/tools.json>.
+- `bytescope://tool/{slug}` — a Markdown digest of one tool page (description, about, FAQ), with a
+  link to the canonical `https://bytescope.dev/en/<slug>.md`.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.