Generate LLM artifacts for MCP server

.github/workflows/ci.yml

@@ -13,6 +13,17 @@ jobs:
         with:
           ruby-version: 3.2.2
           bundler-cache: true
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
       - name: Build Slate
         run: |
           ./deploy.sh -v --source-only
+      - name: Validate LLM artifacts
+        run: |
+          test -f build/docs.jsonl && echo '✓ docs.jsonl exists' || exit 1
+          test -f build/docs-index.json && echo '✓ docs-index.json exists' || exit 1
+          test -f build/llms.txt && echo '✓ llms.txt exists' || exit 1
+          node -e "require('fs').readFileSync('build/docs.jsonl','utf8').trim().split('\n').forEach((l,i)=>{JSON.parse(l)});console.log('✓ docs.jsonl is valid NDJSON')"
+          node -e "JSON.parse(require('fs').readFileSync('build/docs-index.json','utf8'));console.log('✓ docs-index.json is valid JSON');"

.github/workflows/publish.yml

@@ -15,6 +15,10 @@ jobs:
         with:
           ruby-version: 3.2.2
           bundler-cache: true
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
       - name: Setup git user
         run: |
           git config --global user.email "contact@killbill.io"

.gitignore

@@ -17,6 +17,7 @@ build/
 .vagrant
 .sass-cache
 .env
+node_modules/
 # YARD artifacts
 .yardoc
 _yardoc

README.md

@@ -4,6 +4,70 @@ Kill Bill API documentation.
 
 The site is built using [Middleman](https://github.com/middleman/middleman). See also https://github.com/slatedocs/slate.
 
+## Accessing Kill Bill Docs from AI Assistants (MCP)
+
+Kill Bill provides a **Model Context Protocol (MCP) server** that allows AI assistants to retrieve accurate, up-to-date documentation directly from our official docs corpus.
+
+Instead of relying on potentially outdated training data or web scraping, MCP enables assistants to search and fetch documentation through a deterministic API.
+
+This results in:
+
+- more accurate answers
+- fewer hallucinations
+- version-aware documentation retrieval
+- better code generation and testing workflows
+
+---
+
+### Server Information
+
+The Kill Bill MCP server is hosted privately and backed by the same artifacts used to generate this documentation site.
+
+**Endpoint**
+
+```
+
+[https://apidocs-mcp.killbill.io](https://apidocs-mcp.killbill.io)
+
+````
+
+**Available tools**
+
+| Tool | Description |
+|--------|-------------|
+| `searchDocs` | Finds relevant documentation sections |
+| `fetchDoc` | Retrieves the full content of a section |
+
+The server is read-only and optimized for fast retrieval.
+
+---
+
+### Example: Claude Desktop Configuration
+
+Add the server to your Claude MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "killbill-docs": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://apidocs-mcp.killbill.io"
+      ]
+    }
+  }
+}
+````
+
+After restarting Claude, you can ask questions like:
+
+> "How do I create a subscription in Kill Bill?"
+> "Show me an example catalog."
+> "Explain invoice generation flow."
+
+Claude will automatically pull from the official docs.
+
 ## Edit and Syntax
 
 The documentation is in the `source/includes` directory.
@@ -36,3 +100,61 @@ Notes:
 * The generated static pages under `build` are deployed by Cloudflare (https://apidocs.killbill.io/)
 * The built pages are also pushed to the `gh-pages` branch for debugging (served by GitHub pages at https://killbill.github.io/slate/ for backward compatibility)
 * Minification of assets is handled by Cloudflare (check-in the unminified version)
+
+## LLM Artifacts
+
+The build generates machine-consumable artifacts for LLM retrieval and MCP servers. These are produced automatically during the normal build process and deployed alongside the HTML site.
+
+| File | Purpose | Format |
+|------|---------|--------|
+| [`docs.jsonl`](https://apidocs.killbill.io/docs.jsonl) | Retrieval corpus — chunked by heading | Newline-delimited JSON |
+| [`docs-index.json`](https://apidocs.killbill.io/docs-index.json) | Lightweight search pre-filter | JSON array |
+| [`llms.txt`](https://apidocs.killbill.io/llms.txt) | Machine-readable site descriptor | Plain text |
+
+### Chunk Schema (`docs.jsonl`)
+
+Each line is a JSON object representing one retrieval chunk:
+
+```json
+{
+  "id": "catalog-upload-a-catalog-as-xml",
+  "title": "Upload a catalog as XML",
+  "url": "https://apidocs.killbill.io/catalog.html#upload-a-catalog-as-xml",
+  "section": "Catalog",
+  "version": "latest",
+  "headings": ["Catalog", "Catalog", "Upload a catalog as XML"],
+  "content": "...clean markdown...",
+  "keywords": ["catalog", "upload", "xml"],
+  "lastUpdated": "2026-02-12"
+}
+```
+
+Chunks are split on H2/H3 boundaries, targeting 400–1200 tokens. Code blocks and tables are never split.
+
+### Search Index Schema (`docs-index.json`)
+
+```json
+{
+  "id": "...",
+  "title": "...",
+  "url": "...",
+  "keywords": [],
+  "summary": "1-2 sentence description",
+  "headings": []
+}
+```
+
+### Generating locally
+
+```
+bundle exec middleman build --clean
+npm ci
+node scripts/generate-llm-artifacts.js
+```
+
+### Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BASE_URL` | `https://apidocs.killbill.io` | Canonical site URL for absolute links |
+| `VERSION` | `latest` | Version string embedded in every chunk |

cloudflare_deploy.sh

@@ -6,5 +6,5 @@ then
   bundle exec middleman build
 else
   mkdir build
-  mv fonts images javascripts stylesheets *.html build/
+  mv fonts images javascripts stylesheets *.html docs.jsonl docs-index.json llms.txt build/
 fi

deploy.sh

@@ -26,6 +26,11 @@ run_build() {
   else
     bundle exec middleman build --clean
   fi
+
+  # Generate LLM artifacts (docs.jsonl, docs-index.json, llms.txt)
+  npm ci --ignore-scripts
+  node scripts/generate-llm-artifacts.js
+
   # Add script for Cloudflare
   cp -f cloudflare_deploy.sh build/
 }