From feaeb30270bcd5c8cea9ff850e03ea69501a3089 Mon Sep 17 00:00:00 2001 From: Valerio Date: Wed, 22 Jul 2026 08:27:53 +0200 Subject: [PATCH] chore(mcp): align @webclaw/mcp npm README, lockstep version, add CI publish - README: rewrite to match the main webclaw README's voice/positioning (clean markdown/JSON/LLM-ready context + anti-bot angle), accurate 14-tool local/cloud split, consistent links. This is the package's npm landing page. - version @webclaw/mcp in lockstep with the core release (0.6.15) so @webclaw/mcp@X.Y.Z always installs webclaw vX.Y.Z; sync the MCP-registry server.json version to match. - release.yml: add an `npm` job (needs: release) that pins the launcher's RELEASE_TAG to the tag and publishes @webclaw/mcp on stable tags. Requires an NPM_TOKEN repo secret with publish rights on the @webclaw scope. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/release.yml | 33 +++++++++++++++++++++++++++++ packages/create-webclaw/server.json | 4 ++-- packages/webclaw-mcp/README.md | 33 +++++++++++++++++------------ packages/webclaw-mcp/package.json | 2 +- 4 files changed, 56 insertions(+), 16 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d79c80f..1b6efea 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -188,6 +188,39 @@ jobs: $prerelease \ --generate-notes + npm: + name: npm (@webclaw/mcp) + needs: release + # Publish the zero-install MCP launcher on STABLE tags only (prerelease + # tags contain a hyphen and are skipped). Requires the NPM_TOKEN repo + # secret: an npm automation token with publish rights on the @webclaw scope. + if: ${{ github.event_name == 'push' && !contains(github.ref_name, '-') }} + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-node@v4 + with: + node-version: 22 + registry-url: https://registry.npmjs.org + - name: Pin launcher to this release and publish + working-directory: packages/webclaw-mcp + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + run: | + tag="${GITHUB_REF#refs/tags/}" # e.g. v0.6.16 + ver="${tag#v}" # 0.6.16 + # Lockstep versioning: @webclaw/mcp@X.Y.Z installs the webclaw vX.Y.Z + # release. Both the pinned binary tag and the npm version derive from + # the git tag, so no commit-back is needed and the published package + # always points at matching, already-uploaded release assets. + sed -i -E "/const RELEASE_TAG =/ s|\"v[0-9.]+\"|\"${tag}\"|" webclaw-mcp.mjs + npm version "$ver" --no-git-tag-version --allow-same-version + echo "publishing @webclaw/mcp@${ver} pinned to ${tag}:" + grep -n "RELEASE_TAG =" webclaw-mcp.mjs + npm publish --access public + docker: name: Docker needs: release diff --git a/packages/create-webclaw/server.json b/packages/create-webclaw/server.json index 75d2bfe..a10cd76 100644 --- a/packages/create-webclaw/server.json +++ b/packages/create-webclaw/server.json @@ -3,12 +3,12 @@ "name": "io.github.0xMassi/webclaw", "title": "webclaw", "description": "Turn any URL into clean markdown/JSON for AI agents. Self-hostable Firecrawl alternative.", - "version": "0.1.0", + "version": "0.6.15", "packages": [ { "registryType": "npm", "identifier": "@webclaw/mcp", - "version": "0.1.0", + "version": "0.6.15", "transport": { "type": "stdio" } diff --git a/packages/webclaw-mcp/README.md b/packages/webclaw-mcp/README.md index f80d596..7a501fe 100644 --- a/packages/webclaw-mcp/README.md +++ b/packages/webclaw-mcp/README.md @@ -1,12 +1,12 @@ # @webclaw/mcp -Zero-install launcher for the [webclaw](https://webclaw.io) MCP server — web extraction and anti-bot web access for AI agents, over the Model Context Protocol. +**Clean web access for AI agents, over MCP.** Turn any URL into markdown, JSON, or LLM-ready context — including pages that block bots or need JavaScript — straight from Claude, Cursor, and any MCP client. -`npx @webclaw/mcp` downloads a prebuilt `webclaw-mcp` binary once (from the pinned GitHub release), caches it, and runs it as an MCP stdio server. No Rust build, no global install. It runs on your machine; the hosted webclaw cloud is only used for tools that need it, and only when you set `WEBCLAW_API_KEY`. +Zero-install launcher for the [webclaw](https://webclaw.io) MCP server. `npx @webclaw/mcp` downloads a prebuilt `webclaw-mcp` binary once (verified against the release `SHA256SUMS`), caches it, and runs it as an MCP stdio server. No Rust build, no global install. It runs on your machine; the hosted webclaw cloud is used only for the tools that need it, and only when you set `WEBCLAW_API_KEY`. -## Use in an MCP client +## Add to your MCP client -Point any stdio MCP client at the npx command. Claude Desktop / Cursor / Windsurf / Antigravity (`mcpServers` JSON): +Point any stdio MCP client at the npx command — Claude Desktop, Cursor, Windsurf, Antigravity (`mcpServers` JSON): ```json { @@ -19,7 +19,7 @@ Point any stdio MCP client at the npx command. Claude Desktop / Cursor / Windsur } ``` -Add a key for cloud-backed tools (anti-bot bypass, JS rendering, search, research): +Add a key to unlock the cloud-backed tools (bot-protection bypass, JS rendering, web search, research, lead enrichment): ```json { @@ -39,25 +39,32 @@ Claude Code: claude mcp add webclaw -- npx -y @webclaw/mcp ``` -## Tools +Or run `npx create-webclaw` to auto-detect your AI tools and write their configs for you. -scrape, search, crawl, map, batch, extract, summarize, diff, brand, research, lead, lead_batch, plus `list_extractors` / `vertical_scrape` for 30+ site-specific extractors. Local tools run with no API key; cloud tools require `WEBCLAW_API_KEY`. +## Tools (14) + +scrape, search, crawl, map, batch, extract, summarize, diff, brand, research, lead, lead_batch, plus `list_extractors` / `vertical_scrape` for 30+ site-specific extractors (Amazon, GitHub, Reddit, YouTube, npm, PyPI, and more). + +- **No key needed:** scrape, crawl, map, batch, diff, brand, list_extractors, vertical_scrape. +- **Needs an LLM** (local Ollama or a provider key): extract, summarize. +- **Needs `WEBCLAW_API_KEY`:** search, research, lead, lead_batch — plus automatic bot-protection bypass and JS rendering for the fetch tools. + +Get a key at [webclaw.io](https://webclaw.io). ## Environment | Variable | Purpose | |---|---| | `WEBCLAW_API_KEY` | Enables cloud-backed tools (optional). | -| `WEBCLAW_MCP_BIN` | Absolute path to a `webclaw-mcp` binary; skips download. | +| `WEBCLAW_MCP_BIN` | Absolute path to a `webclaw-mcp` binary; skips the download. | | `WEBCLAW_MCP_VERSION` | Release tag to install (default: the pinned release). | | `WEBCLAW_MCP_CACHE` | Cache directory (default: `~/.cache/webclaw`). | -The downloaded archive is verified against the release `SHA256SUMS` before use. +## Links -## Alternatives - -- `npx create-webclaw` — interactive installer that auto-detects your AI tools and writes their configs for you. -- Prebuilt binaries, Homebrew, Docker, and `cargo install` — see the [main README](https://github.com/0xMassi/webclaw). +- **Docs:** [webclaw.io/docs/mcp](https://webclaw.io/docs/mcp) +- **Source** (CLI, REST API, SDKs, extraction engine): [github.com/0xMassi/webclaw](https://github.com/0xMassi/webclaw) +- **Hosted API & keys:** [webclaw.io](https://webclaw.io) ## License diff --git a/packages/webclaw-mcp/package.json b/packages/webclaw-mcp/package.json index 6222845..d7ef337 100644 --- a/packages/webclaw-mcp/package.json +++ b/packages/webclaw-mcp/package.json @@ -1,6 +1,6 @@ { "name": "@webclaw/mcp", - "version": "0.1.0", + "version": "0.6.15", "description": "Zero-install launcher for the webclaw MCP server: web extraction and anti-bot access for AI agents. Runs `npx @webclaw/mcp`.", "type": "module", "bin": {