From 42f195e559cdc922620d08e6a1580d1a20bfaca4 Mon Sep 17 00:00:00 2001 From: Uzair Ahmed Date: Mon, 2 Nov 2026 15:21:11 +0500 Subject: [PATCH 1/5] feat: prepare 1.1.0 for open source Bump mcp to 1.28.1 to clear the High advisories against 1.6.0. Fix read_resource: the SDK passes an AnyUrl, not a str. --- .claude-plugin/marketplace.json | 11 ++++++ .claude-plugin/plugin.json | 2 +- .github/dependabot.yml | 31 +++++++++++++++++ .github/workflows/ci.yml | 44 +++++++++++++++++++++++ .github/workflows/release.yml | 23 +++++------- .mcp.json | 8 +++-- CONTRIBUTING.md | 31 ++++++++++++----- Dockerfile | 2 +- README.md | 62 +++++++++++++++++++++++++++++---- SECURITY.md | 5 ++- requirements.txt | 2 +- server.json | 11 ++---- server.py | 7 ++-- skills/tech-detector/SKILL.md | 38 ++++++++++---------- smithery.yaml | 23 ------------ tests/test_resource.py | 19 ++++++++++ 16 files changed, 227 insertions(+), 92 deletions(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/ci.yml delete mode 100644 smithery.yaml create mode 100644 tests/test_resource.py diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..513396e --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,11 @@ +{ + "name": "whatweb-mcp", + "description": "WhatWeb MCP server and tech-detector skill from Devkind.", + "owner": { "name": "Devkind", "url": "https://devkind.com.au" }, + "plugins": [ + { + "name": "whatweb", + "source": "./" + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 84f6dc3..074b5f1 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "whatweb", "version": "1.1.0", - "description": "Web technology fingerprinting MCP server (multi-arch Docker) plus the tech-detector agent skill — CMS, frameworks, servers, analytics and CDN detection for lead qualification.", + "description": "Web technology fingerprinting MCP server (multi-arch Docker) plus the tech-detector agent skill: CMS, frameworks, servers, analytics and CDN detection for lead qualification.", "author": { "name": "Devkind", "url": "https://devkind.com.au" }, "license": "MIT", "homepage": "https://github.com/devkindhq/whatweb-mcp", diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..50e7dae --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,31 @@ +version: 2 +updates: + - package-ecosystem: pip + directory: / + schedule: + interval: weekly + commit-message: + prefix: fix + groups: + pip-minor-patch: + update-types: [minor, patch] + + - package-ecosystem: docker + directory: / + schedule: + interval: weekly + commit-message: + prefix: fix + groups: + docker-minor-patch: + update-types: [minor, patch] + + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly + commit-message: + prefix: ci + groups: + actions-minor-patch: + update-types: [minor, patch] diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..6d8406c --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,44 @@ +name: CI + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v7 + + - name: Set up Python + uses: actions/setup-python@v7 + with: + # The image runs Alpine 3.23 python3, which is 3.12. + python-version: "3.12" + + - name: Install dependencies + run: pip install -r requirements.txt pytest + + - name: Run tests + run: python -m pytest -q + + docker: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v7 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v4 + + - name: Build image + uses: docker/build-push-action@v7 + with: + context: . + platforms: linux/amd64 + push: false diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 780bbf7..4f581c2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -13,7 +13,7 @@ jobs: version: ${{ steps.version.outputs.version }} steps: - name: Checkout code - uses: actions/checkout@v5.1.0 + uses: actions/checkout@v7 - name: Check tag matches server.json version id: version @@ -32,19 +32,19 @@ jobs: echo "version=$VERSION" >> "$GITHUB_OUTPUT" - name: Set up QEMU - uses: docker/setup-qemu-action@v3.7.0 + uses: docker/setup-qemu-action@v4 - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3.12.0 + uses: docker/setup-buildx-action@v4 - name: Log in to Docker Hub - uses: docker/login-action@v3.7.0 + uses: docker/login-action@v4 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - name: Build and push multi-arch image - uses: docker/build-push-action@v6.19.2 + uses: docker/build-push-action@v7 with: context: . platforms: linux/amd64,linux/arm64 @@ -61,18 +61,13 @@ jobs: contents: read steps: - name: Checkout code - uses: actions/checkout@v5.1.0 + uses: actions/checkout@v7 - name: Install mcp-publisher run: | curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.7/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher - # [unverified] The MCP Registry docs say GitHub-based auth allows - # io.github.orgname/* names, but the documented OIDC flow does not - # explicitly confirm it for an org namespace. If login fails, fall back to - # `mcp-publisher login github --token` with a PAT (read:org, read:user). - - name: Authenticate to MCP Registry - run: ./mcp-publisher login github-oidc - - name: Publish server to MCP Registry - run: ./mcp-publisher publish + # The registry can lag behind a new image push. + run: | + for i in 1 2 3 4 5 6 7 8 9 10; do ./mcp-publisher login github-oidc && ./mcp-publisher publish && exit 0; sleep 30; done; exit 1 diff --git a/.mcp.json b/.mcp.json index 0d7b266..85da9f0 100644 --- a/.mcp.json +++ b/.mcp.json @@ -1,6 +1,8 @@ { - "whatweb": { - "command": "docker", - "args": ["run", "-i", "--rm", "--memory=512m", "--cpus=0.5", "--pids-limit=100", "devkind/whatweb-mcp:latest"] + "mcpServers": { + "whatweb": { + "command": "docker", + "args": ["run", "-i", "--rm", "--memory=512m", "--cpus=0.5", "--pids-limit=100", "devkind/whatweb-mcp:1.1.0"] + } } } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 53d85c0..21df012 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,8 +18,9 @@ python3 -m venv .venv && .venv/bin/pip install -r requirements.txt pytest ``` The test suite covers target validation, WhatWeb JSON parsing, the in-memory -result store, and a live MCP stdio JSON-RPC handshake. All tests must pass -before a PR is merged. +result store, and a live MCP stdio JSON-RPC handshake. The tests do not need +the WhatWeb binary. CI runs them on Python 3.12 and builds the Docker image +for `linux/amd64`. Both jobs must pass before a PR is merged. ## Ground rules @@ -31,17 +32,29 @@ before a PR is merged. ## Pull requests -1. Fork, branch, commit with a clear message. -2. Ensure `pytest` passes. +1. Fork, branch, and commit with a + [Conventional Commits](https://www.conventionalcommits.org/) message, for + example `fix: reject empty targets`. +2. Make sure `pytest` passes. 3. Open the PR describing what changed and why. ## Releasing -Pushing a tag `vX.Y.Z` (matching `version` in `server.json` and the image tag in -`packages[0].identifier`) runs `.github/workflows/release.yml`. It builds and -pushes the multi-arch image to Docker Hub (`X.Y.Z` and `latest`), then -publishes `server.json` to the Official MCP Registry. Maintainers need the -`DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` repository secrets. +1. In one PR, set the new version `X.Y.Z` in all of these places: + - `server.json`: `version` and the image tag in `packages[0].identifier` + (`docker.io/devkind/whatweb-mcp:X.Y.Z`). + - `.claude-plugin/plugin.json`: `version`. + - `.mcp.json`: the image `devkind/whatweb-mcp:X.Y.Z`. +2. Merge the PR to `main`. +3. Push the tag `vX.Y.Z` from `main`. + +The tag runs `.github/workflows/release.yml`. The workflow stops if the tag +does not match the `server.json` version and image tag. It then builds and +pushes the multi-arch image to Docker Hub (`X.Y.Z` and `latest`), and +publishes `server.json` to the Official MCP Registry with GitHub OIDC. + +The workflow needs the `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` repository +secrets. ## License diff --git a/Dockerfile b/Dockerfile index 937962b..a446789 100644 --- a/Dockerfile +++ b/Dockerfile @@ -10,7 +10,7 @@ LABEL org.opencontainers.image.title="whatweb-mcp" LABEL org.opencontainers.image.description="MCP server for WhatWeb: web technology fingerprinting for AI agents" LABEL org.opencontainers.image.source="https://github.com/devkindhq/whatweb-mcp" LABEL io.modelcontextprotocol.server.name="io.github.devkindhq/whatweb-mcp" -LABEL org.opencontainers.image.licenses="MIT" +LABEL org.opencontainers.image.licenses="MIT AND GPL-2.0-or-later" RUN addgroup -g 1000 mcpuser && \ adduser -D -u 1000 -G mcpuser mcpuser diff --git a/README.md b/README.md index b41a767..a6abbe9 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,14 @@ # WhatWeb MCP Server: web technology fingerprinting for AI agents +[![Docker Hub](https://img.shields.io/docker/v/devkind/whatweb-mcp?sort=semver&label=docker%20hub)](https://hub.docker.com/r/devkind/whatweb-mcp) +[![CI](https://github.com/devkindhq/whatweb-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/devkindhq/whatweb-mcp/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) + WhatWeb MCP server lets Claude Code, Cursor, and any MCP client fingerprint websites and identify their CMS, web server, frameworks, and analytics tools. It runs WhatWeb in a hardened Docker container and returns a structured report in one tool call. Sales and prospecting teams use it to qualify leads; security teams use it for recon. -The server publishes three tools: `whatweb_scan` (scan a target at five aggression levels), `get_scan_results` (fetch a previous scan by ID), and `list_active_scans` (see what is running). Scans run in a sandboxed container with a non-root user, memory and CPU limits, and flag-injection validation on every target. +The server has three [tools](#tools) for scanning a site and reading results. Scans run in a sandboxed container with a non-root user, memory and CPU limits, and flag-injection validation on every target. ## Quickstart (Docker) @@ -130,12 +134,22 @@ Go to `Settings` -> `AI` -> `Manage MCP Servers` -> `+ Add` to [add an MCP Serve -## Example tool call and output +## Tools + +| Tool | What it does | +| --- | --- | +| `whatweb_scan` | Scan a URL or domain. Arguments: `target` (required), `aggression` (default `normal`), `timeout` in seconds. | +| `get_scan_results` | Return a previous scan by `scan_id`. | +| `list_active_scans` | List the scans that are running now. | + +## Example ```json { "tool": "whatweb_scan", "arguments": { "target": "https://example.com", "aggression": "normal" } } ``` +Illustrative output: + ```json { "scan_id": "a1b2c3d4", @@ -154,29 +168,63 @@ Go to `Settings` -> `AI` -> `Manage MCP Servers` -> `+ Add` to [add an MCP Serve Aggression levels map to WhatWeb's `-a` flag: `stealthy`/`passive` (1, one request), `polite` (2), `normal` (3), `aggressive` (4, potentially intrusive, so use only on targets you are authorized to test). +## Configuration + +Pass these environment variables with `docker run -e NAME=value`. All are optional. + +| Variable | Default | Purpose | +| --- | --- | --- | +| `WHATWEB_TIMEOUT` | `300` | Per-scan timeout in seconds, when the tool call does not set `timeout`. | +| `WHATWEB_MAX_CONCURRENT` | `2` | Maximum number of scans that run at the same time. | +| `WHATWEB_OUTPUT_DIR` | `/app/output` | Directory for WhatWeb JSON logs inside the container. | + ## How it works -The container installs WhatWeb from the official upstream repository on an Alpine Ruby base, then runs a Python MCP server (`mcp` SDK, stdio transport). Each scan shells out with an argument array (no shell interpolation), writes WhatWeb's JSON log to an ephemeral `/app/output`, and parses it into typed results. Up to 100 scan results are kept in memory for follow-up questions in the same session. Tests cover target validation, JSON parsing, result-store bounds, and a live MCP stdio JSON-RPC handshake. Run them with `pytest`. Also installable from source without Docker: `pip install -r requirements.txt && python3 server.py` (requires WhatWeb on your PATH). +The container installs WhatWeb from the official upstream repository on an Alpine Ruby base, then runs a Python MCP server (`mcp` SDK, stdio transport). Each scan shells out with an argument array (no shell interpolation), writes WhatWeb's JSON log to an ephemeral `/app/output`, and parses it into typed results. Up to 100 scan results are kept in memory for follow-up questions in the same session. Also installable from source without Docker: `pip install -r requirements.txt && python3 server.py` (requires WhatWeb on your PATH). + +## Claude Code plugin -## Claude Code skill +The repo root is a Claude Code plugin. It adds two things: -This repo ships a ready-made agent skill at [`skills/tech-detector/SKILL.md`](skills/tech-detector/SKILL.md). It teaches Claude Code (or any skill-aware agent) when to scan a site, how to call `whatweb_scan`, and how to turn the raw technology list into a structured stack summary, business interpretation, and analysis angles — useful for lead qualification and competitor research. To install, copy the `skills/tech-detector/` directory into your project's `.claude/skills/` (or `~/.claude/skills/`) directory. +- The WhatWeb MCP server, pinned to a release image with the resource limits above ([`.mcp.json`](.mcp.json)). +- The [`tech-detector`](skills/tech-detector/SKILL.md) skill. The skill tells Claude when to scan a site, how to call `whatweb_scan`, and how to turn the result into a stack summary for lead qualification or competitor research. + +The repo is also its own plugin marketplace. In Claude Code 2.1.275 or later, install the plugin with: + +```text +/plugin install whatweb --marketplace devkindhq/whatweb-mcp +``` + +The plugin will also be in the Claude plugin directory once it is listed. ## Roadmap - [x] Official MCP Registry listing (`io.github.devkindhq/whatweb-mcp`) -- [ ] Docker MCP Registry and Smithery listings +- [ ] Docker MCP Registry listing - [ ] Batch scanning (multiple targets in one call) - [ ] Optional CSV/JSON export tool - [ ] Scheduled re-scans with diffing (alert when a target's stack changes) +## Development + +```bash +python3 -m venv .venv && .venv/bin/pip install -r requirements.txt pytest +.venv/bin/python -m pytest +``` + +The tests do not need the WhatWeb binary. See [CONTRIBUTING.md](CONTRIBUTING.md) for checks, commit style and the release flow. + ## Built by Built by [Devkind](https://devkind.com.au). Maintained by Kazim Ali. ## License -[MIT](LICENSE). See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md). WhatWeb itself is licensed by its upstream authors. Scan only targets you are authorized to scan. +The code in this repo is [MIT](LICENSE). See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md). + +The Docker image also installs [WhatWeb](https://github.com/urbanadventurer/WhatWeb) v0.6.4 from upstream, unmodified. WhatWeb is licensed under the [GNU GPL v2](https://github.com/urbanadventurer/WhatWeb/blob/v0.6.4/LICENSE) or later. + +Scan only targets you are authorized to scan. ## Qualifying leads by their tech stack? diff --git a/SECURITY.md b/SECURITY.md index 483e730..f566fb3 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,12 +2,11 @@ ## Supported versions -The `latest` tag on Docker Hub and the tip of `main` are supported. +Only the latest release is supported. ## Reporting a vulnerability -Email the maintainers via the Devkind GitHub organisation -(open a private security advisory on the repo if enabled, or contact an admin). +Email security@devkind.com.au. Please do not open public issues for suspected vulnerabilities. We aim to respond within 5 business days. diff --git a/requirements.txt b/requirements.txt index 16b15e9..fe77cea 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,3 @@ -mcp==1.6.0 +mcp==1.28.1 pydantic==2.11.5 pydantic-settings==2.9.1 diff --git a/server.json b/server.json index 2a3ff86..4abcc0a 100644 --- a/server.json +++ b/server.json @@ -8,11 +8,11 @@ "url": "https://github.com/devkindhq/whatweb-mcp", "source": "github" }, - "version": "1.0.1", + "version": "1.1.0", "packages": [ { "registryType": "oci", - "identifier": "docker.io/devkind/whatweb-mcp:1.0.1", + "identifier": "docker.io/devkind/whatweb-mcp:1.1.0", "transport": { "type": "stdio" }, @@ -35,12 +35,7 @@ "_meta": { "io.modelcontextprotocol.registry/publisher-provided": { "author": "Devkind", - "website": "https://devkind.com.au", - "tools": [ - "whatweb_scan", - "get_scan_results", - "list_active_scans" - ] + "website": "https://devkind.com.au" } } } diff --git a/server.py b/server.py index 1ac4d01..660d13a 100644 --- a/server.py +++ b/server.py @@ -27,7 +27,7 @@ TextContent, Tool, ) -from pydantic import BaseModel, Field +from pydantic import AnyUrl, BaseModel, Field from pydantic_settings import BaseSettings logging.basicConfig( @@ -176,7 +176,7 @@ async def run_whatweb_scan( aggression_level = AGGRESSION_LEVELS.get(aggression, 3) - # Uses create_subprocess_exec (args array, no shell) — safe against injection + # Uses create_subprocess_exec (args array, no shell), safe against injection cmd = [ "whatweb", "-a", str(aggression_level), @@ -348,7 +348,8 @@ async def list_resources() -> list[Resource]: @app.read_resource() -async def read_resource(uri: str) -> str: +async def read_resource(uri: AnyUrl) -> str: + uri = str(uri) if uri.startswith("whatweb://results/"): scan_id = uri.replace("whatweb://results/", "") result = scan_results.get(scan_id) diff --git a/skills/tech-detector/SKILL.md b/skills/tech-detector/SKILL.md index 6984b3f..022fa75 100644 --- a/skills/tech-detector/SKILL.md +++ b/skills/tech-detector/SKILL.md @@ -4,7 +4,7 @@ description: Detect the technology stack of any website for lead qualification a tools: [whatweb_scan] --- -# Tech Detector — Stack Analysis +# Tech Detector: Stack Analysis ## When to use this skill @@ -20,7 +20,7 @@ Trigger when: Call the `whatweb_scan` tool (exposed by this repo's WhatWeb MCP server) with: - `target`: the URL provided -- `aggression`: `normal` (default — non-intrusive, safe for live sites) +- `aggression`: `normal` (default, non-intrusive, safe for live sites) If the scan is long-running, follow up with `get_scan_results` (fetch by `scan_id`) or `list_active_scans` (see what is running). @@ -30,10 +30,10 @@ Always present findings in three sections: ### 1. Stack Summary Plain-English summary of what they're running. Group by: -- **Platform/CMS** — Shopify, WordPress, Webflow, custom, etc. -- **Frontend** — React, Vue, jQuery, Bootstrap, etc. -- **Infrastructure** — Cloudflare, AWS, Vercel, Fastly, etc. -- **Analytics/Marketing** — GTM, GA4, HubSpot, Intercom, etc. +- **Platform/CMS**: Shopify, WordPress, Webflow, custom, etc. +- **Frontend**: React, Vue, jQuery, Bootstrap, etc. +- **Infrastructure**: Cloudflare, AWS, Vercel, Fastly, etc. +- **Analytics/Marketing**: GTM, GA4, HubSpot, Intercom, etc. ### 2. What This Tells Us Interpret the stack in business terms: @@ -47,24 +47,24 @@ Map detected tech to specific opportunities: | Detected | Observation | |----------|-------------| -| Shopify (Bootstrap/jQuery theme) | Likely older theme — performance and modernisation opportunity | -| Shopify (no GTM/analytics) | Analytics gap — no conversion tracking in place | +| Shopify (Bootstrap/jQuery theme) | Likely older theme: performance and modernisation opportunity | +| Shopify (no GTM/analytics) | Analytics gap: no conversion tracking in place | | WordPress | Common maintenance pain points: performance, security, plugin sprawl | -| Webflow | Hosted CMS constraints — custom dev or migration may be needed at scale | -| No identifiable platform | Likely custom build — dev team dependency, higher maintenance cost | -| jQuery / Bootstrap (no modern framework) | Legacy frontend — migration to React/Vue may be warranted | +| Webflow | Hosted CMS constraints: custom dev or migration may be needed at scale | +| No identifiable platform | Likely custom build: dev team dependency, higher maintenance cost | +| jQuery / Bootstrap (no modern framework) | Legacy frontend: migration to React/Vue may be warranted | | No HTTPS / missing HSTS | Basic security gap, quick to address | | Google Tag Manager | Active marketing instrumentation in place | -| Cloudflare | Performance and security aware — sophisticated infra | +| Cloudflare | Performance and security aware, sophisticated infra | | Vercel / Next.js | Modern stack, likely needs backend/API or design system work | -| No CDN detected | Performance risk — static assets served from origin | +| No CDN detected | Performance risk: static assets served from origin | ## Output format Keep it tight and actionable. Example: --- -**[Company] — Tech Stack** +**[Company]: Tech Stack** **Platform:** Shopify **Frontend:** Bootstrap, jQuery (legacy theme) @@ -75,13 +75,13 @@ Keep it tight and actionable. Example: They're on a standard Shopify setup with an older theme stack (Bootstrap/jQuery). GTM presence means there's an active marketing team. Cloudflare suggests someone technical is involved, even if their dev team is small. **Analysis angles:** -- Custom Shopify theme (modern, performance-focused) — Bootstrap/jQuery theme is likely slow +- Custom Shopify theme (modern, performance-focused). Bootstrap/jQuery theme is likely slow - Headless Shopify if they're hitting platform limits -- Analytics depth — GTM is present, tracking baseline is in place +- Analytics depth: GTM is present, tracking baseline is in place --- ## Parallelisation -Safe — this skill is stateless and read-only (HTTP scan only). Multiple tech-detector agents can run simultaneously against different URLs with no conflicts or side effects. +Safe: this skill is stateless and read-only (HTTP scan only). Multiple tech-detector agents can run simultaneously against different URLs with no conflicts or side effects. ## Machine-readable Return Contract When invoked by an orchestrator agent collecting results for multiple targets, return a JSON envelope alongside the markdown report: @@ -98,6 +98,6 @@ The orchestrator uses this to aggregate and sort results without parsing the mar ## Notes - If http_status is not 200, flag it ("site may be down or blocking scanners") -- If very few technologies detected (<5), note that the site may be behind a heavy proxy or WAF masking the stack — suggest running with `aggression: aggressive` for a deeper look -- Never present raw scan JSON to the user — always translate to the format above +- If very few technologies detected (<5), note that the site may be behind a heavy proxy or WAF masking the stack. Suggest running with `aggression: aggressive` for a deeper look +- Never present raw scan JSON to the user. Always translate to the format above - If no URL is provided, ask for one before running diff --git a/smithery.yaml b/smithery.yaml deleted file mode 100644 index c71cfdd..0000000 --- a/smithery.yaml +++ /dev/null @@ -1,23 +0,0 @@ -name: whatweb-mcp -description: Website technology fingerprinting for AI agents, powered by WhatWeb. Multi-arch Docker. -vendor: Devkind -homepage: https://devkind.com.au/services -license: MIT -startCommand: - type: stdio - configSchema: - type: object - properties: - timeout: - type: number - description: Per-scan timeout in seconds - default: 300 - maxConcurrent: - type: number - description: Maximum concurrent scans - default: 2 - commandFunction: |- - (config) => ({ - command: "docker", - args: ["run", "-i", "--rm", "--memory=512m", "--cpus=0.5", "--pids-limit=100", "-e", `WHATWEB_TIMEOUT=${config.timeout ?? 300}`, "-e", `WHATWEB_MAX_CONCURRENT=${config.maxConcurrent ?? 2}`, "devkind/whatweb-mcp:latest"] - }) diff --git a/tests/test_resource.py b/tests/test_resource.py new file mode 100644 index 0000000..3dd45ea --- /dev/null +++ b/tests/test_resource.py @@ -0,0 +1,19 @@ +"""Tests for resources/read through the registered MCP handler.""" + +import asyncio +import json + +from mcp import types + +import server + + +def test_read_unknown_result_returns_not_found(): + handler = server.app.request_handlers[types.ReadResourceRequest] + req = types.ReadResourceRequest( + method="resources/read", + params=types.ReadResourceRequestParams(uri="whatweb://results/missing"), + ) + result = asyncio.run(handler(req)) + text = result.root.contents[0].text + assert json.loads(text) == {"error": "Resource not found"} From de47a4e612b3099fe7ec4e18ac83fe51bb86ec04 Mon Sep 17 00:00:00 2001 From: Uzair Ahmed Date: Mon, 2 Nov 2026 15:59:23 +0500 Subject: [PATCH 2/5] chore: keep only the security and bug fixes Revert the optional changes. Keep mcp 1.28.1 (High advisories), the read_resource fix and its test. --- .claude-plugin/marketplace.json | 11 ------ .claude-plugin/plugin.json | 2 +- .github/dependabot.yml | 31 ----------------- .github/workflows/ci.yml | 44 ----------------------- .github/workflows/release.yml | 23 +++++++----- .mcp.json | 8 ++--- CONTRIBUTING.md | 31 +++++------------ Dockerfile | 2 +- README.md | 62 ++++----------------------------- SECURITY.md | 5 +-- requirements.txt | 2 +- server.json | 11 ++++-- server.py | 7 ++-- skills/tech-detector/SKILL.md | 38 ++++++++++---------- smithery.yaml | 23 ++++++++++++ 15 files changed, 92 insertions(+), 208 deletions(-) delete mode 100644 .claude-plugin/marketplace.json delete mode 100644 .github/dependabot.yml delete mode 100644 .github/workflows/ci.yml create mode 100644 smithery.yaml diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json deleted file mode 100644 index 513396e..0000000 --- a/.claude-plugin/marketplace.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "name": "whatweb-mcp", - "description": "WhatWeb MCP server and tech-detector skill from Devkind.", - "owner": { "name": "Devkind", "url": "https://devkind.com.au" }, - "plugins": [ - { - "name": "whatweb", - "source": "./" - } - ] -} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 074b5f1..84f6dc3 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "whatweb", "version": "1.1.0", - "description": "Web technology fingerprinting MCP server (multi-arch Docker) plus the tech-detector agent skill: CMS, frameworks, servers, analytics and CDN detection for lead qualification.", + "description": "Web technology fingerprinting MCP server (multi-arch Docker) plus the tech-detector agent skill — CMS, frameworks, servers, analytics and CDN detection for lead qualification.", "author": { "name": "Devkind", "url": "https://devkind.com.au" }, "license": "MIT", "homepage": "https://github.com/devkindhq/whatweb-mcp", diff --git a/.github/dependabot.yml b/.github/dependabot.yml deleted file mode 100644 index 50e7dae..0000000 --- a/.github/dependabot.yml +++ /dev/null @@ -1,31 +0,0 @@ -version: 2 -updates: - - package-ecosystem: pip - directory: / - schedule: - interval: weekly - commit-message: - prefix: fix - groups: - pip-minor-patch: - update-types: [minor, patch] - - - package-ecosystem: docker - directory: / - schedule: - interval: weekly - commit-message: - prefix: fix - groups: - docker-minor-patch: - update-types: [minor, patch] - - - package-ecosystem: github-actions - directory: / - schedule: - interval: weekly - commit-message: - prefix: ci - groups: - actions-minor-patch: - update-types: [minor, patch] diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml deleted file mode 100644 index 6d8406c..0000000 --- a/.github/workflows/ci.yml +++ /dev/null @@ -1,44 +0,0 @@ -name: CI - -on: - pull_request: - push: - branches: [main] - -permissions: - contents: read - -jobs: - test: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v7 - - - name: Set up Python - uses: actions/setup-python@v7 - with: - # The image runs Alpine 3.23 python3, which is 3.12. - python-version: "3.12" - - - name: Install dependencies - run: pip install -r requirements.txt pytest - - - name: Run tests - run: python -m pytest -q - - docker: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v7 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v4 - - - name: Build image - uses: docker/build-push-action@v7 - with: - context: . - platforms: linux/amd64 - push: false diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4f581c2..780bbf7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -13,7 +13,7 @@ jobs: version: ${{ steps.version.outputs.version }} steps: - name: Checkout code - uses: actions/checkout@v7 + uses: actions/checkout@v5.1.0 - name: Check tag matches server.json version id: version @@ -32,19 +32,19 @@ jobs: echo "version=$VERSION" >> "$GITHUB_OUTPUT" - name: Set up QEMU - uses: docker/setup-qemu-action@v4 + uses: docker/setup-qemu-action@v3.7.0 - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v4 + uses: docker/setup-buildx-action@v3.12.0 - name: Log in to Docker Hub - uses: docker/login-action@v4 + uses: docker/login-action@v3.7.0 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - name: Build and push multi-arch image - uses: docker/build-push-action@v7 + uses: docker/build-push-action@v6.19.2 with: context: . platforms: linux/amd64,linux/arm64 @@ -61,13 +61,18 @@ jobs: contents: read steps: - name: Checkout code - uses: actions/checkout@v7 + uses: actions/checkout@v5.1.0 - name: Install mcp-publisher run: | curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.7/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher + # [unverified] The MCP Registry docs say GitHub-based auth allows + # io.github.orgname/* names, but the documented OIDC flow does not + # explicitly confirm it for an org namespace. If login fails, fall back to + # `mcp-publisher login github --token` with a PAT (read:org, read:user). + - name: Authenticate to MCP Registry + run: ./mcp-publisher login github-oidc + - name: Publish server to MCP Registry - # The registry can lag behind a new image push. - run: | - for i in 1 2 3 4 5 6 7 8 9 10; do ./mcp-publisher login github-oidc && ./mcp-publisher publish && exit 0; sleep 30; done; exit 1 + run: ./mcp-publisher publish diff --git a/.mcp.json b/.mcp.json index 85da9f0..0d7b266 100644 --- a/.mcp.json +++ b/.mcp.json @@ -1,8 +1,6 @@ { - "mcpServers": { - "whatweb": { - "command": "docker", - "args": ["run", "-i", "--rm", "--memory=512m", "--cpus=0.5", "--pids-limit=100", "devkind/whatweb-mcp:1.1.0"] - } + "whatweb": { + "command": "docker", + "args": ["run", "-i", "--rm", "--memory=512m", "--cpus=0.5", "--pids-limit=100", "devkind/whatweb-mcp:latest"] } } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 21df012..53d85c0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,9 +18,8 @@ python3 -m venv .venv && .venv/bin/pip install -r requirements.txt pytest ``` The test suite covers target validation, WhatWeb JSON parsing, the in-memory -result store, and a live MCP stdio JSON-RPC handshake. The tests do not need -the WhatWeb binary. CI runs them on Python 3.12 and builds the Docker image -for `linux/amd64`. Both jobs must pass before a PR is merged. +result store, and a live MCP stdio JSON-RPC handshake. All tests must pass +before a PR is merged. ## Ground rules @@ -32,29 +31,17 @@ for `linux/amd64`. Both jobs must pass before a PR is merged. ## Pull requests -1. Fork, branch, and commit with a - [Conventional Commits](https://www.conventionalcommits.org/) message, for - example `fix: reject empty targets`. -2. Make sure `pytest` passes. +1. Fork, branch, commit with a clear message. +2. Ensure `pytest` passes. 3. Open the PR describing what changed and why. ## Releasing -1. In one PR, set the new version `X.Y.Z` in all of these places: - - `server.json`: `version` and the image tag in `packages[0].identifier` - (`docker.io/devkind/whatweb-mcp:X.Y.Z`). - - `.claude-plugin/plugin.json`: `version`. - - `.mcp.json`: the image `devkind/whatweb-mcp:X.Y.Z`. -2. Merge the PR to `main`. -3. Push the tag `vX.Y.Z` from `main`. - -The tag runs `.github/workflows/release.yml`. The workflow stops if the tag -does not match the `server.json` version and image tag. It then builds and -pushes the multi-arch image to Docker Hub (`X.Y.Z` and `latest`), and -publishes `server.json` to the Official MCP Registry with GitHub OIDC. - -The workflow needs the `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` repository -secrets. +Pushing a tag `vX.Y.Z` (matching `version` in `server.json` and the image tag in +`packages[0].identifier`) runs `.github/workflows/release.yml`. It builds and +pushes the multi-arch image to Docker Hub (`X.Y.Z` and `latest`), then +publishes `server.json` to the Official MCP Registry. Maintainers need the +`DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` repository secrets. ## License diff --git a/Dockerfile b/Dockerfile index a446789..937962b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -10,7 +10,7 @@ LABEL org.opencontainers.image.title="whatweb-mcp" LABEL org.opencontainers.image.description="MCP server for WhatWeb: web technology fingerprinting for AI agents" LABEL org.opencontainers.image.source="https://github.com/devkindhq/whatweb-mcp" LABEL io.modelcontextprotocol.server.name="io.github.devkindhq/whatweb-mcp" -LABEL org.opencontainers.image.licenses="MIT AND GPL-2.0-or-later" +LABEL org.opencontainers.image.licenses="MIT" RUN addgroup -g 1000 mcpuser && \ adduser -D -u 1000 -G mcpuser mcpuser diff --git a/README.md b/README.md index a6abbe9..b41a767 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,10 @@ # WhatWeb MCP Server: web technology fingerprinting for AI agents -[![Docker Hub](https://img.shields.io/docker/v/devkind/whatweb-mcp?sort=semver&label=docker%20hub)](https://hub.docker.com/r/devkind/whatweb-mcp) -[![CI](https://github.com/devkindhq/whatweb-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/devkindhq/whatweb-mcp/actions/workflows/ci.yml) -[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) - WhatWeb MCP server lets Claude Code, Cursor, and any MCP client fingerprint websites and identify their CMS, web server, frameworks, and analytics tools. It runs WhatWeb in a hardened Docker container and returns a structured report in one tool call. Sales and prospecting teams use it to qualify leads; security teams use it for recon. -The server has three [tools](#tools) for scanning a site and reading results. Scans run in a sandboxed container with a non-root user, memory and CPU limits, and flag-injection validation on every target. +The server publishes three tools: `whatweb_scan` (scan a target at five aggression levels), `get_scan_results` (fetch a previous scan by ID), and `list_active_scans` (see what is running). Scans run in a sandboxed container with a non-root user, memory and CPU limits, and flag-injection validation on every target. ## Quickstart (Docker) @@ -134,22 +130,12 @@ Go to `Settings` -> `AI` -> `Manage MCP Servers` -> `+ Add` to [add an MCP Serve -## Tools - -| Tool | What it does | -| --- | --- | -| `whatweb_scan` | Scan a URL or domain. Arguments: `target` (required), `aggression` (default `normal`), `timeout` in seconds. | -| `get_scan_results` | Return a previous scan by `scan_id`. | -| `list_active_scans` | List the scans that are running now. | - -## Example +## Example tool call and output ```json { "tool": "whatweb_scan", "arguments": { "target": "https://example.com", "aggression": "normal" } } ``` -Illustrative output: - ```json { "scan_id": "a1b2c3d4", @@ -168,63 +154,29 @@ Illustrative output: Aggression levels map to WhatWeb's `-a` flag: `stealthy`/`passive` (1, one request), `polite` (2), `normal` (3), `aggressive` (4, potentially intrusive, so use only on targets you are authorized to test). -## Configuration - -Pass these environment variables with `docker run -e NAME=value`. All are optional. - -| Variable | Default | Purpose | -| --- | --- | --- | -| `WHATWEB_TIMEOUT` | `300` | Per-scan timeout in seconds, when the tool call does not set `timeout`. | -| `WHATWEB_MAX_CONCURRENT` | `2` | Maximum number of scans that run at the same time. | -| `WHATWEB_OUTPUT_DIR` | `/app/output` | Directory for WhatWeb JSON logs inside the container. | - ## How it works -The container installs WhatWeb from the official upstream repository on an Alpine Ruby base, then runs a Python MCP server (`mcp` SDK, stdio transport). Each scan shells out with an argument array (no shell interpolation), writes WhatWeb's JSON log to an ephemeral `/app/output`, and parses it into typed results. Up to 100 scan results are kept in memory for follow-up questions in the same session. Also installable from source without Docker: `pip install -r requirements.txt && python3 server.py` (requires WhatWeb on your PATH). - -## Claude Code plugin +The container installs WhatWeb from the official upstream repository on an Alpine Ruby base, then runs a Python MCP server (`mcp` SDK, stdio transport). Each scan shells out with an argument array (no shell interpolation), writes WhatWeb's JSON log to an ephemeral `/app/output`, and parses it into typed results. Up to 100 scan results are kept in memory for follow-up questions in the same session. Tests cover target validation, JSON parsing, result-store bounds, and a live MCP stdio JSON-RPC handshake. Run them with `pytest`. Also installable from source without Docker: `pip install -r requirements.txt && python3 server.py` (requires WhatWeb on your PATH). -The repo root is a Claude Code plugin. It adds two things: +## Claude Code skill -- The WhatWeb MCP server, pinned to a release image with the resource limits above ([`.mcp.json`](.mcp.json)). -- The [`tech-detector`](skills/tech-detector/SKILL.md) skill. The skill tells Claude when to scan a site, how to call `whatweb_scan`, and how to turn the result into a stack summary for lead qualification or competitor research. - -The repo is also its own plugin marketplace. In Claude Code 2.1.275 or later, install the plugin with: - -```text -/plugin install whatweb --marketplace devkindhq/whatweb-mcp -``` - -The plugin will also be in the Claude plugin directory once it is listed. +This repo ships a ready-made agent skill at [`skills/tech-detector/SKILL.md`](skills/tech-detector/SKILL.md). It teaches Claude Code (or any skill-aware agent) when to scan a site, how to call `whatweb_scan`, and how to turn the raw technology list into a structured stack summary, business interpretation, and analysis angles — useful for lead qualification and competitor research. To install, copy the `skills/tech-detector/` directory into your project's `.claude/skills/` (or `~/.claude/skills/`) directory. ## Roadmap - [x] Official MCP Registry listing (`io.github.devkindhq/whatweb-mcp`) -- [ ] Docker MCP Registry listing +- [ ] Docker MCP Registry and Smithery listings - [ ] Batch scanning (multiple targets in one call) - [ ] Optional CSV/JSON export tool - [ ] Scheduled re-scans with diffing (alert when a target's stack changes) -## Development - -```bash -python3 -m venv .venv && .venv/bin/pip install -r requirements.txt pytest -.venv/bin/python -m pytest -``` - -The tests do not need the WhatWeb binary. See [CONTRIBUTING.md](CONTRIBUTING.md) for checks, commit style and the release flow. - ## Built by Built by [Devkind](https://devkind.com.au). Maintained by Kazim Ali. ## License -The code in this repo is [MIT](LICENSE). See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md). - -The Docker image also installs [WhatWeb](https://github.com/urbanadventurer/WhatWeb) v0.6.4 from upstream, unmodified. WhatWeb is licensed under the [GNU GPL v2](https://github.com/urbanadventurer/WhatWeb/blob/v0.6.4/LICENSE) or later. - -Scan only targets you are authorized to scan. +[MIT](LICENSE). See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md). WhatWeb itself is licensed by its upstream authors. Scan only targets you are authorized to scan. ## Qualifying leads by their tech stack? diff --git a/SECURITY.md b/SECURITY.md index f566fb3..483e730 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,11 +2,12 @@ ## Supported versions -Only the latest release is supported. +The `latest` tag on Docker Hub and the tip of `main` are supported. ## Reporting a vulnerability -Email security@devkind.com.au. +Email the maintainers via the Devkind GitHub organisation +(open a private security advisory on the repo if enabled, or contact an admin). Please do not open public issues for suspected vulnerabilities. We aim to respond within 5 business days. diff --git a/requirements.txt b/requirements.txt index fe77cea..16b15e9 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,3 @@ -mcp==1.28.1 +mcp==1.6.0 pydantic==2.11.5 pydantic-settings==2.9.1 diff --git a/server.json b/server.json index 4abcc0a..2a3ff86 100644 --- a/server.json +++ b/server.json @@ -8,11 +8,11 @@ "url": "https://github.com/devkindhq/whatweb-mcp", "source": "github" }, - "version": "1.1.0", + "version": "1.0.1", "packages": [ { "registryType": "oci", - "identifier": "docker.io/devkind/whatweb-mcp:1.1.0", + "identifier": "docker.io/devkind/whatweb-mcp:1.0.1", "transport": { "type": "stdio" }, @@ -35,7 +35,12 @@ "_meta": { "io.modelcontextprotocol.registry/publisher-provided": { "author": "Devkind", - "website": "https://devkind.com.au" + "website": "https://devkind.com.au", + "tools": [ + "whatweb_scan", + "get_scan_results", + "list_active_scans" + ] } } } diff --git a/server.py b/server.py index 660d13a..1ac4d01 100644 --- a/server.py +++ b/server.py @@ -27,7 +27,7 @@ TextContent, Tool, ) -from pydantic import AnyUrl, BaseModel, Field +from pydantic import BaseModel, Field from pydantic_settings import BaseSettings logging.basicConfig( @@ -176,7 +176,7 @@ async def run_whatweb_scan( aggression_level = AGGRESSION_LEVELS.get(aggression, 3) - # Uses create_subprocess_exec (args array, no shell), safe against injection + # Uses create_subprocess_exec (args array, no shell) — safe against injection cmd = [ "whatweb", "-a", str(aggression_level), @@ -348,8 +348,7 @@ async def list_resources() -> list[Resource]: @app.read_resource() -async def read_resource(uri: AnyUrl) -> str: - uri = str(uri) +async def read_resource(uri: str) -> str: if uri.startswith("whatweb://results/"): scan_id = uri.replace("whatweb://results/", "") result = scan_results.get(scan_id) diff --git a/skills/tech-detector/SKILL.md b/skills/tech-detector/SKILL.md index 022fa75..6984b3f 100644 --- a/skills/tech-detector/SKILL.md +++ b/skills/tech-detector/SKILL.md @@ -4,7 +4,7 @@ description: Detect the technology stack of any website for lead qualification a tools: [whatweb_scan] --- -# Tech Detector: Stack Analysis +# Tech Detector — Stack Analysis ## When to use this skill @@ -20,7 +20,7 @@ Trigger when: Call the `whatweb_scan` tool (exposed by this repo's WhatWeb MCP server) with: - `target`: the URL provided -- `aggression`: `normal` (default, non-intrusive, safe for live sites) +- `aggression`: `normal` (default — non-intrusive, safe for live sites) If the scan is long-running, follow up with `get_scan_results` (fetch by `scan_id`) or `list_active_scans` (see what is running). @@ -30,10 +30,10 @@ Always present findings in three sections: ### 1. Stack Summary Plain-English summary of what they're running. Group by: -- **Platform/CMS**: Shopify, WordPress, Webflow, custom, etc. -- **Frontend**: React, Vue, jQuery, Bootstrap, etc. -- **Infrastructure**: Cloudflare, AWS, Vercel, Fastly, etc. -- **Analytics/Marketing**: GTM, GA4, HubSpot, Intercom, etc. +- **Platform/CMS** — Shopify, WordPress, Webflow, custom, etc. +- **Frontend** — React, Vue, jQuery, Bootstrap, etc. +- **Infrastructure** — Cloudflare, AWS, Vercel, Fastly, etc. +- **Analytics/Marketing** — GTM, GA4, HubSpot, Intercom, etc. ### 2. What This Tells Us Interpret the stack in business terms: @@ -47,24 +47,24 @@ Map detected tech to specific opportunities: | Detected | Observation | |----------|-------------| -| Shopify (Bootstrap/jQuery theme) | Likely older theme: performance and modernisation opportunity | -| Shopify (no GTM/analytics) | Analytics gap: no conversion tracking in place | +| Shopify (Bootstrap/jQuery theme) | Likely older theme — performance and modernisation opportunity | +| Shopify (no GTM/analytics) | Analytics gap — no conversion tracking in place | | WordPress | Common maintenance pain points: performance, security, plugin sprawl | -| Webflow | Hosted CMS constraints: custom dev or migration may be needed at scale | -| No identifiable platform | Likely custom build: dev team dependency, higher maintenance cost | -| jQuery / Bootstrap (no modern framework) | Legacy frontend: migration to React/Vue may be warranted | +| Webflow | Hosted CMS constraints — custom dev or migration may be needed at scale | +| No identifiable platform | Likely custom build — dev team dependency, higher maintenance cost | +| jQuery / Bootstrap (no modern framework) | Legacy frontend — migration to React/Vue may be warranted | | No HTTPS / missing HSTS | Basic security gap, quick to address | | Google Tag Manager | Active marketing instrumentation in place | -| Cloudflare | Performance and security aware, sophisticated infra | +| Cloudflare | Performance and security aware — sophisticated infra | | Vercel / Next.js | Modern stack, likely needs backend/API or design system work | -| No CDN detected | Performance risk: static assets served from origin | +| No CDN detected | Performance risk — static assets served from origin | ## Output format Keep it tight and actionable. Example: --- -**[Company]: Tech Stack** +**[Company] — Tech Stack** **Platform:** Shopify **Frontend:** Bootstrap, jQuery (legacy theme) @@ -75,13 +75,13 @@ Keep it tight and actionable. Example: They're on a standard Shopify setup with an older theme stack (Bootstrap/jQuery). GTM presence means there's an active marketing team. Cloudflare suggests someone technical is involved, even if their dev team is small. **Analysis angles:** -- Custom Shopify theme (modern, performance-focused). Bootstrap/jQuery theme is likely slow +- Custom Shopify theme (modern, performance-focused) — Bootstrap/jQuery theme is likely slow - Headless Shopify if they're hitting platform limits -- Analytics depth: GTM is present, tracking baseline is in place +- Analytics depth — GTM is present, tracking baseline is in place --- ## Parallelisation -Safe: this skill is stateless and read-only (HTTP scan only). Multiple tech-detector agents can run simultaneously against different URLs with no conflicts or side effects. +Safe — this skill is stateless and read-only (HTTP scan only). Multiple tech-detector agents can run simultaneously against different URLs with no conflicts or side effects. ## Machine-readable Return Contract When invoked by an orchestrator agent collecting results for multiple targets, return a JSON envelope alongside the markdown report: @@ -98,6 +98,6 @@ The orchestrator uses this to aggregate and sort results without parsing the mar ## Notes - If http_status is not 200, flag it ("site may be down or blocking scanners") -- If very few technologies detected (<5), note that the site may be behind a heavy proxy or WAF masking the stack. Suggest running with `aggression: aggressive` for a deeper look -- Never present raw scan JSON to the user. Always translate to the format above +- If very few technologies detected (<5), note that the site may be behind a heavy proxy or WAF masking the stack — suggest running with `aggression: aggressive` for a deeper look +- Never present raw scan JSON to the user — always translate to the format above - If no URL is provided, ask for one before running diff --git a/smithery.yaml b/smithery.yaml new file mode 100644 index 0000000..c71cfdd --- /dev/null +++ b/smithery.yaml @@ -0,0 +1,23 @@ +name: whatweb-mcp +description: Website technology fingerprinting for AI agents, powered by WhatWeb. Multi-arch Docker. +vendor: Devkind +homepage: https://devkind.com.au/services +license: MIT +startCommand: + type: stdio + configSchema: + type: object + properties: + timeout: + type: number + description: Per-scan timeout in seconds + default: 300 + maxConcurrent: + type: number + description: Maximum concurrent scans + default: 2 + commandFunction: |- + (config) => ({ + command: "docker", + args: ["run", "-i", "--rm", "--memory=512m", "--cpus=0.5", "--pids-limit=100", "-e", `WHATWEB_TIMEOUT=${config.timeout ?? 300}`, "-e", `WHATWEB_MAX_CONCURRENT=${config.maxConcurrent ?? 2}`, "devkind/whatweb-mcp:latest"] + }) From 596f072bc49d0bc33ce8e241a0441e9f69fdb7c9 Mon Sep 17 00:00:00 2001 From: Uzair Ahmed Date: Mon, 2 Nov 2026 15:59:46 +0500 Subject: [PATCH 3/5] fix: bump mcp to 1.28.1 and fix read_resource mcp 1.6.0 has five High advisories. The SDK passes an AnyUrl, not a str, to read_resource. --- requirements.txt | 2 +- server.py | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/requirements.txt b/requirements.txt index 16b15e9..fe77cea 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,3 @@ -mcp==1.6.0 +mcp==1.28.1 pydantic==2.11.5 pydantic-settings==2.9.1 diff --git a/server.py b/server.py index 1ac4d01..bccae5c 100644 --- a/server.py +++ b/server.py @@ -27,7 +27,7 @@ TextContent, Tool, ) -from pydantic import BaseModel, Field +from pydantic import AnyUrl, BaseModel, Field from pydantic_settings import BaseSettings logging.basicConfig( @@ -348,7 +348,8 @@ async def list_resources() -> list[Resource]: @app.read_resource() -async def read_resource(uri: str) -> str: +async def read_resource(uri: AnyUrl) -> str: + uri = str(uri) if uri.startswith("whatweb://results/"): scan_id = uri.replace("whatweb://results/", "") result = scan_results.get(scan_id) From 653830a97c1f8a3f3025a599ed00d7b72c780a1c Mon Sep 17 00:00:00 2001 From: Uzair Ahmed Date: Mon, 2 Nov 2026 16:16:51 +0500 Subject: [PATCH 4/5] docs: drop Smithery from the roadmap --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b41a767..bba5dab 100644 --- a/README.md +++ b/README.md @@ -165,7 +165,7 @@ This repo ships a ready-made agent skill at [`skills/tech-detector/SKILL.md`](sk ## Roadmap - [x] Official MCP Registry listing (`io.github.devkindhq/whatweb-mcp`) -- [ ] Docker MCP Registry and Smithery listings +- [ ] Docker MCP Registry listing - [ ] Batch scanning (multiple targets in one call) - [ ] Optional CSV/JSON export tool - [ ] Scheduled re-scans with diffing (alert when a target's stack changes) From 4f1dc4632ba1bff78f7bd340b1219d7159b7bf48 Mon Sep 17 00:00:00 2001 From: Uzair Ahmed Date: Mon, 9 Nov 2026 09:38:07 +0500 Subject: [PATCH 5/5] chore: remove smithery.yaml Smithery shut down its hosted services on 31 Oct 2026. --- smithery.yaml | 23 ----------------------- 1 file changed, 23 deletions(-) delete mode 100644 smithery.yaml diff --git a/smithery.yaml b/smithery.yaml deleted file mode 100644 index c71cfdd..0000000 --- a/smithery.yaml +++ /dev/null @@ -1,23 +0,0 @@ -name: whatweb-mcp -description: Website technology fingerprinting for AI agents, powered by WhatWeb. Multi-arch Docker. -vendor: Devkind -homepage: https://devkind.com.au/services -license: MIT -startCommand: - type: stdio - configSchema: - type: object - properties: - timeout: - type: number - description: Per-scan timeout in seconds - default: 300 - maxConcurrent: - type: number - description: Maximum concurrent scans - default: 2 - commandFunction: |- - (config) => ({ - command: "docker", - args: ["run", "-i", "--rm", "--memory=512m", "--cpus=0.5", "--pids-limit=100", "-e", `WHATWEB_TIMEOUT=${config.timeout ?? 300}`, "-e", `WHATWEB_MAX_CONCURRENT=${config.maxConcurrent ?? 2}`, "devkind/whatweb-mcp:latest"] - })