@boomstream/mcp 0.1.0 → 0.1.1

package/README.md

@@ -25,6 +25,31 @@ npm install -g @boomstream/mcp
 BOOMSTREAM_API_KEY=your-key boomstream-mcp
 ```
 
+## Available tools
+
+<!-- TOOLS:BEGIN -->
+| Section | Tools | Description | Examples |
+|---|---:|---|---|
+| media | 5 | Recorded media (VOD): info, create, upload, bulk-info | `boomstream_media_bulkinfo`, `boomstream_media_info` |
+| live | 7 | Live broadcast streams: create, manage, schedule | `boomstream_live_info`, `boomstream_live_list` |
+| ppv | 13 | Pay-per-view subscriptions: create, buyers, media access | `boomstream_ppv_create`, `boomstream_ppv_update` |
+| conference | 9 | Video conference sessions: create, manage, participants | `boomstream_conference_info`, `boomstream_conference_list` |
+| folder | 12 | Folder hierarchy for organizing media assets | `boomstream_folder_media_folder`, `boomstream_folder_media_folder_create` |
+| playlist | 7 | Playlists of media items: create, update, reorder | `boomstream_playlist_create`, `boomstream_playlist_update` |
+| stats | 3 | Viewing statistics per project, target, or session | `boomstream_stats_project`, `boomstream_stats_target` |
+| chat | 5 | Chat settings and messages for broadcasts | `boomstream_chat_init`, `boomstream_chat_info` |
+| screenshot | 4 | Thumbnail and screenshot management for media | `boomstream_screenshot_info`, `boomstream_screenshot_create` |
+| subtitles | 5 | Subtitle tracks: enable, upload, set default | `boomstream_subtitles_enable`, `boomstream_subtitles_info` |
+| timecodes | 3 | Chapter/timecode markers for video navigation | `boomstream_timecodes_info`, `boomstream_timecodes_enable` |
+| webhooks | 6 | Webhook endpoint management: list, create, update, delete | `boomstream_webhooks_list`, `boomstream_webhooks_info` |
+| project | 5 | Project-level settings, users, and configuration | `boomstream_project_create`, `boomstream_project_info` |
+| record_live | 9 | Record-live sessions: create and manage recordings | `boomstream_record_live_info`, `boomstream_record_live_list` |
+| live_ipcamera | 7 | IP camera stream integration for live broadcasts | `boomstream_live_ipcamera_info`, `boomstream_live_ipcamera_list` |
+| general | 1 | General API utilities (server info, capabilities) | `boomstream_general_info` |
+<!-- TOOLS:END -->
+
+The full schema is in `schemas/boomstream.json`. Regenerate with `pnpm build-schema`.
+
 ## Claude Desktop
 
 Add to your Claude Desktop config file:
@@ -68,6 +93,64 @@ boomstream-mcp --help, -h      Show help
 
 JSONSchema for each tool is **not hand-written**. The source of truth is the Boomstream API documentation database (`hwdmedia.documents`). The script `scripts/build-schema.mjs` parses the markdown and produces `schemas/boomstream.json` covering all ~100 methods in a single run. The generated file is committed to the repository and shipped in the npm package.
 
+## Development
+
+```bash
+pnpm install             # install dependencies
+pnpm dev:stdio           # run server locally (stdio transport)
+pnpm test                # run unit/integration tests (vitest)
+pnpm build-schema        # regenerate schemas/boomstream.json from markdown corpus
+pnpm build-readme-tools  # regenerate the Available tools table in this README
+pnpm build               # TypeScript compile → dist/
+pnpm test:smoke          # end-to-end smoke cycle (requires BOOMSTREAM_TEST_API_KEY)
+```
+
+Offline test runs use fixtures in `tests/fixtures/`. To pull a fresh schema from the database, run `pnpm build-schema:db` (requires the `mariadb-mcp` MCP server).
+
+To run the smoke cycle you need:
+- `BOOMSTREAM_TEST_API_KEY` — a sandbox project API key. Ask the project owner for a sandbox key, or check the team-shared key in the secrets store. *(Exact source pending security review.)*
+- `BOOMSTREAM_TEST_MEDIA_CODE` — a known media code in that sandbox project.
+
+## Troubleshooting
+
+**`BOOMSTREAM_API_KEY` is not set**
+
+The server exits immediately with:
+```
+Error: BOOMSTREAM_API_KEY env required for Phase A
+```
+Set it before starting:
+```bash
+BOOMSTREAM_API_KEY=your-key npx -y @boomstream/mcp stdio
+# or in Claude Desktop config under "env": { "BOOMSTREAM_API_KEY": "…" }
+```
+
+**Network timeout or 5xx from `boomstream.com/api/`**
+
+The client retries up to 3 times with exponential backoff (100 ms → 400 ms → 1 600 ms). If all attempts fail, the tool returns an error. Check your network connectivity and `boomstream.com` status.
+
+**Invalid API key (401/403)**
+
+Verify your key in Boomstream project settings → API. Keys are project-scoped; make sure the key matches the project you intend to query.
+
+**Claude Desktop doesn't list any Boomstream tools**
+
+1. Check the MCP server logs:
+   - macOS: `~/Library/Logs/Claude/mcp*.log`
+   - Windows: `%APPDATA%\Claude\logs\`
+2. Confirm `BOOMSTREAM_API_KEY` is set in the `env` block of your `claude_desktop_config.json`.
+3. Restart Claude Desktop after any config change.
+4. Run the server manually to verify it starts without errors:
+   ```bash
+   BOOMSTREAM_API_KEY=your-key npx -y @boomstream/mcp stdio
+   ```
+
+## Roadmap
+
+**Phase B — SSE transport** (`mcp.boomstream.com`): hosted remote server compatible with claude.ai and other SSE-capable MCP clients. No local install required; connect by URL. Coming soon.
+
+**Phase C — OAuth**: per-user authentication so each Boomstream account holder can connect with their own credentials instead of a shared environment API key. Coming soon.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boomstream/mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP server providing Boomstream API as tools for LLM agents",
   "type": "module",
   "license": "MIT",
@@ -46,11 +46,12 @@
     "build-schema": "node scripts/build-schema.mjs",
     "build-schema:dry": "node scripts/build-schema.mjs --dry-run",
     "build-schema:db": "node scripts/build-schema.mjs --from-db",
+    "build-readme-tools": "node scripts/build-readme-tools.mjs",
     "dev:stdio": "tsx src/transports/stdio.ts",
     "dev:sse": "tsx src/transports/sse.ts",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:smoke": "echo 'TBD: requires BOOMSTREAM_API_KEY'",
+    "test:smoke": "vitest run --dir tests/smoke",
     "lint": "eslint .",
     "typecheck": "tsc --noEmit"
   }