Skip to content

Add MCP health check and profile lookup helpers - #19

Open
anhtahaylove wants to merge 2 commits into
ProxyShard:mainfrom
huuhungn:codex-mcp-helpers
Open

anhtahaylove wants to merge 2 commits into
ProxyShard:mainfrom
huuhungn:codex-mcp-helpers

Conversation

@anhtahaylove

@anhtahaylove anhtahaylove commented Jul 9, 2026

Copy link
Copy Markdown

Summary

  • add health_check for ShardX Launcher API reachability/auth checks
  • add find_profile_by_name to locate profiles by id/name without returning full fingerprint config
  • add ensure_profile_started to idempotently resolve/start a profile and return its CDP endpoint
  • add safe_open_url to resolve/start a profile, open an http(s) URL, and return title/url for MCP smoke checks
  • let the MCP server read SHARDX_API / SHARDX_TOKEN from Windows user environment when stdio clients strip custom env vars
  • document the Codex/Cursor-friendly setup and helper flow

Why

These helpers make MCP clients safer to bootstrap and automate against ShardX Launcher:

  • clients can detect whether the launcher is reachable and whether SHARDX_TOKEN is valid before mutating calls
  • clients can resolve human-friendly profile names without inspecting full profile objects
  • agents can do a one-shot profile-start + page-open smoke test without manually chaining low-level tools
  • Windows stdio clients that whitelist inherited env vars can still use the user-level token without copying secrets into client config

This PR intentionally does not change browser engine behavior, fingerprint behavior, profile isolation, or the launcher API contract.

Test

  • node --check mcp/index.js
  • local MCP smoke test against ShardX Launcher v0.1.10:
    • health_check authenticated with token from Windows user env fallback
    • find_profile_by_name found VN Automation 001 - No Proxy
    • ensure_profile_started returned an existing CDP endpoint
    • safe_open_url opened https://example.com/ and returned Example Domain
    • safe_open_url rejected file://... with safe_open_url only supports http(s) URLs

chovizzz added a commit to chovizzz/ShardBrowser that referenced this pull request Jul 9, 2026
…roxyShard#19)

Snapshot download previously read the whole blob (up to 512 MiB) into a
Vec<u8> before returning, with no concurrency cap — a burst of lock
holders pulling at once could exhaust server memory/bandwidth.

Server (server/src/routes/locks.rs, blob.rs, state.rs, main.rs):
  - Stream the blob straight from disk via tokio_util ReaderStream +
    axum Body::from_stream instead of buffering it.
  - New download_slots semaphore (8) mirrors upload_slots: acquire a
    permit AFTER the ACL + lock-token + row-existence checks (so an
    unauthorized/non-holder request can't consume a slot), then move it
    into a GuardedReader that owns it for the whole streamed transfer —
    released when the stream drains or the client disconnects. 429 +
    Retry-After when saturated.
  - Defense-in-depth: verify the on-disk blob length matches the
    recorded snap.size before streaming, so corruption/tampering fails
    loudly rather than serving a body that contradicts Content-Length.
  - Advertise Content-Length from snap.size.

Launcher (src-tauri/src/sync.rs):
  - download() retries a 429 up to 5 attempts, honoring a clamped
    (1..=10s) Retry-After, before surfacing an error — so a transient
    download-slot saturation degrades to a short wait instead of
    aborting the launch. The LeaseGuard keeps renewing across the wait.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@anhtahaylove

Copy link
Copy Markdown
Author

Tidied my open PRs here against current main so the queue reflects reality — 7 closed, 3 left, all rebased and mergeable.

Closed as superseded (each with the specific reason on the PR):

Still open, rebased onto current main, no conflicts:

PR What it adds Size
#19 health_check (fail fast when the launcher is closed or the token is stale) and find_profile_by_name MCP tools 185+/6−
#23 devtools_context MCP tool + Tauri command returning the CDP endpoint and per-target DevTools URL, for handing a live profile to a human 219+/1−
#24 encoding="utf-8" on the Python SDK's file IO — without it a profile name with non-ASCII characters is written mojibake or throws UnicodeDecodeError on Windows 8+/8−

Verification on my side: node --check on mcp/index.js, cargo check clean for #23, and an AST sweep confirming zero remaining unencoded read_text/write_text calls for #24. I dropped some .pyc files and a generated windows-schema.json that had crept into earlier revisions.

No rush from my side — flagging only because all three are small and independent, so they can be taken in any order or declined individually. One unrelated note: sdks/python/shardx/__pycache__/*.pyc is tracked on main and .gitignore has no __pycache__ rule.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant