@hootlens/mcp 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +13 -3
  2. package/README.md +33 -13
  3. package/dist/cli.mjs +647 -387
  4. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -2,9 +2,19 @@
2
2
 
3
3
  All notable changes to `@hootlens/mcp` are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
4
4
 
5
- ## [1.1.0] - Prepared 2026-10-12
5
+ ## [1.2.0] - Unreleased
6
6
 
7
- Publication is pending. This entry describes the reviewed source, not a published npm artifact.
7
+ ### Added
8
+
9
+ - `doctor` checks the API's public readiness and OAuth identity, local credential availability, project selection and toolsets. `--authenticated` explicitly checks existing access metadata. It never refreshes or rewrites credentials, reads recordings, calls MCP tools or changes a grant.
10
+ - `doctor --json` produces a bounded, redacted report with stable check codes and exit statuses. Custom HTTPS APIs require an explicit matching `--trust-api` before an authenticated check. Connection health and completed investigations are reported separately.
11
+ - Read-tool diagnostics disclose conditional `explain_snags` provider and account AI allowance use.
12
+
13
+ ### Changed
14
+
15
+ - Registry metadata now links the public repository and lists the optional configuration and site-creation toolsets.
16
+
17
+ ## [1.1.0] - 2026-10-14
8
18
 
9
19
  ### Added
10
20
 
@@ -46,7 +56,7 @@ First release on npm. The same server was available before as a single-file down
46
56
  - Prompts for common jobs and resources for the Hoot Lens documentation.
47
57
  - Structured output for tool results, alongside the text content.
48
58
  - `hootlens-mcp login`, `logout` and `whoami`: sign in with your browser (OAuth with PKCE) instead of creating an access key. The sign-in is stored in the macOS Keychain, the Linux Secret Service, or a private file, and renews itself.
49
- - Packaging as an npm package with a `hootlens-mcp` command, and no runtime dependencies. Historical packages did not carry npm provenance.
59
+ - Packaging as an npm package with a `hootlens-mcp` command and no runtime dependencies. Historical 1.0.x packages did not carry npm provenance.
50
60
 
51
61
  ### Changed
52
62
 
package/README.md CHANGED
@@ -2,9 +2,9 @@
2
2
 
3
3
  Give your coding agent evidence from website visits: recordings, click maps, funnels and recurring snags. Trace a finding to the page, release, device and recorded moment before proposing a fix.
4
4
 
5
- This repository prepares buildable source for `@hootlens/mcp` 1.1.0, imported from the reviewed Hoot Lens source commit recorded in [SOURCE.json](docs/SOURCE.json). This checkout does not establish npm publication. The last published version verified during preparation is [1.0.2](https://www.npmjs.com/package/@hootlens/mcp/v/1.0.2). Issues and questions are welcome here.
5
+ This repository contains the Hoot Lens MCP source for 1.2.0, including the doctor command. Check the [release records and procedure](docs/RELEASING.md) for publication and provenance. Version [1.1.0](https://www.npmjs.com/package/@hootlens/mcp/v/1.1.0) was released on 14 October 2026 from the public [`mcp-v1.1.0` tag](https://github.com/Parallel-Platforms/hootlens-mcp/tree/mcp-v1.1.0). Issues and questions are welcome here.
6
6
 
7
- [Public release preparation](docs/RELEASING.md) proposes a reviewed migration to public CI with npm provenance for a future version. It has not published a new version or changed npm publisher settings. [Security scan evidence](docs/SECURITY-EVIDENCE.md) separates published-source inspection from synthetic runtime enumeration.
7
+ [The 1.1.0 release record](docs/RELEASE-1.1.0.md) links npm provenance, the exact public source and the official MCP Registry entry. Provenance identifies the source and build, not a security certification. The [1.1.0 security evidence](docs/security/release-1.1.0/README.md) records bounded scans and synthetic permission checks. [Historical scan evidence](docs/SECURITY-EVIDENCE.md) remains specific to the versions it inspected. Neither transfers to prepared 1.2.0.
8
8
 
9
9
  ## Try a first investigation without an account
10
10
 
@@ -31,33 +31,53 @@ The demo offers read and replay tools only. It requires no account or token. Sta
31
31
  The local package needs Node.js 20 or newer. Sign in with the projects and read permissions you want to share:
32
32
 
33
33
  ```sh
34
- npx -y @hootlens/mcp@1.0.2 login --scopes read,replay
35
- npx -y @hootlens/mcp@1.0.2 whoami
34
+ npx -y @hootlens/mcp@1.1.0 login --scopes read,replay
35
+ npx -y @hootlens/mcp@1.1.0 whoami
36
36
  ```
37
37
 
38
- Add a stdio server to your client with command `npx` and arguments `-y @hootlens/mcp@1.0.2 --toolsets read,replay` for an investigation connection. Read scopes alone do not remove default install and feedback tools, which can submit setup requests or issues. Selecting the toolsets narrows what your agent is offered. It uses the saved sign-in. `HOOTLENS_PAT`, when set, overrides it. You can pin a project with `--project YOUR_PROJECT_ID`; the API still checks access on every request.
38
+ Add a stdio server to your client with command `npx` and arguments `-y @hootlens/mcp@1.1.0 --toolsets read,replay` for an investigation connection. Read scopes alone do not remove default install and feedback tools, which can submit setup requests or issues. Selecting the toolsets narrows what your agent is offered. It uses the saved sign-in. `HOOTLENS_PAT`, when set, overrides it. You can pin a project with `--project YOUR_PROJECT_ID`; the API still checks access on every request.
39
39
 
40
40
  For remote clients, connect to `https://mcp.hootlens.com/mcp` and approve Hoot Lens sign-in in the browser. See the [current client guides and permission details](https://hootlens.com/docs/MCP.md), or the [Cline installation guide](llms-install.md).
41
41
 
42
- Package 1.0.2 and the hosted server have different release schedules. This local release provides analytics reads, replay data, installation tools, feedback and optional annotation. Hosted MCP Apps and newer configuration tools are not in this local release. The local `whoami` above is a CLI command; it is not an MCP tool in 1.0.2. Inspect `tools/list` on the connection you actually use.
42
+ Package 1.1.0 includes MCP Apps for hosts that render them, JavaScript error tools and optional site creation and configuration tools. The package and hosted server have separate release schedules. Run the CLI `whoami` above, then call the MCP `whoami` tool and inspect `tools/list` on the connection you actually use. A listed client guide is not proof that every client has been tested.
43
43
 
44
- End the local sign-in with `npx -y @hootlens/mcp@1.0.2 logout`. Revoke a connected app or access key in the Hoot Lens dashboard when access should end.
44
+ End the local sign-in with `npx -y @hootlens/mcp@1.1.0 logout`. Revoke a connected app or access key in the Hoot Lens dashboard when access should end.
45
+
46
+ ## Check local setup with doctor
47
+
48
+ Doctor requires 1.2.0 or a source build containing the command. Published 1.1.0 does not include it. In a release containing doctor:
49
+
50
+ ```sh
51
+ npx -y @hootlens/mcp doctor --toolsets read,replay
52
+ npx -y @hootlens/mcp doctor --authenticated --project YOUR_PROJECT_ID --toolsets read,replay --json
53
+ ```
54
+
55
+ To check this source before publication, build the checkout and use its executable:
56
+
57
+ ```sh
58
+ node dist/cli.mjs doctor --toolsets read,replay
59
+ node dist/cli.mjs doctor --authenticated --project YOUR_PROJECT_ID --toolsets read,replay --json
60
+ ```
61
+
62
+ The first checks public readiness and OAuth identity plus local configuration and credential availability. The second explicitly reads existing access metadata. Neither refreshes tokens, changes grants, reads recordings or calls tools. A PAT overrides saved sign-in. Custom HTTPS APIs require a matching `--trust-api https://YOUR_EXPECTED_API` before an authenticated check. JSON includes stable check codes and recovery steps; exit codes are `0` for selected checks passed, `1` for service/access failure and `2` for invalid configuration. A successful check is not a completed investigation or proof of remote client sign-in.
63
+
64
+ Read tools include `explain_snags`: if explanations are enabled for the site, requests can send aggregated counts to the provider and use the site owner's monthly account AI allowance. Doctor discloses this and never calls the tool. Use client approval or allowlist controls when you want an investigation without explanation-provider effects.
45
65
 
46
66
  ## Create a site through an authenticated agent
47
67
 
48
- The prepared 1.1.0 source adds `create_site`. The verified account owner must explicitly approve the optional OAuth `sites:create` permission for all sites. It is never included in default login scopes. Personal access tokens, anonymous demo connections and project-pinned connections cannot create sites. An owner with no sites can authorize an agent to create their first site.
68
+ Package 1.1.0 adds `create_site`. The verified account owner must explicitly approve the optional OAuth `sites:create` permission for all sites. It is never included in default login scopes. Personal access tokens, anonymous demo connections and project-pinned connections cannot create sites. An owner with no sites can authorize an agent to create their first site.
49
69
 
50
- From a built checkout, opt in with:
70
+ Opt in with:
51
71
 
52
72
  ```sh
53
- node dist/cli.mjs login --scopes read,replay,sites:create
73
+ npx -y @hootlens/mcp@1.1.0 login --scopes read,replay,sites:create
54
74
  ```
55
75
 
56
- The tool takes a site name, exact HTTPS origins and a stable `idempotencyKey`. The API enforces available site slots atomically. New agent-created sites use balanced or strict privacy and require visitor consent. Retrying the same site arguments and key recovers the original site for 24 hours. After that, inspect existing sites before creating again.
76
+ Offer `read,replay,sites,install` toolsets on an unpinned connection. The tool takes a site name, exact HTTPS origins and a stable `idempotencyKey`. The API enforces available site slots atomically. New agent-created sites use balanced or strict privacy and require visitor consent. Retrying the same site arguments and key recovers the original site for 24 hours. After that, inspect existing sites before creating again.
57
77
 
58
78
  The response distinguishes site creation from tag installation and received recording data. Install the platform-specific code, connect the visitor consent platform or an explicit consent control, then use `check_install`. If fetching installation code temporarily fails, the response keeps the created project ID so the agent can retrieve its tag with `get_install_snippet` rather than create another site.
59
79
 
60
- This source also includes MCP Apps, JavaScript error tools and the optional `configure` toolset. Settings changes remain a preview and apply flow that can only tighten privacy. Existing OAuth connections require fresh approval to gain a new optional permission. Inspect `tools/list` on the actual connection; npm 1.0.2 does not include these newer tools.
80
+ The optional `configure` toolset requires its own approved permission. Settings changes remain a preview and apply flow that can only tighten privacy. Existing OAuth connections require fresh approval to gain a new optional permission. Inspect `tools/list` on the actual connection; npm 1.0.2 does not include these newer tools.
61
81
 
62
82
  ## Build and verify the source
63
83
 
@@ -73,7 +93,7 @@ The shared source needed by the server is included under `packages/core`. No pri
73
93
 
74
94
  The tests check snapshot hashes, version identity, CLI execution and a real stdio SDK connection to a loopback API with synthetic fixtures. They check read-tool discovery, project pinning and API refusal. They do not validate customer capture, production authorization, browser sign-in or compatibility with every client. CI runs these checks on Linux and Windows with Node 20 and 22; consult the actual run before claiming those platforms passed.
75
95
 
76
- [Source provenance and synchronization](docs/SOURCE.md) records the exact imported source commit and normalized file hashes for the prepared 1.1.0 source. No npm integrity or attestation is recorded for this unpublished version. Historical 1.0.2 security evidence remains separately versioned.
96
+ [Source identity and synchronization](docs/SOURCE.md) describes the complete prepared 1.2.0 import. The [1.1.0 release record](docs/RELEASE-1.1.0.md) separately identifies the published 1.1.0 artifact and provenance. Historical security evidence remains versioned.
77
97
 
78
98
  ## Privacy and access
79
99