docs: Add MCP tools API reference documentation #79
Description
Summary
The MCP server exposes 10 tools but there is no formal API reference documenting their parameters, response formats, error codes, and usage examples. This makes it difficult for developers and AI agents to correctly use the tools.
Problem
- No centralized API reference for MCP tools
- Tool schemas are only visible in source code (
apps/mcp-server/src/tools/) - Error codes and response structures are undocumented
- No usage examples showing real request/response pairs
apps/docs/has guides but no tool-level API docs
Tools to Document
| # | Tool Name | Source File |
|---|---|---|
| 1 | lighthouse_upload_file |
tools/LighthouseUploadFileTool.ts |
| 2 | lighthouse_fetch_file |
tools/LighthouseFetchFileTool.ts |
| 3 | lighthouse_batch_upload |
tools/LighthouseBatchUploadTool.ts |
| 4 | lighthouse_batch_download |
tools/LighthouseBatchDownloadTool.ts |
| 5 | lighthouse_create_dataset |
tools/LighthouseCreateDatasetTool.ts |
| 6 | lighthouse_list_datasets |
tools/LighthouseListDatasetsTool.ts |
| 7 | lighthouse_get_dataset |
tools/LighthouseGetDatasetTool.ts |
| 8 | lighthouse_update_dataset |
tools/LighthouseUpdateDatasetTool.ts |
| 9 | lighthouse_generate_key |
tools/LighthouseGenerateKeyTool.ts |
| 10 | lighthouse_setup_access_control |
tools/LighthouseSetupAccessControlTool.ts |
Acceptance Criteria
For each tool, document:
- Description — What the tool does
- Parameters — Name, type, required/optional, description, constraints
- Response format — Success and error response structures
- Error codes — Possible errors and their meanings
- Usage examples — At least one request/response example per tool
- Authentication — How API key is passed and validated
Additionally:
- Add an overview page listing all tools with brief descriptions
- Include rate limiting and authentication details
- Place documentation in
apps/docs/alongside existing guides
Context
- Existing docs are in
apps/docs/(SDK integration guide, configuration reference, error handling docs) - Tool input schemas are defined using
zodin each tool class - The MCP server README (
apps/mcp-server/README.md) has a brief tool listing but no parameter details