scrypted-mcp-plugin CLAUDE.md

scrypted-mcp

Scrypted plugin that exposes a Streamable HTTP Model Context Protocol endpoint. AI clients (Claude Desktop, Claude Code, etc.) authenticate via OAuth backed by Scrypted user accounts and call MCP tools to inspect logs, manage plugins, and query devices on the same Scrypted server.

Commands

npm run build       # scrypted-webpack → out/main.nodejs.js (+ plugin.zip)
npm run fmt         # prettier --write
npm run fmt:check   # CI gate
npm run lint        # eslint
npm run lint:fix
npm run scrypted-deploy-debug   # build + push to a running Scrypted server (see SDK docs)

CI runs fmt:check, lint, build on every push/PR (.github/workflows/ci.yml). publish.yml runs on v* tags and pushes to npm.

Architecture

The plugin is one process inside Scrypted. src/main.ts declares ScryptedMcpPlugin extends ScryptedDeviceBase implements HttpRequestHandler and registers the full MCP tool surface on a per-session McpServer. Inbound HTTP requests are dispatched in onRequest:

1. OAuthService.handle() claims /authorize, /token, /register, and the four .well-known/* documents (oauth-protected-resource, oauth-authorization-server, openid-configuration, jwks.json). If it returns true, the response is already populated.
2. Otherwise, if the path resolves to /mcp, we verify the Bearer JWT, look up (or create) a WebStandardStreamableHTTPServerTransport keyed by the Mcp-Session-Id header, bridge the Scrypted request to a Web-standard Request, and forward.
3. Anything else returns 404.

src/http-bridge.ts is the only adapter between Scrypted's HttpRequest/HttpResponse and Web-standard Request/Response. Streamed responses (Content-Type: text/event-stream) flow through HttpResponse.sendStream(AsyncGenerator<Buffer>); everything else buffers and sends.

Two SSE behaviours are inherited from the MCP SDK transport (since 1.30.0) rather than implemented here, and both depend on the bridge staying byte- and header-transparent: