Skip to content

feat: add lk docs commands for searching and browsing LiveKit documentation#774

Merged
bcherry merged 9 commits intomainfrom
bcherry/docs-search
Mar 5, 2026
Merged

feat: add lk docs commands for searching and browsing LiveKit documentation#774
bcherry merged 9 commits intomainfrom
bcherry/docs-search

Conversation

@bcherry
Copy link
Contributor

@bcherry bcherry commented Mar 3, 2026 •
edited
Loading

Summary

Adds lk docs commands for searching and browsing LiveKit documentation directly from the terminal, powered by the LiveKit docs MCP server.

Commands

  • lk docs overview — full site table of contents
  • lk docs search <query> — search docs with pagination
  • lk docs get-page <path> — fetch one or more pages as markdown
  • lk docs code-search <query> — search code across LiveKit GitHub repos
  • lk docs changelog <identifier> — get recent releases for an SDK/package
  • lk docs list-sdks — list all LiveKit SDK repos and package names
  • lk docs submit-feedback <text> — submit docs feedback

Features

  • Uses the official MCP Go SDK (v1.4.0)
  • --json / -j flag on docs parent command to request JSON output from all tools
  • Sends lkCliVersion and projectId (when configured) as telemetry params on all tool calls
  • Server version check: warns on stderr if the docs MCP server is newer than expected (1.3.x)
  • 30-second request timeout to prevent hanging if the server is unresponsive
  • Hidden --server-url and --vercel-header flags for development/staging

Dependencies

Test plan

  • All 7 commands tested against production and staging MCP servers
  • --json flag verified against staging (docs-git-bcherry-mcp-json-option.staging.livekit.io)
  • Server version warning triggers correctly when server is newer
  • Hidden dev flags (--server-url, --vercel-header) work and don't appear in --help
  • All tool params match the server schema (audited via tools/list)
  • Unit tests for parseMajorMinor, isNotFoundErr, headerTransport
  • go build and go test pass

🤖 Generated with Claude Code

@bcherry bcherry requested review from Topherhindman and rektdeckard and removed request for Topherhindman and rektdeckard March 3, 2026 00:27
@bcherry bcherry marked this pull request as draft March 3, 2026 00:31
@bcherry
Copy link
Contributor Author

bcherry commented Mar 3, 2026

i found some more opportunity for improvement - will remark for review soon

@bcherry
Copy link
Contributor Author

bcherry commented Mar 3, 2026

Replaced the hand-rolled MCP streamable HTTP client (~230 lines of JSON-RPC/SSE transport code) with the official modelcontextprotocol/go-sdk v1.4.0. This cuts docs.go from ~670 lines to ~450 lines while gaining proper protocol handling, session management, and retry support from the upstream SDK.

Also audited all tool parameters against the MCP server's schema and added the missing --agent and --model flags to submit-feedback.

@bcherry bcherry marked this pull request as ready for review March 3, 2026 01:12
Topherhindman
Topherhindman approved these changes Mar 3, 2026
View reviewed changes
Copy link

@Topherhindman Topherhindman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall looks good. Couple minor nonblocking comment/question I have are:

Although the command handlers are just thin wrappers and there isn't much logic to unit test, I think there's some amount of unit tests that could be useful to add for these changes.

Should we consider adding an overall timeout in the event the server hangs for some reason?

@bcherry
Copy link
Contributor Author

bcherry commented Mar 3, 2026

Addressed the feedback in 6fbc135:

  1. Unit tests — Added cmd/lk/docs_test.go with tests for parseMajorMinor (10 cases including edge cases), isNotFoundErr (9 cases covering all RPC error code paths + wrapped errors), and headerTransport (verifies headers are injected correctly).

  2. Request timeout — Added a 30-second context.WithTimeout wrapping both callDocsToolAndPrint and callDocsResourceAndPrint, so the CLI won't hang indefinitely if the server is unresponsive.

  3. hits-per-page default — Removed the hardcoded Value: 10 from the --hits-per-page flag. The flag now defaults to 0 (unset) and is only sent when explicitly provided, letting the server use its own default of 20.

bcherry and others added 9 commits March 4, 2026 15:25
@bcherry
search
d1d7058
@bcherry @claude
refactor: use official MCP Go SDK, add missing submit-feedback params
0ea5f1d 
Replace hand-rolled MCP streamable HTTP client (~230 lines) with the
official modelcontextprotocol/go-sdk. Also add missing --agent and
--model flags to submit-feedback to match the server's full schema.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@bcherry @claude
feat: warn when docs MCP server is newer than expected
284b921 
Check the server's reported version after connecting. If the major or
minor version is newer than what this CLI was built against (currently
1.2.x), print a warning to stderr suggesting the user update lk.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@bcherry @claude
feat: add hidden --server-url and --vercel-header flags for docs dev
99cb411 
Add hidden flags to `lk docs` for development against staging or preview
deployments of the docs MCP server. Also add a README section documenting
the docs feature and its development options.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@bcherry @claude
feat: send lk_cli_version and project_id with docs MCP tool calls
7ee0288 
Injects lightweight telemetry params into every MCP tool call so the
docs server can track CLI version and optionally the Cloud project ID.
The project ID is resolved silently from the --project flag or default
project config and omitted when no project is configured.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@bcherry @claude
feat: add request timeout, unit tests, fix hits-per-page default
105a5f8 
- Add 30s timeout to all docs MCP requests to prevent hanging if the
  server is unresponsive.
- Remove hardcoded hits-per-page default of 10; let the server default
  to 20 instead.
- Add unit tests for parseMajorMinor, isNotFoundErr, and
  headerTransport.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@bcherry @claude
feat: add --json flag to docs commands
e7e2f38 
Adds a --json / -j flag on the docs parent command so all tool-based
subcommands can request JSON output from the MCP server. When set,
sends format: "json" in the tool call arguments.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@bcherry @claude
feat: switch list-sdks to get_sdks tool, bump expected server to 1.3
5a4633d 
Replace the livekit://sdks resource read with the new get_sdks tool
call, which supports all standard params (format, telemetry). Remove
the now-unused callDocsResourceAndPrint helper and encoding/json
import. Bump expectedServerVersion to 1.3.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@bcherry @claude
fix: use camelCase for telemetry params (lkCliVersion, projectId)
98a0746 
Match the server-side naming convention.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
rektdeckard
rektdeckard approved these changes Mar 4, 2026
View reviewed changes
Copy link
Member

@rektdeckard rektdeckard left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall looks great to me, and seems to work as expected in manual testing.

@bcherry bcherry force-pushed the bcherry/docs-search branch 2 times, most recently from c636786 to 98a0746 Compare March 4, 2026 23:57
@bcherry bcherry merged commit 42ee929 into main Mar 5, 2026
9 checks passed
@bcherry bcherry deleted the bcherry/docs-search branch March 5, 2026 00:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@rektdeckard rektdeckard rektdeckard approved these changes

@Topherhindman Topherhindman Topherhindman approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@bcherry @Topherhindman @rektdeckard