Kofra Documentation MCP Server
OfficialREADME.md
# kofra-mcp
Kofra MCP servers. Today this is the public documentation MCP server: a Cloudflare Worker that lets an AI
client search and read the Kofra documentation, the API reference and the error catalogue, with no login. An
account MCP server may follow later.
**Status:** not deployed.
**Indexing:** `X-Robots-Tag: noindex` on every response (pages, discovery files, MCP answers and errors) is
the authoritative no-index control for the preview. `/robots.txt` also disallows everything, deliberately,
until launch; while it does, compliant crawlers never fetch `/llms.txt` or `/.well-known/mcp.json` either, so
the discovery files only reach clients that are pointed at them. When and how to open indexing at launch is
an open decision.
## What the Worker serves
| Path | What it is |
| ----------------------- | ---------------------------------------------------------------------- |
| `/docs` | MCP endpoint (Streamable HTTP, stateless, no login) |
| `/docs/<slug>.md` | One documentation page as Markdown |
| `/llms.txt` | Markdown links to every page |
| `/.well-known/mcp.json` | MCP discovery: names the `/docs` endpoint on the origin that serves it |
| `/robots.txt` | `Disallow: /` (pre-launch) |
| `/` | A short plain-text index of the above |
MCP tools, both read-only and free of account data:
- `docs_search`: ranked search (BM25) over every page; returns slugs, titles and snippets.
- `docs_read`: one page as Markdown, by slug.
MCP resources: `kofra://docs/<slug>` (every page), `kofra://openapi` (the API contract as JSON) and
`kofra://errors/<code>` (one error catalogue entry each).
Browser requests must come from an exact allow-listed origin (`https://kofra.app`, `www.`, `console.` or `mcp.`
on https, default port); local origins are accepted only when the server itself runs locally. Anything else
gets 403, and `Access-Control-Allow-Origin` echoes the accepted origin, never `*`. Non-browser clients send no
`Origin` and are not affected. Only successful static responses are cacheable (`public, max-age=3600`); errors
are `no-store`. Every string the server returns is checked at build time to contain no control, escape or
invisible characters, and tool text is sanitised again at run time.
## Content
| Path | Where it comes from |
| -------------------------- | ----------------------------------------------------------------------------- |
| `content/openapi.json` | Copied from kofra-api `generated/` by `tools/sync-content.mjs` |
| `content/errors.json` | Same |
| `content/docs/errors/*.md` | Same |
| `content/SOURCE` | The kofra-api commit the copies come from |
| `content/docs/*.md` | Written here (overview, AI agents) |
| `content/docs/api/*.md` | Generated by `tools/generate.mjs`, one page per API operation |
| `generated/content.json` | Generated: pages, search index, contract and catalogue, shipped in the Worker |
| `discovery/` | Generated: `llms.txt`, `robots.txt`, `.well-known/mcp.json` |
To pick up a new contract: `node tools/sync-content.mjs <path to a kofra-api checkout>`, then commit
`content/`, `generated/` and `discovery/`. Never edit the copied or generated files by hand; `pnpm run build`
fails when they are stale.
## Development
Requires Node 24 (see `.node-version`) and pnpm 10.
```sh
pnpm install
pnpm run dev # wrangler dev, local Workers runtime
pnpm run lint # prettier --check and eslint
pnpm run format # prettier --write
pnpm run check # wrangler types and tsc
pnpm run test:unit # vitest, the Worker called in-process with the MCP SDK client
pnpm run build # generate --check, then a wrangler dry-run bundle in dist/
pnpm run test:e2e # wrangler dev plus the MCP SDK client over HTTP, both protocol eras
pnpm run f7 # deny-list over every tracked file
pnpm run f7:build # deny-list over dist/, content/, discovery/ and generated/
```
None of these needs a Cloudflare account. `worker-configuration.d.ts` is generated by `wrangler types` and is
not committed.
## Deployment
Not enabled from this repository: there is no deploy workflow. The Worker name is `kofra-mcp-docs`, with a
`workers.dev` preview and no per-version preview URLs.
## Contributing and security
See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
## Licence
[MIT](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues