# @hootlens/mcp 中文文档

规范地址：https://npmcn.com/package/%40hootlens/mcp/

版本：1\.4\.0
npm 元数据更新时间：2026-11-01T06:43:44.107Z
中文译文更新时间：2026-11-01T08:47:00.502Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40hootlens/mcp
原文对照：https://npmcn.com/package/%40hootlens/mcp/?lang=original
项目主页：https://hootlens.com/docs/MCP.md
源码仓库：https://github.com/Parallel-Platforms/hootlens-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.8 MB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-10-07T23:20:19.778Z
- 最新版本发布：2026-11-01T06:43:43.727Z
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

Hoot Lens MCP服务器：让AI助手读取录音，重播，热图，漏斗和发现从Hoot Lens，与您自己的访问。

## 安装

```sh
npm install @hootlens/mcp
```

也可以使用：`pnpm add @hootlens/mcp`、`yarn add @hootlens/mcp`、`bun add @hootlens/mcp`

## README

# @hootlens / mcp

Hoot Lens MCP服务器。它可以让AI助手（Claude, Cursor, VS Code， Codex和其他MCP客户端）读取Hoot Lens在您的网站上记录的内容：访问，重播，热图，漏斗，流量，发现和变化。助手只能看到您自己的Hoot Lens帐户可以看到的内容，并且只能看到您允许的网站（项目）和范围。

你可以用两种方式运行它：

-   **本地直播间** 与 `npx -y @hootlens/mcp` （此包），用于可以启动工作室服务器的客户端。
-   **主持** 在 `https://mcp.hootlens.com/mcp`，用于支持远程MCP服务器的客户端。无需安装；你在浏览器中使用Hoot Lens登录。

工具目录依赖于版本和选择的工具集。Source 1.4.0使客户工具在授予可选权限之前可以被发现。发现工具不授予访问权限：API每次都会检查凭据、当前站点权限和请求的操作。较早的版本可能会隐藏其作用域缺失的工具。检查已安装版本并巡检 `tools/list` 根据你的实际联系。 `whoami` 可作为CLI命令和MCP连接检查工具使用； `doctor` 要求1.2.0或更高版本。

读取工具集包括 `explain_snags`。当站点启用AI解释时，请求可以向解释提供者发送汇总计数，并使用站点所有者的每月AI帐户津贴。在要求解释之前检查它的工具描述。医生在不调用该工具的情况下报告了这个警告。

## 要求

-   Node.js 20或更新版本（仅限本地服务器）。
-   Hoot Lens账号。读取录音需要一个可访问的站点。新的所有者可以在连接期间添加他们的第一个网站，然后批准对该网站的访问。让助手创建其他站点需要单独的显式OAuth `sites:create` 许可和包含 `create_site`.

## 登录

选择一个。

**浏览器登录（推荐）。** 运行一次：

```sh
npx -y @hootlens/mcp login
```

你的浏览器打开Hoot Lens。选择要共享的项目和权限，并批准。登录保存在macOS Keychain， Linux Secret Service （libsecret）中，或者，如果这些都不可用，则保存在一个文件(`~/.config/hootlens-mcp/credentials.json`，或者 `%APPDATA%\hootlens-mcp\credentials.json` 在Windows上)。在POSIX系统上，回退使用仅所有者模式标志。在Windows上，它依赖于继承的配置文件acl；该包不强制一个仅限所有者的Windows ACL。令牌永远不会被打印。

如果您还没有网站，请在连接屏幕中输入您的网站。创建网站和批准助理访问是两个不同的决定。您只能共享具有读/重放访问权限的新站点；创建未来站点的帐户范围权限是可选的。返回到助手后，要求它检索您平台的安装说明。已连接的帐户和已创建的站点不确定是否安装了跟踪标签或接收数据。

```sh
npx -y @hootlens/mcp whoami   # who is signed in, scopes, projects, token expiry
npx -y @hootlens/mcp logout   # delete the saved sign-in and end it at the server
```

`login --scopes read,replay` 请求更少的权限(默认： `read replay annotate`）. 在没有浏览器的远程机器上， `login` 打印链接；在一台可以访问CLI的机器上打开它 `127.0.0.1` （例如，通过它指定的端口的SSH端口转发）。

持续时间：访问令牌持续1小时，并自动更新。更新令牌从最后一次使用算起持续30天，因此如果您在30天内没有使用服务器，则必须运行 `login` 再一次。在Hoot Lens仪表板的“已连接应用”下断开连接，将立即终止登录。当登录结束时，服务器会告诉您运行 `npx -y @hootlens/mcp login`.

**访问密钥。** 在仪表板中，打开设置，AI助手，并为一个项目创建一个密钥。设置为 `HOOTLENS_PAT` 在客户的环境中。当 `HOOTLENS_PAT` 设置时，将使用它代替已保存的登录。一个密钥属于一个项目，您可以随时在仪表板中撤销它。建议在个人机器上使用浏览器登录，并使用CI或共享设置的密钥。

## 检查本地设置

对于1.2.0或更高版本，运行：

```sh
npx -y @hootlens/mcp doctor --toolsets read,replay
npx -y @hootlens/mcp doctor --authenticated --toolsets read,replay --project YOUR_PROJECT_ID --json
```

默认情况下检查公共准备情况和OAuth元数据以及本地配置。第二个命令显式地将现有凭据发送给 `/v1/access` 查看选定的场地和补助金。这两个命令都不会刷新令牌、更改登录、读取记录或调用MCP工具。配置的PAT将覆盖保存的浏览器登录。对于自定义HTTPS API，检查报告的来源并显式添加 `--trust-api https://YOUR_EXPECTED_API` 验证检查前。

退出代码: `0` 表示选定的支票已通过； `1` 表示服务或访问检查失败，并且 `2` 表示选项或配置无效。JSON包括 `schemaVersion`， `authenticatedMetadataVerified`，检查代码和恢复步骤。 `investigationVerified` 保持虚假：要求你的客户提供一个发现和一个定时的叙述来证明调查。医生有10秒的时限和有限的反应体；它的作用域是本地工作室配置，而不是远程客户端保存的登录或对交互式视图的支持。

## 创建站点作为经过身份验证的代理

在1.1.0或更高版本中，选择加入 `login --scopes read,replay,annotate,sites:create`。经过验证的帐户所有者必须显式批准浏览器中所有站点的站点创建。该权限从不包含在默认登录范围中。个人访问令牌、匿名演示连接和项目固定连接无法创建站点。源1.4.0广告 `create_site` 在授予权限之前，在正常的未固定连接上，以便助手可以发现操作。支持工具级OAuth的托管客户端可以在调用工具时请求该权限。否则，重新连接并显式批准所请求的范围。检查 `tools/list` 根据你的实际联系。

呼叫 `create_site` 与 `name`准确的HTTPS `origins`，一个马厩 `idempotencyKey` （8 ~ 128个可打印的ASCII字符，如UUID）。超时或24小时内出现网络故障后，使用相同的密钥和站点参数。幂等保护在24小时后失效；检查 `list_projects` ，然后再重新创建。API自动执行计划的可用站点槽。新网站默认使用平衡隐私（严格是可选的）并需要同意。结果给出一个项目ID和平台特定的安装说明。安装在公共页面上，征得同意，然后打电话 `check_install`;创作本身并不能证明是录音作品。如果没有安装说明，请使用 `get_install_snippet` 为返回的项目ID而不是创建另一个站点。

`start_setup` 和 `check_setup` 当用户明确请求时，提供电子邮件确认的替代方案。在调用任何工具之前，托管的MCP连接器都需要登录。公共REST登录端点允许所有者在没有现有帐户的情况下开始电子邮件确认，但这是一个单独的入口路径。本地工作室启动程序还需要其配置的登录或访问密钥。不要使用电子邮件设置绕过连接器的授权，也不要以他们的名义打开所有者的确认链接。

## 安装到您的客户端

下面的命令使用本地服务器。取代 `YOUR_PROJECT_ID` 如果要固定一个项目（可选；请参阅项目固定）。如果你没有跑 `login`，加上你的 `HOOTLENS_PAT` 如每个示例所示。

### 克劳德代码

地方:

```sh
claude mcp add --transport stdio hootlens -- npx -y @hootlens/mcp
# with an access key instead of the saved sign-in, and a pinned project:
claude mcp add --transport stdio --env HOOTLENS_PAT=hl_pat_... hootlens -- npx -y @hootlens/mcp --project YOUR_PROJECT_ID
```

托管（然后运行） `/mcp` 在Claude代码内登录)：

```sh
claude mcp add --transport http hootlens "https://mcp.hootlens.com/mcp"
```

添加 `--scope project` 与你的团队分享参赛作品 `.mcp.json`，或者 `--scope user` 对于你所有的项目。

### 光标

将......添加到...... `.cursor/mcp.json` 在一个项目中，或者 `~/.cursor/mcp.json` 适用于所有项目。

地方:

```json
{
  "mcpServers": {
    "hootlens": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hootlens/mcp"],
      "env": { "HOOTLENS_PAT": "${env:HOOTLENS_PAT}" }
    }
  }
}
```

离开了 `env` 来使用保存的登录 `login`.

主持:

```json
{
  "mcpServers": {
    "hootlens": { "url": "https://mcp.hootlens.com/mcp" }
  }
}
```

### VS代码

将......添加到...... `.vscode/mcp.json` (顶级键是 `servers`,而不是 `mcpServers`）。

地方:

```json
{
  "inputs": [
    { "type": "promptString", "id": "hootlens-pat", "description": "Hoot Lens access key", "password": true }
  ],
  "servers": {
    "hootlens": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hootlens/mcp"],
      "env": { "HOOTLENS_PAT": "${input:hootlens-pat}" }
    }
  }
}
```

离开了 `inputs` 和 `env` 来使用保存的登录 `login`.

主持:

```json
{
  "servers": {
    "hootlens": { "type": "http", "url": "https://mcp.hootlens.com/mcp" }
  }
}
```

### 克劳德桌面

当地。打开设置，开发人员，编辑配置，并添加到 `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`Windows: `%APPDATA%\Claude\claude_desktop_config.json`)，然后退出并重新打开Claude Desktop：

```json
{
  "mcpServers": {
    "hootlens": {
      "command": "npx",
      "args": ["-y", "@hootlens/mcp"]
    }
  }
}
```

这将使用保存的登录 `login`． 要使用访问键，请添加 `"env": { "HOOTLENS_PAT": "hl_pat_..." }`.

主持。远程服务器不会添加到JSON文件中。在Claude Desktop中添加一个带有URL的自定义连接器（Customize, Connectors, add custom connector） `https://mcp.hootlens.com/mcp`，然后在被要求时登录Hoot Lens。自定义连接器取决于您的Claude计划。

### 食典委

地方:

```sh
codex mcp add hootlens -- npx -y @hootlens/mcp
# with an access key:
codex mcp add hootlens --env HOOTLENS_PAT=hl_pat_... -- npx -y @hootlens/mcp
```

同样的 `~/.codex/config.toml`：

```toml
[mcp_servers.hootlens]
command = "npx"
args = ["-y", "@hootlens/mcp"]
# env_vars = ["HOOTLENS_PAT"]   # forward the key from your shell instead of saving it here
```

主持:

```toml
[mcp_servers.hootlens]
url = "https://mcp.hootlens.com/mcp"
```

然后运行 `codex mcp login hootlens`.

### 其他客户

任何可以启动stdio服务器的客户端：命令 `npx`,参数 `-y @hootlens/mcp`，可选环境 `HOOTLENS_PAT`． 任何通过带有OAuth的可流式HTTP支持远程服务器的客户端：URL `https://mcp.hootlens.com/mcp`． 托管端点通过标准OAuth发现（RFC 9728和RFC 8414）发布其登录，并接受客户端ID元数据文档和动态客户端注册。

## 托管URL选项

两个可选的查询参数缩小托管工具目录或固定站点。他们从不扩大你认可的范围。

| 参数 | 例子 | 效果 |
| --- | --- | --- |
| `project` | `https://mcp.hootlens.com/mcp?project=YOUR_PROJECT_ID` | 此项目默认使用的工具。 |
| `toolsets` | `https://mcp.hootlens.com/mcp?toolsets=read,replay` | 只提供这些工具集。 |

将它们与 `&`： `https://mcp.hootlens.com/mcp?project=YOUR_PROJECT_ID&toolsets=read`． 在shell中把URL放在引号中。

## 工具集

工具集对工具进行分组，以便只向助手提供所需的工具。将它们与 `--toolsets read,replay` 或者 `HOOTLENS_TOOLSETS=read,replay`.

| 工具集 | 它提供什么 |
| --- | --- |
| `read` | 网站（项目）、访问、记录列表、叙述、热图、发现、流量、目标、渠道、变化、每周总结。 |
| `replay` | 一个记录的原始重播事件和单击，以及交互式重播视图加载的事件。需要 `replay` 范围。 |
| `annotate` | 为录音和日志更改添加注释。需要 `annotate` 范围。 |
| `configure` | 预览和应用站点设置更改。需要可选 `configure` 范围。 |
| `install` | 每个平台安装标签和安装检查器。 |
| `sites` | 用你自己的账户创建一个网站。需要明确批准OAuth `sites:create` 用于所有站点和未固定的连接。 |
| `feedback` | 向Hoot Lens团队报告漏洞和想法，并遵循您的报告。 |
| `issues` | Hoot Lens员工分类工具。需要 `triage` 范围。 |
| `default` | 客户目录： `read`， `replay`， `annotate`， `configure`， `install`， `sites`, `feedback`. |
| `all` | 每一个客户工具集，加上员工分流授权。 |

这些默认值描述了1.4.0源代码。在没有明确选择的情况下，授权人员也会收到 `issues` 工具集。当普通客户工具的执行范围丢失时，它们仍然是可发现的。每个描述符声明其所需的OAuth范围。调用没有所需范围的托管工具将在操作运行之前返回权限挑战。站点角色拒绝仍然是拒绝，即使OAuth批准已经包含了该范围。工作人员的分类仍然隐藏在外面 `triage`，以及固定或演示连接不提供网站创建。显式的工具集选择仍然会缩小目录。

对于仅用于调查的目录，请选择 `--toolsets read,replay` 然后用 `login --scopes read,replay`． 选择工具集和授予范围是单独的控件：第一个控件控制助手看到的内容，第二个控件控制凭据可以执行的内容。

## 互动的观点

在呈现MCP应用程序（如Claude）的客户端中，访问叙述显示为您可以播放和逐步通过的重播，热图显示页面上的点击密度，结果显示为卡片。其他客户机一如既往地获得相同的文本和数据。视图本身没有请求，也没有从第三方加载任何内容；重放视图通过您的连接读取记录，并需要 `replay` 范围。看到 [MCP文档](https://hootlens.com/docs/MCP.md#mcp-apps).

## 项目将

默认情况下，工具采用a `projectId`． 在一个项目中工作，钉住它。第一个设定的人获胜：

1.  `--project YOUR_PROJECT_ID`
2.  `HOOTLENS_PROJECT=YOUR_PROJECT_ID`
3.  一、 `.hootlens.json` 工作目录或任何父目录下的文件： `{"projectId": "YOUR_PROJECT_ID"}`． 项目id是公开的，因此提交文件是安全的。

固定设置一个默认值。API仍然根据您的凭据可能到达的位置检查每个调用。

## 配置

| 变量 | 目的 |
| --- | --- |
| `HOOTLENS_PAT` | 访问密钥。覆盖已保存的登录。 |
| `HOOTLENS_API_URL` | API来源（默认：Hoot Lens生产API）。所使用的 `login`， `whoami` 还有服务器。 |
| `HOOTLENS_PROJECT` | 固定的项目。 |
| `HOOTLENS_TOOLSETS` | 用逗号分隔的工具集。 |

服务器只向stderr写入消息。标准输出携带MCP协议。

## 故障排除

-   **“没有凭据”**:跑 `npx -y @hootlens/mcp login`，或设置 `HOOTLENS_PAT`.
-   **“登录已经结束”**： 30天未使用或在仪表板中断开连接。运行 `login` 再一次。
-   **工具显示一个瞄准镜不见了**：证书缺少该权限。运行 `login --scopes read,replay,annotate`，或者将范围添加到仪表板中的访问键中。
-   **找不到项目**：您在登录时没有分享，或者您不是会员。运行 `whoami` 列出凭证可以达到的范围。
-   **`npx` 没有被Claude Desktop或编辑器找到**这些应用程序以简短的开头 `PATH`． 使用绝对路径 `npx` （`which npx`)作为命令，或者从nodejs.org安装Node。
-   **Linux上没有钥匙链（无头服务器，容器）**：登录回退到私有文件。安装 `libsecret-tools` 让特勤局使用钥匙链
-   **`login` 表示所有端口都在使用中**： login监听127.0.0.1端口28731到28735。关闭正在使用它们的程序并运行 `login` 再一次。
-   **背后是代理还是脱机**：服务器需要通过HTTPS访问API(或 `HOOTLENS_API_URL`）。
-   **显示版本**： `npx -y @hootlens/mcp --version`.

## 版本

该包遵循语义版本控制。工具名称和参数在主版本中不会改变；新工具和可选参数可能出现在次要版本中。看到 `CHANGELOG.md`. `npx -y @hootlens/mcp` 总是运行最新的1.x；销和 `npx -y @hootlens/mcp@1.0.1` 如果您需要一个固定版本。服务器支持的MCP协议版本为2026-07-28和2025。

## 隐私

服务器只使用您自己的凭据将您的请求转发到Hoot Lens API。除了上面描述的登录之外，它不存储任何东西。Hoot Lens永远不会捕获密码，付款或一次性代码值，并且重播掩盖其他表单值，除非站点允许列出它们。

## 许可证

看到 `LICENSE`.

## 验证笔记

在2026-10-07上根据每个工具的文档检查了上面的客户端说明。

官方文件证实：

-   克劳德代码: `claude mcp add --transport stdio ... -- <command>`， `--env`， `--transport http`， `--scope`，并与 `/mcp` （[https://code.claude.com/docs/en/mcp](https://code.claude.com/docs/en/mcp)）。
-   游标: `.cursor/mcp.json` 和 `~/.cursor/mcp.json`， `mcpServers` 与 `command`/`args`/`env` (与 `type: "stdio"`), `url` （[https://cursor.com/docs/context/mcp](https://cursor.com/docs/context/mcp)）。
-   VS代码: `.vscode/mcp.json` 与 `servers`， `type` `stdio` 和 `http`, `inputs` 与 `${input:id}` （[https://code.visualstudio.com/docs/copilot/customization/mcp-servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)）。
-   克劳德桌面: `claude_desktop_config.json` 位置和 `mcpServers` 对于本地服务器([https://modelcontextprotocol.io/docs/develop/connect-local-servers](https://modelcontextprotocol.io/docs/develop/connect-local-servers)）; 远程服务器作为自定义连接器添加，而不是在文件([https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)）。
-   食典委: `codex mcp add <name> --env K=V -- <command>`， `[mcp_servers.<name>]` 与 `command`， `args`， `env_vars`， `url`, `codex mcp login <name>` （[https://developers.openai.com/codex/mcp](https://developers.openai.com/codex/mcp)）。

未确认，因此将其视为可能，但检查是否失败：

-   游标和VS Code启动浏览器，无需额外配置即可自行登录远程服务器。他们的文档只描述了预注册客户端的OAuth设置，所以如果登录没有启动，请使用本地服务器。
-   Codex添加了一个远程服务器 `codex mcp add hootlens --url ...`。这个 `config.toml` 以上表格为文件格式。
-   这个 `env = { HOOTLENS_PAT = "..." }` 法典内嵌表 `config.toml`;文档化的密钥是 `env_vars`.
-   克劳德桌面扩展(`.mcpb`)包装。这个包不提供。
-   包含Claude Desktop自定义连接器的计划。

## 常见问题

### @hootlens/mcp 是什么？

Hoot Lens MCP服务器：让AI助手读取录音，重播，热图，漏斗和发现从Hoot Lens，与您自己的访问。

### 如何安装 @hootlens/mcp？

在项目目录运行 npm install @hootlens/mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 hootlens-mcp，可以用 npx hootlens-mcp 直接运行。

### @hootlens/mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/hootlens\_\_mcp 是否存在。

### @hootlens/mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @hootlens/mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @hootlens/mcp 可以商用吗？

@hootlens/mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @hootlens/mcp 还在维护吗？

最新版本 1\.4\.0 发布于 2026/11/01（2 天前）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/10/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。