Prepare Screenly MCP for Claude Desktop marketplace listing [T10708]

[salmanfarisvp]

Summary

Unblocks Anthropic Claude Desktop marketplace submission by finishing the remaining MCP listing prerequisites, and fixes a stdio bug that would have failed review on first launch.

• Tool annotations on all 33 MCP tools (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so clients can distinguish read-only vs destructive actions
• MCPB Desktop Extension packaging (mcpb/manifest.json + mcpb/README.md with privacy policy, 512×512 icon) and a release workflow step that builds .mcpb for macOS and Windows (rustc-target names plus friendlier aliases like screenly-macos-arm64.mcpb), injecting the version from the git tag and pinning @anthropic-ai/mcpb@2.1.2
• Fix MCP stdout contamination by enabling simple_logger's stderr feature — log lines were previously interleaved with JSON-RPC on stdout and caused Claude Desktop to fail with Unexpected non-whitespace character after JSON at position 4
• Docs updated for Desktop Extensions install, Gatekeeper on unsigned macOS bundles, privacy (API host + Sentry), and token URL alignment

Review follow-ups

Addressed @sergey-borovkov's review on this PR:

High

• Corrected privacy policy: production API host api.screenlyapp.com, and disclosed unconditional Sentry init
• Documented Desktop Extensions as the primary install path; Gatekeeper → Privacy & Security → Open Anyway for unsigned macOS sideloads

Medium

• Annotation semantics: asset_create openWorldHint, updates marked destructive, link/share tools idempotent (13 destructive)
• Drift test: MCPB manifest tools must match server.rs
• Per-platform entry_point / command in the release pack step (incl. win32)
• 512×512 mcpb/icon.png
• Dropped unexplained compatibility.claude_desktop version floor
• Aligned token docs with *.screenlyapp.com → Settings → Security → API tokens

Minor

• Pinned @anthropic-ai/mcpb@2.1.2 (latest under @2, as noted in review)
• Friendlier release aliases: screenly-macos-arm64, screenly-macos-x64, screenly-windows-x64

Changes

Area	Files
Annotations	src/mcp/server.rs — all 33 tools
MCPB bundle	mcpb/manifest.json, mcpb/README.md, mcpb/icon.png
Release packaging	.github/workflows/release.yml
CI	.github/workflows/actions.yml — skip List screens on fork PRs
Drift guard	src/mcp/tests.rs — manifest tools match server
Stdout fix	Cargo.toml (simple_logger + stderr)
Docs	README.md, .gitignore (*.mcpb)

Test plan

• cargo check --all-targets
• cargo fmt --check
• cargo test (including MCPB manifest drift test)
• Local .mcpb pack with @anthropic-ai/mcpb — manifest schema validation passed; executable bit preserved
• Confirmed stdout is pure JSON-RPC after the stderr logging fix; logs go to stderr only
• Confirmed tools/list returns annotations for all 33 tools (12 read-only, 13 destructive)
• Installed .mcpb in Claude Desktop locally — connects successfully with API token; tools work
• Review release.yml MCP Bundle step for macOS/Windows matrix targets (aliases + pinned mcpb)
• After merge + tagged release, verify .mcpb artifacts (target names + aliases) attach to the GitHub release

[salmanfarisvp]

Tested with the local build and working fine as expected

and different commands

[vpetersson]

Love it!

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[salmanfarisvp]

@renatgalimov, could you please request a review from Copilot?

[sergey-borovkov]

Overview

This prepares the Screenly MCP server for Claude Desktop marketplace listing: MCP tool annotations on all 33 tools, an .mcpb bundle (manifest + README) built per-target in the release workflow, and a fix routing simple_logger output to stderr so stdio JSON-RPC isn't corrupted. Plus a CI guard so the integration job skips on fork PRs.

The core direction is right and the stdout fix is a genuine bug fix. Several things I verified directly:

• simple_logger 5.1.0 does expose a stderr feature; default-features stays on, so timestamps is preserved. And there are no println!/print! calls on the screenly mcp path — stdout really is clean now.
• rmcp-macros 1.4.0 supports annotations(...) with exactly this syntax.
• manifest_version: "0.3" validates against @anthropic-ai/mcpb@2 (latest 2.1.2). I unpacked the schema — 0.4 only adds the uv runtime, so 0.3 is correct for a binary server, and every field used is in the strict schema.
• pack [directory] [output] is the right signature, and files: "screenly*" in the Publish step will pick up screenly-cli-<target>.mcpb at workspace root — the open checklist item should pass.
• Counts are consistent: 33 tools, 12 read-only, 8 destructive across manifest, both READMEs, and server.rs.

High — should block marketplace submission

1. The privacy policy in mcpb/README.md is factually wrong on two counts. This is precisely what listing review scrutinizes.

• It says the extension "connects only to the Screenly API at api.screenly.io". The production host is api.screenlyapp.com (build.rs:7), with login.screenly.local / api.screenlyappstage.com for other builds, and overridable via API_BASE_URL (src/authentication.rs:45).
• It says the extension "collects no analytics, sends no telemetry, and transmits data to no third party other than Screenly itself." But src/main.rs:32-40 unconditionally initializes Sentry with a hardcoded DSN pointing at o4505481987489792.ingest.sentry.io. sentry 0.46's default features include the panic integration plus contexts/debug-images, so panics and device/OS context are uploaded to a third party on every subcommand — including mcp. Either disclose Sentry in the privacy section, or skip sentry::init when the subcommand is mcp.

2. No macOS code signing or notarization anywhere in release.yml. The .mcpb ships an unsigned, un-notarized Mach-O. A bundle downloaded from a GitHub release carries com.apple.quarantine, and Gatekeeper will refuse to exec it. The test-plan entry "Installed screenly-cli-aarch64-apple-darwin.mcpb in Claude Desktop locally" used a locally built bundle, which has no quarantine attribute — so that test cannot catch this. Before submitting, cut a pre-release tag, download the artifact through a browser, and install it. Longer term this needs codesign + notarytool steps for the darwin targets.

Medium — annotation semantics

3. open_world_hint = false on asset_create is wrong. The tool takes an arbitrary source_url that Screenly then fetches and renders. That is the textbook open-world interaction (and an SSRF-adjacent surface). Blanket-false is defensible for the other 32 tools — the Screenly API is a closed, well-defined domain — but not this one.

4. destructive_hint = false on every *_update tool. Per the MCP spec, destructiveHint: false means the tool performs only additive updates. Overwriting a title, a playlist's predicate, or a label name is not additive. asset_update is the sharpest case: it overwrites js_injection, i.e. arbitrary JavaScript that executes on the customer's screens. That should be destructive_hint = true at minimum, so clients prompt before it.

5. Link/unlink idempotency is asymmetric. label_link_screen, label_link_playlist, and shared_playlist_create are idempotent_hint = false, while their unlink/delete counterparts are true. All six are set-membership operations — re-linking an already-linked label has no additional effect. Either mark the link side idempotent too, or document why the API doesn't behave that way.

Medium — maintainability & packaging

6. The 33-tool list now exists in four places (src/mcp/server.rs, mcpb/manifest.json with tools_generated: false, README.md, mcpb/README.md), each carrying descriptions that must stay byte-identical. There's no test guarding drift, and no test covers annotations at all — src/mcp/tests.rs is 35 per-tool behavior tests, none of which touch the new metadata. A single test asserting that manifest.json's tool names and descriptions match the server's tool router would cover both gaps cheaply, and would have caught any typo in this 600-line diff.

7. entry_point: "server/screenly" is wrong for the win32 bundle — that bundle contains server/screenly.exe, and there's no platform override for entry_point (only for mcp_config.command). I checked mcpb's validator: it only verifies icon paths, not entry_point, so this packs silently, and Claude Desktop launches via mcp_config.command, which is correct. So it likely works — but the manifest is internally inconsistent. Extend the jq filter to set entry_point per platform alongside .compatibility.platforms.

8. No icon in the manifest. Not schema-required, but mcpb emits a recommendation (512×512) and a marketplace listing almost certainly wants one.

9. compatibility.claude_desktop: ">=0.10.0" is an unexplained magic floor. If it's higher than the real minimum you silently block installs. Worth a comment or a source.

10. Conflicting token instructions in the same PR. mcpb/README.md says console.screenly.io → Settings → Tokens; manifest.json says https://[your-workspace].screenlyapp.com → Settings > Security > API tokens. Given the API host is screenlyapp.com, the manifest version looks right. Pick one and use it in both.

Minor

• Scope creep in .github/workflows/actions.yml — the fork-PR guard is a correct fix and well-commented, but it isn't mentioned in the PR body's Changes table. Also confirm that if "List screens" is a required status check, a skipped job satisfies it for fork PRs.
• screenly-cli-x86_64-pc-windows-gnu.mcpb is cryptic against the instruction "download screenly-cli-<your-platform>.mcpb". Consider a friendlier alias for the bundle artifacts specifically.
• npx --yes @anthropic-ai/mcpb@2 floats across the 2.x range. Pinning an exact version is more reproducible for a release pipeline.
• The mcpb/README.md local-build snippet is correct and I traced it end to end — no issues.

Verdict

The stderr fix and the annotation pass are solid work. I'd hold merge on #1 (the privacy policy misstates both the API host and the Sentry telemetry) and #2 (unsigned macOS binary, untested through the actual download path) — both are submission blockers rather than code-quality nits. #3 and #4 are quick annotation corrections worth folding in at the same time.

[salmanfarisvp]

Thanks for the detailed review, @sergey-borovkov , really helpful. I’ve addressed the High / Medium / Minor items in the latest pushes:

High

• Privacy policy: corrected API host to api.screenlyapp.com and disclosed Sentry — 7bd86b9
• Desktop Extensions as primary install path; Gatekeeper / Open Anyway for unsigned macOS sideloads — 789f0e0

Medium

• Annotation semantics (asset_create open-world, updates destructive, link/share idempotent) — 5e6453c
• Drift test so MCPB manifest tools stay in sync with server.rs — 4334ae8
• Per-platform entry_point / command in the release pack step — 4a522e4
• Dropped the unexplained claude_desktop version floor — 0fbd086
• Token docs aligned with *.screenlyapp.com → Settings → Security → API tokens — 0ac561b
• 512×512 mcpb/icon.png — a8616e5

Minor

• Pinned @anthropic-ai/mcpb@2.1.2 and added friendlier release aliases (screenly-macos-arm64, etc.) — b73fbe9

Full Apple codesign / notarization for the binary is still an org-level follow-up (same as CLI releases today). Happy to adjust anything else you spot.

[salmanfarisvp]

@sergey-borovkov Please check. I’ve addressed the comments. Thanks

[sergey-borovkov]

Re-reviewed at f352a1e — all ten findings from the previous pass are addressed, and addressed properly.

Verified by running it:

• cargo test test_mcpb_manifest_tools_match_server passes; the other 200 tests are unaffected.
• Simulated the win32 jq transform and packed the bundle with @anthropic-ai/mcpb@2.1.2: manifest schema validation passes, icon accepted, internal zip paths correct (server/screenly.exe), output filename honored.
• mcpb/icon.png is 512x512.
• Destructive count re-counted: 8 deletes/unlinks + 5 updates = 13, matching the docs.

Two non-blocking notes for a follow-up:

1. The Gatekeeper section in mcpb/README.md says "prefer the Desktop Extensions install once it is available", which reads as though the listing path sidesteps the block. It ships the same unsigned Mach-O, so unless Claude Desktop strips the quarantine attribute on extension install, the same block applies. Worth softening the wording or confirming before the listing goes live.

2. The drift test could ask ScreenlyMcpServer::tool_router().list_all() instead of regexing server.rs. Less code, immune to attribute formatting changes, and it would cover the annotations too — which is the part that just changed and is currently untested. The assert_eq!(len, 33) does prevent silent degradation today, so this is a nice-to-have, not a defect.

Approving.