https://github.com/bitcryptic-gw/mdf-reference-server
Reference implementation of the MDF (Markdown First) spec — self-hostable Bun/Docker server with content negotiation, discovery, and payment stubs
https://github.com/bitcryptic-gw/mdf-reference-server
ai ai-agents bitcoin http l402 markdown markdown-first mdf open-source self-hosted web-standards x402
Last synced: about 6 hours ago
JSON representation
Reference implementation of the MDF (Markdown First) spec — self-hostable Bun/Docker server with content negotiation, discovery, and payment stubs
- Host: GitHub
- URL: https://github.com/bitcryptic-gw/mdf-reference-server
- Owner: bitcryptic-gw
- Created: 2026-05-28T02:38:29.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-30T11:01:37.000Z (about 1 month ago)
- Last Synced: 2026-05-30T11:09:10.224Z (about 1 month ago)
- Topics: ai, ai-agents, bitcoin, http, l402, markdown, markdown-first, mdf, open-source, self-hosted, web-standards, x402
- Language: TypeScript
- Homepage: https://github.com/bitcryptic-gw/mdf
- Size: 59.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# mdf-reference-server
Reference implementation of the [MDF (Markdown First)](https://github.com/bitcryptic-gw/mdf) spec.
A self-hostable server that serves markdown natively to AI agents via HTTP content negotiation, with structured discovery, payment-gated content tiers, and bearer token auth. Built with Bun, configured via a single YAML file, runs as a non-root Docker container.
**Live demo:** https://mdf-demo.bitcryptic.com
**Spec:** https://github.com/bitcryptic-gw/mdf
**Status:** v0.1.0-draft — payment verification is stubbed; see [open milestones](#status)
---
## Quick start
```bash
# Clone
git clone https://github.com/bitcryptic-gw/mdf-reference-server.git
cd mdf-reference-server
# Create the secrets directory and wallet address file
mkdir -p secrets
echo -n 0xYourWalletAddress > secrets/wallet_address
chmod 600 secrets/wallet_address
# Build and run
docker compose up --build
```
The server listens on port 3030 (host) → 3000 (container). The dashboard is on port 9090, no external mapping — access via Tailscale or internal network.
---
## Try it
```bash
# Discover the site's MDF capabilities
curl https://mdf-demo.bitcryptic.com/mdf.json
# Fetch the agent index
curl https://mdf-demo.bitcryptic.com/llms.txt
# Request markdown directly (agent-style)
curl -H "Accept: text/markdown" https://mdf-demo.bitcryptic.com/
# Free content — no payment required
curl -H "Accept: text/markdown" https://mdf-demo.bitcryptic.com/docs/getting-started
# Paid content — returns 402 with payment instructions
curl -H "Accept: text/markdown" https://mdf-demo.bitcryptic.com/premium/deep-dive
# Private content — returns 402 with auth endpoint hint
curl https://mdf-demo.bitcryptic.com/private/internals
```
---
## Configuration
All server configuration lives in `mdf.yaml`. The wallet address is never in config — it is read from `/run/secrets/wallet_address` at startup (file-mounted via Docker, not an env var).
```yaml
site:
url: https://your-domain.com
name: Your Site Name
contact: admin@your-domain.com
pricing:
default:
amount: "0.0001"
currency: USDC
chain: base
sections:
/docs/**:
amount: "0.0000"
/premium/**:
amount: "1.0000"
currency: USDC
chain: base
/private/**:
amount: "100.00"
currency: USDC
chain: base
```
See `mdf.yaml` in this repo for the full reference configuration.
---
## Content
Place markdown files under `content/`. The directory structure maps directly to URL paths. Frontmatter is supported. The server auto-generates `/mdf.json` and `/llms.txt` from `mdf.yaml` and the content directory at startup — no manual maintenance required.
---
## Payment rails
Two rails are implemented:
**L402 (Bitcoin/Lightning)** — production-complete. Creates real Lightning invoices via Alby Hub, issues HMAC-bound macaroons, and verifies preimage submission against settled invoice records.
**x402 (EVM/stablecoin)** — structural stub. Receipt shape is validated but on-chain settlement is not yet verified. See the [open issue](https://github.com/bitcryptic-gw/mdf/issues/3) for the x402 trust model discussion.
Sites advertise accepted rails via `payment.accepted_chains` in `/mdf.json`.
---
## Reverse proxy
A Caddy snippet is included at `caddy/Caddyfile`. Point your reverse proxy at port 3030.
---
## Status
| Feature | State |
|---------|-------|
| HTTP content negotiation (`Accept: text/markdown`) | ✅ Complete |
| `/mdf.json` + `/llms.txt` auto-generation | ✅ Complete |
| ETag / `Last-Modified` caching headers | ✅ Complete |
| Atom feed with `mdf:change_type` extension | ✅ Complete |
| WebSub hub declaration | ✅ Complete |
| Bearer token issuance (auth-via-payment) | ✅ Complete |
| Dashboard | ✅ Complete |
| L402 payment verification (Bitcoin/Lightning) | ✅ Complete |
| Validator CLI | ✅ Complete |
| x402 on-chain receipt verification | 🔲 Next milestone |
---
## Development
```bash
bun install
bun run src/index.ts
```
Run the smoke tests:
```bash
bash smoke-test.sh
```
36 tests across content negotiation, discovery, payment stubs, and auth — all passing.
---
## Authors
**Gary Walker** / [BitCryptic™](https://bitcryptic.com)
**Graham Hall** / [Slepner](https://slepner.com.au)
---
## License
MIT