From bdf4a03ef63b3c6cc5a3c3a93ae91debc4ab204d Mon Sep 17 00:00:00 2001 From: Caio Pizzol Date: Wed, 12 Aug 2026 22:28:35 -0300 Subject: [PATCH 1/3] fix(ci): deploy MCP with Bun --- .github/workflows/deploy.yml | 2 ++ README.md | 43 +++++++++++++++++++++++------------- 2 files changed, 30 insertions(+), 15 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 11b308f..96af055 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -85,3 +85,5 @@ jobs: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} workingDirectory: apps/mcp-server + # This subdirectory has no Bun lockfile, so automatic detection falls back to npm. + packageManager: bun diff --git a/README.md b/README.md index 9b7bc06..459eabc 100644 --- a/README.md +++ b/README.md @@ -2,28 +2,41 @@ [![Web](https://img.shields.io/github/v/tag/superdoc/ooxml-dev?filter=%40ooxml-dev%2Fweb%40*&label=Web&color=blue)](https://ooxml.dev) [![MCP Server](https://img.shields.io/github/v/tag/superdoc/ooxml-dev?filter=%40ooxml-dev%2Fmcp-server%40*&label=MCP%20Server&color=blue)](https://api.ooxml.dev/mcp) +[![npm: not published](https://img.shields.io/badge/npm-not%20published-CB3837?logo=npm)](#cli) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) The OOXML spec, explained by people who actually implemented it. ## What is this? -An interactive reference for OOXML, built by the team behind [SuperDoc](https://superdoc.dev). Every page combines XML structure, live rendered previews, and implementation notes the spec leaves out. The MCP server exposes the same knowledge to AI assistants: prose search across the spec PDFs and deterministic schema lookup over the parsed XSDs. +ooxml.dev is an interactive OOXML reference built by the team behind [SuperDoc](https://superdoc.dev). It combines XML examples, live previews, and implementation notes with searchable specification text and schema data. -- **Live previews** - Edit XML and see it render in real-time. Every example is a working document. -- **Implementation notes** - Where Word diverges from the spec, what will break your code, and what to do about it. -- **Semantic spec search** - 18,000+ spec chunks searchable by meaning via MCP server. -- **Structural schema lookup** - Element children, attributes, types, enums, namespaces. Same MCP server, deterministic answers from the parsed XSDs. +- **Live previews** — Edit XML and see the result immediately. Every example is a working document. +- **Implementation notes** — Learn where Word differs from the specification and which details can break an implementation. +- **Specification search** — Search more than 18,000 specification chunks by meaning. +- **Schema lookup** — Inspect element children, attributes, types, enums, and namespaces from the parsed XSDs. ## Why? -The ECMA-376 spec is 5,000+ pages and it lies. Word's actual behavior diverges from the standard in ways you only discover by building against it. The knowledge to implement OOXML correctly is locked inside a handful of companies that have no incentive to share it. +ECMA-376 is more than 5,000 pages, and Word sometimes behaves differently from the standard or fills in details the text leaves unclear. Many of these differences appear only while building a document engine. -We faced this at SuperDoc — building a document engine on native OOXML with no roadmap beyond an unreliable spec. We wrote down everything we learned and made it public. No one should have to reverse-engineer Word alone. +We found these gaps while building SuperDoc. This project records what we learned so other implementers do not need to discover the same edge cases alone. + +## CLI + +The private CLI gives people and agents a stable shell interface to the same reference. Run it from the repository root: + +```bash +bun run ooxml login +bun run ooxml search "paragraph spacing" +bun run ooxml element w:p +``` + +The package is not published to npm yet. During this private beta, it stores sign-in tokens as plain text in the current user's application data directory. Do not use it from a shared account. See the [CLI README](apps/cli/README.md) for details. ## MCP Server -Ask questions in natural language and get answers grounded in the spec, or query the schema graph for precise structural answers. Works with Claude Code, Codex CLI, Cursor, and any MCP-compatible client. +Search specification prose or query the schema graph for precise structural answers. The server works with Claude Code, Codex CLI, Cursor, and other MCP clients. **Claude Code** @@ -44,7 +57,9 @@ Or in `~/.codex/config.toml`: url = "https://api.ooxml.dev/mcp" ``` -**Cursor** — add to your MCP settings: +**Cursor** + +Add the server to your MCP settings: ```json { @@ -63,7 +78,7 @@ Four tool families share one server: ### Authentication -`/mcp` uses OAuth 2.1. Compatible MCP clients register automatically, open the ooxml.dev sign-in and consent pages, and receive a token limited to this MCP server. Clerk handles user identity; the MCP server handles dynamic client registration, PKCE, tokens, refresh, and revocation. +`/mcp` uses OAuth 2.1. Compatible clients register automatically and open the ooxml.dev sign-in and consent pages. Clerk verifies the user's identity. The MCP server handles dynamic client registration, PKCE, resource-bound tokens, refresh, and revocation. ## Development @@ -75,15 +90,13 @@ bun run build # Production build bun run build:prod # Build with .env.prod ``` -Vite+ owns the web development, build, formatting, linting, workspace task, and Git hook -workflows. Bun remains the package manager and test runtime because the test suite uses `bun:test`. +Vite+ handles local development, builds, formatting, linting, workspace tasks, and Git hooks. Bun remains the package manager and test runtime because the tests use `bun:test`. -`build:prod` requires a live Clerk publishable key. This prevents production deploys from using the -auth fallback or a test Clerk instance. +`build:prod` requires a live Clerk publishable key. This prevents a production deployment from using the auth fallback or a test Clerk instance. ## Contributing -Contributions welcome. Add implementation notes, fix examples, or improve the reference. +Contributions are welcome. Add implementation notes, fix examples, or improve the reference. ## License From ddf23669259c3f76b7f6ffdcecfbf216713071fd Mon Sep 17 00:00:00 2001 From: Caio Pizzol Date: Thu, 13 Aug 2026 06:33:25 -0300 Subject: [PATCH 2/3] feat(cli): prepare npm release --- .github/workflows/release.yml | 2 ++ README.md | 36 ++++++++++++++++++++++--------- apps/cli/README.md | 40 ++++++++++++++++++++++++----------- apps/cli/package.json | 8 +++++-- package.json | 8 +------ 5 files changed, 63 insertions(+), 31 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e47a311..254bd90 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -41,3 +41,5 @@ jobs: publish-script: bun run release:publish commit-message: "chore(release): version packages" pr-title: "chore(release): version packages" + env: + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/README.md b/README.md index 459eabc..df275aa 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,14 @@ [![Web](https://img.shields.io/github/v/tag/superdoc/ooxml-dev?filter=%40ooxml-dev%2Fweb%40*&label=Web&color=blue)](https://ooxml.dev) [![MCP Server](https://img.shields.io/github/v/tag/superdoc/ooxml-dev?filter=%40ooxml-dev%2Fmcp-server%40*&label=MCP%20Server&color=blue)](https://api.ooxml.dev/mcp) -[![npm: not published](https://img.shields.io/badge/npm-not%20published-CB3837?logo=npm)](#cli) +[![npm](https://img.shields.io/npm/v/%40ooxml-dev%2Fcli?label=CLI&color=CB3837&logo=npm)](https://www.npmjs.com/package/@ooxml-dev/cli) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) The OOXML spec, explained by people who actually implemented it. +> [!NOTE] +> The CLI and MCP server use the production ooxml.dev service. You may need to create an account and sign in. Sign-in is only used to control usage; the service is free. + ## What is this? ooxml.dev is an interactive OOXML reference built by the team behind [SuperDoc](https://superdoc.dev). It combines XML examples, live previews, and implementation notes with searchable specification text and schema data. @@ -24,20 +27,37 @@ We found these gaps while building SuperDoc. This project records what we learne ## CLI -The private CLI gives people and agents a stable shell interface to the same reference. Run it from the repository root: +Install the CLI with npm. Node.js 20 or later is required. ```bash -bun run ooxml login -bun run ooxml search "paragraph spacing" -bun run ooxml element w:p +npm install --global @ooxml-dev/cli ``` -The package is not published to npm yet. During this private beta, it stores sign-in tokens as plain text in the current user's application data directory. Do not use it from a shared account. See the [CLI README](apps/cli/README.md) for details. +Sign in, then query the reference: + +```bash +ooxml login +ooxml search "paragraph spacing" +ooxml element w:p +``` + +See the [CLI README](apps/cli/README.md) for all commands. + +## Agent skill + +The [`research-ooxml`](skills/research-ooxml/SKILL.md) skill teaches coding agents how to combine specification search and schema evidence through the CLI. Install the CLI first, then add the skill: + +```bash +npx skills add superdoc/ooxml-dev --skill research-ooxml -g -y +``` ## MCP Server Search specification prose or query the schema graph for precise structural answers. The server works with Claude Code, Codex CLI, Cursor, and other MCP clients. +> [!NOTE] +> The hosted server uses MCP `2026-07-28` and remains compatible with current 2024 and 2025 clients. + **Claude Code** ```bash @@ -76,10 +96,6 @@ Four tool families share one server: - **Package metadata** (curated from Part 1 §11.3.x / §12.3.x / §13.3.x / §15.x): `ooxml_package_part` - **Preset shapes** (generated from Part 1 Annex D): `ooxml_preset_shape` -### Authentication - -`/mcp` uses OAuth 2.1. Compatible clients register automatically and open the ooxml.dev sign-in and consent pages. Clerk verifies the user's identity. The MCP server handles dynamic client registration, PKCE, resource-bound tokens, refresh, and revocation. - ## Development ```bash diff --git a/apps/cli/README.md b/apps/cli/README.md index 0576fa9..e43f762 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -1,22 +1,38 @@ # OOXML CLI -Use the OOXML reference from a terminal or an agent skill. Sign in with Clerk to query the hosted ooxml.dev service. +Use the OOXML reference from a terminal or an agent skill. -While the package is private, run it from the repository root: +## Install + +Node.js 20 or later is required. ```bash -bun run ooxml login -bun run ooxml search "paragraph spacing" -bun run ooxml element w:p -bun run ooxml children w:p -bun run ooxml attributes w:p -bun run ooxml logout +npm install --global @ooxml-dev/cli ``` -During this private test, the CLI stores sign-in tokens as plain text in your application data directory. Do not use it from a shared account. The CLI does not store queries or results. +## Use the CLI -The bundled [`research-ooxml`](../../skills/research-ooxml/SKILL.md) skill tells agents which commands to use and how to combine schema and specification evidence. +Sign in, then query the reference: -MCP is an internal transport detail. It is not part of the CLI or skill interface. +```bash +ooxml login +ooxml search "paragraph spacing" +ooxml element w:p +ooxml children w:p +ooxml attributes w:p +ooxml logout +``` + +The CLI uses the production ooxml.dev service. You may need to create an account and sign in. Sign-in is only used to control usage; the service is free. + +The CLI stores sign-in tokens as plain text in your application data directory. Do not use it from a shared account. It does not store queries or results. -The package remains private while we test it. Secure credential storage and npm publishing are separate release steps. +## Install the agent skill + +The bundled [`research-ooxml`](../../skills/research-ooxml/SKILL.md) skill tells coding agents which commands to use and how to combine schema and specification evidence. + +```bash +npx skills add superdoc/ooxml-dev --skill research-ooxml -g -y +``` + +MCP is an internal transport detail. It is not part of the CLI or skill interface. diff --git a/apps/cli/package.json b/apps/cli/package.json index 22bfcb8..46c908a 100644 --- a/apps/cli/package.json +++ b/apps/cli/package.json @@ -2,10 +2,10 @@ "name": "@ooxml-dev/cli", "version": "0.1.0", "description": "Query the ooxml.dev reference from a terminal or agent skill.", - "private": true, + "license": "MIT", "type": "module", "bin": { - "ooxml": "./dist/cli.mjs" + "ooxml": "dist/cli.mjs" }, "files": [ "dist" @@ -13,9 +13,13 @@ "engines": { "node": ">=20" }, + "publishConfig": { + "access": "public" + }, "scripts": { "build": "vp pack --clean", "dev": "bun src/cli.ts", + "prepublishOnly": "bun run build", "typecheck": "tsc --noEmit" }, "dependencies": { diff --git a/package.json b/package.json index 5c55cdb..96f042f 100644 --- a/package.json +++ b/package.json @@ -54,13 +54,7 @@ "overrides": { "vite": "catalog:" }, - "devEngines": { - "packageManager": { - "name": "bun", - "version": "1.3.14", - "onFail": "download" - } - }, + "packageManager": "bun@1.3.14", "catalog": { "typescript": "7.0.2", "vite": "npm:@voidzero-dev/vite-plus-core@0.2.9", From a9a4c14261632ababa3fafa8922c72ce09be7ee6 Mon Sep 17 00:00:00 2001 From: Caio Pizzol Date: Thu, 13 Aug 2026 06:48:53 -0300 Subject: [PATCH 3/3] fix(release): authenticate npm publishing --- .github/workflows/release.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 254bd90..d374ec8 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -31,6 +31,7 @@ jobs: - uses: actions/setup-node@v6 with: node-version: 24 + registry-url: https://registry.npmjs.org - run: bunx --package vite-plus@0.2.9 vp install --frozen-lockfile @@ -42,4 +43,4 @@ jobs: commit-message: "chore(release): version packages" pr-title: "chore(release): version packages" env: - NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}