lasuite-docs-mcp

An MCP server for a self-hosted La Suite Docs instance. It lets an MCP client such as Claude Code search, browse, read, create, and edit Docs documents, and @-mention a favorited document straight into context.

Contents

• What it does

• Requirements

• Setup

  • 1. Register an OAuth client

  • 2. Configure the Docs instance

  • 3. Install

  • 4. Configure this tool

  • 5. Log in

  • 6. Check the instance

  • 7. Connect your MCP client

• Before you point it at real documents

• Troubleshooting

• CLI reference

• Known limitations

• Development

Related MCP server: Day 5 Remote MCP Server

What it does

Favorited documents are also exposed as MCP resources (docs://document/<id>), so they can be @-mentioned directly instead of fetched through docs_read.

Requirements

Setup touches three systems in order: your identity provider, the Docs instance, and then your own machine. The first two usually need whoever administers them.

Setup

1. Register an OAuth client

This tool logs in as a public OAuth client. Register one with your identity provider:

The redirect URI needs that wildcard port. login starts a loopback listener on an ephemeral port and builds the redirect URI from whatever port the OS hands it, so the port is different on every login. A single fixed-port entry works once and then fails. Providers that follow RFC 8252 §7.3 allow this; in Keycloak, http://127.0.0.1:*/callback is accepted verbatim.

2. Configure the Docs instance

Docs must run as an OIDC resource server:

OIDC_RESOURCE_SERVER_ENABLED=True
OIDC_OP_URL=https://sso.example.org/realms/main
OIDC_OP_INTROSPECTION_ENDPOINT=https://sso.example.org/realms/main/protocol/openid-connect/token/introspect
OIDC_RS_CLIENT_ID=docs-resource-server
OIDC_RS_CLIENT_SECRET=<secret of docs-resource-server>
OIDC_RS_AUDIENCE_CLAIM=client_id
OIDC_RS_ALLOWED_AUDIENCES=lasuite-docs-mcp
EXTERNAL_API={"documents":{"enabled":True,"actions":["list","retrieve","create","children","tree","search","content","content_retrieve","formatted_content","can_edit"]}}

That is the complete set. Restart Docs afterwards.

Two different clients are involved here, and both are called a client ID:

Notes on EXTERNAL_API and allowed audiences

EXTERNAL_API gates which API actions an external client may call. Every action in the list above is one this server actually calls, so none of them can be dropped. favorite_list is always permitted by Docs and needs no entry, which is why the resource listing works without one.

OIDC_RS_ALLOWED_AUDIENCES is a comma-separated list, so several clients can be allowed at once: OIDC_RS_ALLOWED_AUDIENCES=lasuite-docs-mcp,other-client.

3. Install

There is no npm release yet, so install from source:

git clone https://github.com/JonasDoebertin/lasuite-docs-mcp.git
cd lasuite-docs-mcp
npm ci
npm run build
npm link

4. Configure this tool

export DOCS_URL=https://docs.example.org
export DOCS_OIDC_ISSUER=https://sso.example.org/realms/main
export DOCS_OIDC_CLIENT_ID=lasuite-docs-mcp

5. Log in

lasuite-docs-mcp login

This opens a browser for an authorization-code-with-PKCE flow against your identity provider and stores the resulting tokens at ~/.config/lasuite-docs-mcp/<profile>.json, mode 0600.

6. Check the instance

lasuite-docs-mcp doctor

doctor probes four of the ten actions (list, search, tree, and formatted_content) and prints the full EXTERNAL_API value to set if any of them is blocked. The other six cannot be probed without creating or modifying something, so they are assumed available and report a classified error on first use instead. A clean doctor is a good sign rather than a guarantee that editing works.

7. Connect your MCP client

For Claude Code:

claude mcp add lasuite-docs \
  -e DOCS_URL=https://docs.example.org \
  -e DOCS_OIDC_ISSUER=https://sso.example.org/realms/main \
  -e DOCS_OIDC_CLIENT_ID=lasuite-docs-mcp \
  -- lasuite-docs-mcp-server

For any other client, run lasuite-docs-mcp-server over stdio with the same environment.

Before you point it at real documents

Writes replace a document's Yjs state in full, and the conversion that produces that state runs against block specs vendored from Docs v5.6.1. If your instance's block schema differs, a write can fail or mangle content.

npm run check:drift does not tell you this. It compares the vendored files against the pinned upstream release, not against your instance. The only real check is the contract suite:

npm run test:contract

Point it at a scratch instance, not your real one. It creates documents and deliberately never deletes them. Once it passes there, switch DOCS_URL over.

Troubleshooting

CLI reference

Known limitations

These are design constraints rather than bugs. Most of them come from what the Docs API does and does not offer.

An edit resets the document's Yjs history

Docs stores a document as a Yjs CRDT state, and every write from this tool replaces that state in full, the same way a fresh document would be written. Collaborative undo across that edit is gone afterwards. You can still step back through changes made after the edit, but not through the edit itself. Upstream Docs' own markdown import behaves identically, so this is not a shortcut this tool takes. It is how the endpoint works.

Editing is refused while someone has the document open

Docs rejects a write while a collaborative session is active over the websocket, and this tool does not use the flag that would bypass that check, because bypassing it would silently overwrite whatever that person is typing. docs_edit fails immediately in that case rather than retrying or queuing.

A whole-document replace refuses to discard unrepresentable blocks

Callouts, PDF blocks, upload loaders, and page breaks have no markdown representation, so a replace built from markdown alone would drop them silently. The tool refuses unless confirmLossy is set. append, prepend, and the section operations need no such guard, since they only touch the range you named.

Concurrent-modification detection is best effort

Before writing, the client re-reads the document's ETag and compares it against the value read at the start of the edit. Docs' PATCH /documents/{id}/content/ endpoint has no conditional-write support, so there is no If-Match and this is a manual before-and-after comparison rather than an atomic check. A narrow window remains where a concurrent write landing between the second read and the write itself can be lost. On an instance that strips ETags, such as one sitting behind a proxy that does not forward them, the check cannot run at all, and docs_edit says so plainly in its result.

BlockNote is pinned to 0.54.0 to match Docs v5.6.1

Content conversion runs @blocknote/server-util locally against block specs vendored from that Docs release. Targeting an instance whose block schema differs means repinning REF in scripts/vendor-blockspecs.sh, running npm run vendor, and getting npm run test:contract green before writes can be trusted again. Re-running npm run vendor on its own changes nothing: it re-fetches the same pinned release.

Only the first 50 favorites become resources

If your account has more than 50 favorited documents, the rest are not registered as docs://document/<id> resources and will not appear in @-mention. Docs' favorite_list endpoint takes no ordering parameter, so which 50 you get is whatever order the API happens to return, not "most recent" or anything else guaranteed. Documents past the cap remain reachable through docs_list and docs_read. When the cap is hit, the server writes a truncation notice to stderr; it does not appear anywhere in the MCP protocol responses.

Development

npm run build             # compile to dist/
npm test                  # unit tests
npx tsc --noEmit          # typecheck
npm run vendor            # re-fetch block specs from the ref pinned in scripts/
npm run check:drift       # vendored block specs vs that pinned ref
npm run test:contract     # live-instance suite, see tests/contract/README.md

See CLAUDE.md for the architecture and the invariants worth knowing before changing the edit or conversion paths.

License

MIT