PicoSvc — small developer services, one account

PicoSvc combines 16 developer services in one repository, a shared Clerk identity and a Cloudflare Worker front controller. The original Remote MCP Factory (GitHub → Remote MCP) is one of those services. The Next.js frontend is built separately for Cloudflare Pages.

Implementation vs production: This repository contains implemented routes and automated tests. GitHub CI does not deploy Pages/Workers, apply production D1 migrations or prove the availability of the actual Browser, Sandbox, email, billing and DNS services. Check the live environment separately before making production-readiness claims.

Documentation / ドキュメント

• Documentation index / ドキュメント一覧 — entry point and source-of-truth map.

• クイックスタート — log in, use the dashboard, create your first resource and store credentials safely.

• 16サービス・APIガイド — management endpoint table and executable cURL examples for Mock, RSS, Cron, Monitor, Fetch, QR and Shot.

• 運用・デプロイ手順 — separate Pages, Worker and D1 rollout; Cloudflare's skipped-build message; production checks.

• Screenshot API — scoped API keys, browser settings, PNG/PDF output and smoke tests.

• Launch handoff — concrete service acceptance criteria and unresolved production verification.

• Billing model — current Free, Pico, PicoPlus and bundle model. Historical MCP-only prices do not apply to PicoSvc.

Related MCP server: remote-mcp-server-authless

Products

Live quota and price data comes from the deployed Worker GET /api/picosvc/catalog; source defaults live in src/picosvc/catalog.ts. Product-specific limits differ. The source-level standalone tiers are Free, Pico ($1/month/product) and PicoPlus ($5/month/product); bundles are documented in Billing model. Confirm the actual checkout price in the billing provider.

Project layout

src/picosvc-entry.ts      Worker entry point
src/picosvc/            Product APIs, runtime routes, quotas and security
web/                    Next.js static frontend for Cloudflare Pages
migrations/             D1 migrations
scripts/                Contract, simulated-behavior and smoke tests
docs/                   User guides, API examples and operator runbooks
wrangler.jsonc           Worker bindings, name and Cron Trigger

Two deploys, not one: frontend changes under web/ need a successful Pages deployment. Backend changes under src/ need a Worker deployment. Schema changes under migrations/ need the correct production D1 migration. A passing GitHub Actions workflow alone does none of these. See the runbook.

Local development

Worker (repository root):

npm install
npm run typecheck
npm run dev

Web (in a second terminal):

cd web
cp .env.example .env.local
npm install
npm run dev

Edit web/.env.local for your own Worker origin and Clerk publishable key. Do not enable ALLOW_DEV_AUTH in production. The web README has the exact Pages build settings. Database initialization, remote migrations, secrets and production rollout are described in the deployment runbook; do not run database initialization against existing production data.

Authentication and credentials

Most management routes under /api/picosvc/ and /api/servers require a Clerk session. Ownership uses the active Clerk Organization when available, otherwise the user. The GET /api/picosvc/catalog endpoint is public, while GET /api/picosvc/account requires a session. Public data-plane URLs (Mock, RSS, QR, etc.) have service-specific rules and quotas; a public URL does not mean unrestricted use.

PicoSvc MCP supports public endpoints and bearer-token protected endpoints. Protected tokens are shown when created/rotated and are stored as hashes. MCP deployment environment secrets are AES-GCM encrypted; management APIs list names instead of disclosing values. The Screenshot API has separate pss_... keys limited to that product; do not reuse them as management credentials.

The Worker needs provider secrets/variables appropriate to the features you enable. The Remote MCP / GitHub App configuration includes:

CLERK_SECRET_KEY
CLERK_PUBLISHABLE_KEY
DEPLOYMENT_SECRETS_KEY       # base64-encoded 32 random bytes
CLERK_JWT_KEY                # optional/recommended
CLERK_AUTHORIZED_PARTIES     # allowed application origins, if used
CLERK_SIGN_IN_URL            # optional
CLERK_PRICING_URL            # optional
GITHUB_APP_ID
GITHUB_APP_CLIENT_ID
GITHUB_APP_CLIENT_SECRET
GITHUB_APP_PRIVATE_KEY
GITHUB_APP_SLUG
GITHUB_WEBHOOK_SECRET
GITHUB_OAUTH_CALLBACK_URL    # optional; see GitHub App settings

Generate the deployment encryption key locally with openssl rand -base64 32 and store it as a Worker secret (npx wrangler secret put DEPLOYMENT_SECRETS_KEY). Do not rotate it without a key-rotation migration: existing encrypted deployment secrets depend on it. Do not commit any secret, installation token or sensitive webhook payload. ALLOW_DEV_AUTH=true is for local development only, never production. For security boundaries and operating constraints, see SECURITY.md and deployment runbook.

Remote MCP deployment workflow

1. Sign in with Clerk. Paste a public repository URL, or connect a private repository through the GitHub App at /github.

2. Select the branch, public/token visibility and any required encrypted environment secrets. For a private repository, authorize GitHub App installation access to the relevant repository.

3. The deployment pipeline clones/builds in an isolated Cloudflare Sandbox, selects an Edge-compatible Dynamic Worker or Sandbox fallback, and performs MCP initialize / tools/list health checks before considering it ready.

4. Use the issued MCP URL (typically /mcp/<deployment-id> on the configured MCP origin). Store the one-time protected bearer token securely.

5. GitHub App deployments may auto-rebuild on signed push webhooks for the configured repository and branch. Review build failures, access and quota status in management APIs rather than assuming a Git push makes every deployment ready.

GitHub App integrations include /api/github/connect/start, /api/github/callback, /api/github/installations, /api/github/deploy and the signature-verified /api/github/webhook. The installation ID alone is not authorization; the connection uses OAuth/PKCE and verifies the user's installation access. Configure the GitHub App's minimum required repository contents read permission and subscribed webhook events for your deployment workflow. Keep the GitHub App private key, OAuth client secret and webhook secret on the Worker. Repository source is untrusted code and must run inside isolated execution environments, not the management Worker.

Contributing and testing

Run the relevant repository CI checks and update the matching documentation whenever an API path, field, quota, runtime requirement, secret or migration changes. Keep examples free of real credentials. A static export or typecheck is not a live acceptance test; use the launch handoff with controlled test resources for production verification.