# lichtblick-docs-mcp POC
MCP server exposing the Lichtblick documentation and the @lichtblick/suite extension API to AI agents

## Tools

| Tool                 | Purpose                                                                 |
| -------------------- | ----------------------------------------------------------------------- |
| `docs_search`        | Full-text search over docs and guides, returns sections with URL anchor |
| `docs_fetch`         | Full markdown of a page, by path or URL                                 |
| `docs_list`          | All pages with path and summary, optionally filtered by section         |
| `extension_api_get`  | TypeScript declaration and doc comments of a `@lichtblick/suite` symbol |
| `extension_api_list` | All symbols exported by `@lichtblick/suite`                             |

Each page is also exposed as an MCP resource: `lichtblick-docs://<path>`.

## How it works

- **Docs**: on first use, reads `llms.txt` from the docs site (generated by `docusaurus-plugin-llms`), fetches
  each page's `.md` route (generated by `docusaurus-plugin-copy-page-button`) and builds an in-memory
  [MiniSearch](https://github.com/lucaong/minisearch) index of `##`/`###` sections. No build step or release is needed when the docs change.
- **Extension API**: parses the TypeScript sources shipped in the pinned `@lichtblick/suite` dependency, following
  the re-exports of `src/index.ts`.
- **Transport**: stdio. The client spawns the process; no port is opened. All tools are read-only.

## Quick start

Requires Node.js 22.12+.

```bash
npm install
npm run build
npm run inspect   # optional: MCP Inspector UI
```

Open this folder in VS Code; [.vscode/mcp.json](.vscode/mcp.json) registers the built server. Start it from
**MCP: List Servers** and use the tools in Copilot Chat agent mode.

## Configuration

| Variable                   | Default                                    | Description                                                                 |
| -------------------------- | ------------------------------------------ | --------------------------------------------------------------------------- |
| `LICHTBLICK_DOCS_SITE_URL` | `https://lichtblick-suite.github.io/docs/` | Public docs URL; `llms.txt` links are resolved against it                   |
| `LICHTBLICK_DOCS_SOURCE`   | value of `LICHTBLICK_DOCS_SITE_URL`        | URL or local Docusaurus `build/` directory to read `llms.txt` and pages from |

To test unpublished docs, build the docs repo and point `LICHTBLICK_DOCS_SOURCE` at its `build/` folder.

## Development

```bash
npm test          # vitest
npm run typecheck
npm run dev       # tsc --watch
```

## Known limitations

- `docusaurus-plugin-llms` writes file-based URLs into `llms.txt` and ignores `slug`/`id` front matter, so pages
  that override them (for example `initial-information`, `3d-panel`, `guides/introduction`) are listed but cannot
  be fetched and are skipped from the index.
- The extension API only covers what `@lichtblick/suite` exports; it is updated by bumping the dependency.
- Not published; distribution (`npx`), CI and versioning are out of scope for the PoC.