# @bevel-software/hexis-mcp 中文文档

规范地址：https://npmcn.com/package/%40bevel-software/hexis-mcp/

版本：0\.37\.0
npm 元数据更新时间：2026-11-05T17:23:59.028Z
中文译文更新时间：2026-11-08T00:37:00.594Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40bevel-software/hexis-mcp
原文对照：https://npmcn.com/package/%40bevel-software/hexis-mcp/?lang=original
项目主页：https://github.com/Bevel-Software/Hexis#readme
源码仓库：https://github.com/Bevel-Software/Hexis

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

- 包体积（解压后）：870 kB，84 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.13 \<23 \|\| \>=24 \<25
- 运行依赖：8 个
- 首次发布：2026-08-16T20:08:17.304Z
- 最新版本发布：2026-11-05T17:23:58.834Z
- 近 30 天下载量：2721（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 36 个）

## 中文简介

运行一个Hexis工作空间作为本地的MCP服务器:主机端点所服务的每一个工具,加上它无法到达的本地唯一的工具.

## 安装

```sh
npm install @bevel-software/hexis-mcp
```

也可以使用：`pnpm add @bevel-software/hexis-mcp`、`yarn add @bevel-software/hexis-mcp`、`bun add @bevel-software/hexis-mcp`

## README

# @bevel-software/hexis-mcp (英语)

运行一个 [中国](https://github.com/Bevel-Software/Hexis) 作为工作空间 **当地** MCP服务器.

一个工作空间已经发布一个主机MCP端点,并且对于大多数工具来说都是运行它们的适当地点. 不过 `.tool` 标记 `remote: false` —— MCP 服务器打开 `localhost`,这个服务只在您的网络中回答——是主机端点无法到达的. 它跳过那些工具,只能命名它们,通过 `list_local_tools`。 。 。 .

这个命令通过成为这些工具的实际位置来填补空白,而不放弃主机端点给你的任何东西.

```bash
npx @bevel-software/hexis-mcp --url https://your-workspace.example
```

**需要节点22.13+或24.** 这些版本是这个服务器的沙盒`isolated-vm`) 发布一个预建的二进制; 在任何其他一个上, 它会编译 C++ 在您的机器上, 因此命令以一句话拒绝 。 选择一个 `nvm install 22`,或者指向您的 MCP 客户端 `"command"` 在那个版本 `npx` ——绝对路径,有: `-y @bevel-software/hexis-mcp` 参数不变( e)`node` 将不这样做: `-y` (作为自己的选择).

签名后,服务器会回答客户端的 `initialize` 并立即在背景中发现您的工作空间的工具,因此下载软件包和每个插件的运行不会绊倒客户端的握手超时. (一个例外是代理商的第一个无密钥运行:服务器持有客户端的 `initialize` 在您通过浏览器签名时, 因此在您拿到证书之前, 任何信息都不会被解答 —— 证书会在之后被缓存, 而以后的每一个开始都是立即的 。 ) `tools/list` 等待发现, 然后正常地回答; 如果失败, 失败会作为工具到达 `hexis_unavailable` 他们的描述说明了原因,在标准上——这个过程没有消失,反而没有消失.

**工具盘跟踪工作空间 .** 工作空间默认分支上添加、 更改或去除的技能, 位于此服务器的下一个 `prompts/list` ——每个请求都从工作空间读取提示. 当连接是下一个USED时,一个工具手册会添加,修改或移除到这个服务器而无需重启:每当一个工具呼叫完成或客户端列出工具时,服务器会将工作空间的目录指纹与它注册的指纹进行比较——最多每两秒钟一次,无论连接多么繁忙,所以一个突起的呼叫需要一个小读. 在使用中,将变化放在承诺的十秒内——除非一个工具呼叫仍在运行中,只要该呼叫运行,它就保持新鲜度,限制在15秒之内(下面的第一个提示)。 上市检查并等待它,所以你得到的绝不是名单的更新;在两秒钟的窗口里,从最后确认的支票中,而不是从新的读数中——在这十秒钟中,只有两秒钟是这个窗口. 在接到电话后,一旦接到电话,变化就会降落,所以从那个电话之后的电话中可以调用一个新的工具。 虽然连接是IDLE,服务器只询问工作空间的目录,除了它通过一个MCP会话为工具服务之外,它没有打开任何内容——没有目录计时器,也没有停放请求——因此,一个无人使用的笔记本电脑只花费工作空间的连接费用,它在下次使用时赶上。 (浏览器签名的服务器在自己的时钟上所做的一件事,就是在过期前不久更新自己的登录——每几个小时一次请求,与目录无关. 当目录移动时,服务器会重新登记工作空间的工具 **及其仅本地服务器** (单位:千美元)`local: true`,或一个 `type: "stdio"` 命令 ——这些被再次带入磁盘,其子进程被重新注册重新启动,然后发送MCP工具列表更改和快速列表更改通知。 履行这些通知的客户端自行重新列出;缓存在连接时给出的列表的客户端必须被要求重新列出,或者重新连接. 有两个警告:一个更新的等待工具呼叫,在重新登记之前仍在运行,但只有15秒钟——一个在等待完成之后的中调区域被改变,一个超过等待时间的呼叫却在等待下进行,这是刻意的:一个楔形的呼叫在它在乎运行的时间内,决不能把工具被拖住;一个比这个包年长的工作空间根本不能够报告它的目录,服务器在保留它开始使用的工具之前,曾经在stderr上说过这个目录.

## 签名于

两条路进去, 以及你是否通过一个关键:

**无密钥( 默认)** ——命令打开了您的浏览器以登录到工作空间,同样在Web UI中使用的标志. 签入属于运行服务器的代理: 它从 MCP 的握手和工作空间注册到哪个, 比如“ Claude Code ” —— 本地服务器, 这就是它出现在工作空间的审核日志页上的方式, 以及您取消的。 机器标志上的每个代理人 一次,作为本身; 证书 保持它签在土地上 `~/.hexis/oauth/`,只有您可以读取,所以以后会跳过浏览器。 在一台没有显示的机器上, `--no-open` (或 `HEXIS_NO_BROWSER=1`)打印登录的URL,而不是打开任何东西——从任何浏览器中跟踪. 浏览器的登录需要至少和这个软件包一样新的部署;针对一个命令说的更老的,一个连接键仍然在那里工作.

**用钥匙** —— 说 `--key bevel_…` (或 `HEXIS_CONNECTION_KEY`)跳过浏览器完全:CI,管道的正确模式,以及任何无人在场的签名地点. 配置菜单上的薄荷一 ~ **外部代理访问**。 。 。 .

无论哪种方式,证书认证 _这一进程_ 且没有其他任何变化: 工具仍然执行他们总是执行的地方, 工作空间的"秘诀"在服务器上保留.

## 克劳德密码

```json
{
  "mcpServers": {
    "hexis": {
      "command": "npx",
      "args": ["-y", "@bevel-software/hexis-mcp"],
      "env": {
        "HEXIS_URL": "https://your-workspace.example",
        "HEXIS_CONNECTION_KEY": "bevel_…"
      }
    }
  }
}
```

离开 `HEXIS_CONNECTION_KEY` 出局后,第一个启动时打开浏览器进行签名;在此之后,存储的登录将包含每个启动.

## 你得到的东西

主机端点所服务的一切——知识库工具,您的插件 `.tool` 融合, 和你作为斜线命令的技能—— **加号** 只有本地的工具. `call_tool_chain` 这里运行到合并的集, 所以一个脚本可以从工作空间读取一个页面, 并将其交给一个运行在笔记本上的工具 .

## 全权证书来自何处

这是值得理解的部分,因为它决定了哪些工具有效.

一个UTCP工具的 `${VAR}` 占位符为 **以客户端所持有的程序为准**。这个服务器将部署的 MCP 端点登记为单一的手册,所以每个远程工具仍然 _在服务器上执行_ 并不断从那里的秘密地窖中解析其变量. 共享的 API 密钥, 管理器设置一次, 或者在连接页面上完成的某个名词签名, 仍然和今天一样工作 。 没有东西能把那些值拉入你的机器.

只有本地化的工具是例外的,必然的:它们运行在这里,所以它们的变量也必须在这里. 解决了问题 **相同的密钥**,通过一条故意狭窄的路线, 这是值得知道的边界:

-   **请求为手册命名, 绝不是变量 .** 此进程要求工作空间解决 _什麽 `mytool` 声明_; 工作空间重读 `.tool` 文档和答案中完全包含这些变量。 知识基础是允许列表,而这个过程发送的任何东西都无法扩大它.
-   **仅 `remote: false` 手册在这里解决.** 远程工具的证书被使用在服务器上,并被这个路线拒绝——把它们移到笔记本电脑上将会比他们解锁的工具更广阔的曝光.
-   **价值永远不归还给代理人.** 它们被取而代之为工具引用,不再进一步。 代理电话 `git.push(...)`从来没有看到 使推力起作用的标志.
-   **浏览器会话无法使用此路由 .** 它回答机器的证书这个过程所持有的——一个连接键,或者内部的符号一个浏览器的登录交换——并直接拒绝一个Web-UI会话. 网页 UI 中签名的用户获得只写的秘密页面 。 因此,运行这个命令的两种方式都能够解决一个本地工具的变量;既不让一个人读回一个.

所以:像其他工具一样,在工作空间的秘密页面上设置本地工具的变量. 每台机器上都不用装什么.

环境仍然是以旧方式提供工具的后盾。 将值放入 `env` 块,用于启动命令的 MCP 客户端配置, 以 UTCP 命名空间名称命名 `id` 从 `.tool` 文件,一个下划线,然后是变量。 UTCP先将 id 进行消毒: 每一个不是字母、数字或下划线的字符都变成 `_`,然后每个 `_` 实值 **双倍**这样 `mytool` + 键 `API_KEY` → `mytool_API_KEY`时 `my-tool` 或者说 `my_tool` + 键 `API_KEY` 都变成 `my__tool_API_KEY`. (两份手册,其编号仅因 `-` 对 `_` 因此共享一个命名空间;工作空间拒绝第二个,这个进程拒绝解决两个问题。 )

## 选项

| 旗帜 | 环境 | 含义 |
| --- | --- | --- |
| `-u, --url` | `HEXIS_URL` | 工作空间基础 URL |
| `-k, --key` | `HEXIS_CONNECTION_KEY` | 外部代理访问中的连接密钥; 省略通过浏览器签名 |
| `--no-open` | `HEXIS_NO_BROWSER` | 打印登录的 URL 而不是打开浏览器 |
| `-h, --help` |  | 使用量 |

MCP端点本身不是一个设置:服务器为此询问部署(`/api/config`),所以一个代理或第二个域后的工作空间会被处理,而不需要你两次配置任何东西. 不发布广告的旧部署会回到 `<url>/api/mcp`上面写着警告.

## 解决问题

诊断到 **标准** (stdout带有协议),而MCP客户端将其表面显示为服务器日志.

-   **客户说 `npx` (或 `ENOENT`(未找到)** ——客户端是从 Dock, Start 菜单或桌面图标推出的,所以它是由窗口服务器而不是登录 shell 启动的,并且从未读取过将 Homebrew 或 nvm 的配置文件 `npx` 在路径。 在macOS上的Cursor和Claude桌面是常见的对. 运行 `which npx` 在终端中( e)`where.exe npx` 在PowerShell中),并使用它打印的完整路径作为 `"command"` (在Windows上,每回斜线翻倍或使用前斜线——字段为JSON) `args` 保持原样 如果客户报到 `env: node: No such file or directory`,那个 `npx` 是一个从 `#!/usr/bin/env node` 而同样的路径漏洞 现在隐藏 `node` —— 将路径名称添加到客户端的文件夹 `"env"`,保留后面的系统文件夹,因为第一个运行的登录打开了您的浏览器: `{ "PATH": "/that/folder:/usr/local/bin:/usr/bin:/bin" }`.(从终端启动的客户端工程中运行相同的配置,这让这个配置看起来像一个破解的配置而不是缺失的 PATH
-   _"Hexis-mcp运行在节点22.13+或24"_ - 这一过程在其他版本上(夜间或 `rc` 一个支持的计数作为另一个版本:一个尚未结算的ABI没有发布二进制。 沙盒是一个原生模块,没有预建的二进制,在你的机器上建造它将会是一个 C++ 编译. `nvm install 22`,或设置 `"command"` 到一个支持的版本 `npx` ——一个GUI启动的客户端无法通过终端中的切换版本来固定,因为它从未读取过该 shell.
-   _"hexis -mcp 无法装入其本土的沙盒"_ ——节点主被支持,但二进制不会加载:通常是一个在机器或架构之间被复制的安装. 莱因斯图尔( Rinstall)`npx -y` ,或删除 `node_modules` 在运行它的机器上.
-   **唯一列出的工具是 `hexis_unavailable`** ——在握手后发现失败;其描述带有理由,同样句子也在服务器的stderr日志中. 服务器是故意保持连接的,所以你得到的原因 而不是客户端报告它死了。 修正因并重开.
-   _"连接密钥被拒绝"_ —— 密钥无效或被撤销, 或者属于另一个工作空间 。 薄荷在外部代理访问。 进程退出而不是提供浏览器的登录 。 Claude Code只显示服务器失败; `claude mcp get <name>` 在终端中运行命令或显示消息.
-   _"你的签注被拒绝"_ 编号 : _"无法被刷新"_ ——工作区撤销登录,否则失效. 重新启动通过浏览器再次签名的命令 .
-   _"这个部署对于浏览器的登录来说太老了"_ ——工作空间早于签入交换. 升级, 或传递连接密钥 .
-   **列表中缺少本地工具** 它注册了,但是失败了;日志名称和原因。 本地服务器未运行的工具是通常的原因 .
-   **列出一个本地工具, 但它的电话无法使用** ——它的变量没有被设定在工作空间的"秘密"页面上,在这个过程中的环境也没有. 变量返回的日志名称未设置 。 如果您正在使用环境倒置,请注意名称空格前缀,与 `-`编号 :`_` 在工具 id 成为 `__`。 。 。 .
-   **日志上说有两本手册共享一个命名空间,或者有嵌入的** ——在重新命名(共享)之前,既不能解决,也不能解决较短手册中的一个变量,其名称以 `_` 避免(已取消).
-   **一个工具完全丢失** ——工作区隐藏工具,您尚未在密钥认证会话上设置过其用户证书。 在工作空间的连接页面上配置它 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @bevel-software/hexis-mcp 是什么？

运行一个Hexis工作空间作为本地的MCP服务器:主机端点所服务的每一个工具,加上它无法到达的本地唯一的工具\.

### 如何安装 @bevel-software/hexis-mcp？

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

### @bevel-software/hexis-mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bevel-software/hexis-mcp 支持 ESM 还是 CommonJS？

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

### @bevel-software/hexis-mcp 需要什么版本的 Node\.js？

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

### @bevel-software/hexis-mcp 可以商用吗？

@bevel-software/hexis-mcp 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @bevel-software/hexis-mcp 的下载量有多少？

根据 npm 官方下载统计，@bevel-software/hexis-mcp 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,721 次，日均约 91 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bevel-software/hexis-mcp 还在维护吗？

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