# thedocs

Documents for agents and people. Publish a file and it is served as-is, with its own content type, at a stable URL. No wrapper page, no script rewriting: `curl` gets exactly what was published.

- A project lives at `https://<project>.thedocs.stream/`.
- A document lives at `https://<project>.thedocs.stream/<path>`.
- Every publish makes a version. Read an old one with `?v=<n>`; pinned versions are immutable and cached forever.
- Relative links resolve inside the project, so a site can be several files: `index.html`, `style.css`, `guide.md`.
- A project root with no `index.html` or `index.md` lists its documents with their titles and summaries.
- Every version carries a title, a summary, and metadata (string key/value pairs) you can filter on.

## Visibility

Projects are private until a token holder sets them `unlisted` (readable by link) or `public` (listed and searchable), with `setProjectVisibility` or `PUT /_thedocs/settings` and `{"visibility": "public"}`. People log in at `https://thedocs.stream/_thedocs/login` with Cloudflare Access; agents send the bearer token.

## MCP

Connect any MCP client to `https://thedocs.stream/mcp` (Streamable HTTP, stateless protocol `2026-07-28`).

```sh
claude mcp add --transport http thedocs https://thedocs.stream/mcp --header "Authorization: Bearer $THEDOCS_TOKEN"
```

Tools: `listProjects`, `listDocs`, `readDoc`, `docHistory`, `searchDocs`, and with a token `publishDoc` and `removeDoc`. Without a token the server is read-only.

## HTTP

```sh
# publish (new version); content type comes from the header or the extension
curl -X PUT https://finite.thedocs.stream/guide.md \
  -H "Authorization: Bearer $THEDOCS_TOKEN" \
  -H "x-thedocs-message: first draft" \
  --data-binary @guide.md

# read the latest, or pin a version
curl https://finite.thedocs.stream/guide.md
curl "https://finite.thedocs.stream/guide.md?v=1"

# title, summary, and metadata (per-key headers, or x-thedocs-metadata: {"k":"v"}; {} clears)
curl -X PUT https://finite.thedocs.stream/plan.md -H "Authorization: Bearer $THEDOCS_TOKEN" \
  -H "x-thedocs-title: Q4 plan" -H "x-thedocs-summary: What we ship this quarter." \
  -H "x-thedocs-meta-status: draft" -H "x-thedocs-meta-owner: jesse" --data-binary @plan.md

# filter by metadata on any JSON endpoint, alone or with q=
curl "https://finite.thedocs.stream/_thedocs/docs?meta.status=draft"
curl "https://finite.thedocs.stream/_thedocs/search?q=widget&meta.owner=jesse"

# remove (history is kept)
curl -X DELETE https://finite.thedocs.stream/guide.md -H "Authorization: Bearer $THEDOCS_TOKEN"
```

Send `x-thedocs-base-version: <n>` to publish only if the latest version is still `n` (0 means the path must be new); otherwise you get 409.

JSON endpoints on every project host:

- `GET /_thedocs/docs[?prefix=]` lists documents
- `GET /_thedocs/history/<path>` lists versions
- `GET /_thedocs/search?q=` searches the project
- add `meta.<key>=<value>` to filter any of these on metadata (`q` is optional when filtering)

On `https://thedocs.stream`: `GET /_thedocs/projects` lists the projects you can see. Search is per project.