Skip to main content
Glama
Kofra Documentation MCP Server

Kofra Documentation MCP Server

Official
README.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)