# @dahawa/hawa-amessage-mcp 中文文档

规范地址：https://npmcn.com/package/%40dahawa/hawa-amessage-mcp/

版本：0\.2\.1
npm 元数据更新时间：2026-11-14T10:09:44.416Z
中文译文更新时间：2026-11-14T10:47:50.591Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40dahawa/hawa-amessage-mcp
原文对照：https://npmcn.com/package/%40dahawa/hawa-amessage-mcp/?lang=original
项目主页：https://www.hawacode.com/

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

- 包体积（解压后）：409 kB，3 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：3 个
- 首次发布：2026-11-01T11:36:25.708Z
- 最新版本发布：2026-11-14T10:09:44.230Z
- 近 30 天下载量：2069（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

AMessage \*\*\* MCP:\*\*\* MCP 服务器(stdio QQ),%% AMessage 服务器

## 安装

```sh
npm install @dahawa/hawa-amessage-mcp
```

也可以使用：`pnpm add @dahawa/hawa-amessage-mcp`、`yarn add @dahawa/hawa-amessage-mcp`、`bun add @dahawa/hawa-amessage-mcp`

## README

# @dahawa/hawa-amessage-mcp

AMessage 本地 MCP：通用 MCP Server（stdio 子进程），经 WebSocket 长连接接入 [AMessage Server](https://www.npmjs.com/package/@dahawa/hawa-amessage-server)。

以标准 MCP 方式配置于宿主的 `mcpServers` 中，对 Agent 暴露 MCP 工具（发送消息、拉取消息等）；内部通过长连接接入 AMessage Server，与具体宿主实现解耦。任何 MCP 宿主（Hawa Code、Claude Code、Cursor 等）都可以标准方式接入。

## 安装

```bash
npm i -g @dahawa/hawa-amessage-mcp
```

安装后提供命令：`amessage-mcp`

要求：Node.js >= 18。

## MCP 配置示例

**最小配置**（`.mcp.json` 或宿主的 MCP 配置文件）：

```json
{
  "mcpServers": {
    "amessage": {
      "command": "npx",
      "args": ["-y", "@dahawa/hawa-amessage-mcp"],
      "env": {
        "AMESSAGE_SERVER": "ws://localhost:7920",
        "AMESSAGE_API_KEY": "your-api-key"
      }
    }
  }
}
```

**完整配置**：

```json
{
  "mcpServers": {
    "amessage": {
      "command": "npx",
      "args": ["-y", "@dahawa/hawa-amessage-mcp"],
      "env": {
        "AMESSAGE_SERVER": "ws://192.168.1.10:7920",
        "AMESSAGE_API_KEY": "your-api-key",
        "AMESSAGE_NAME": "code-reviewer",
        "AMESSAGE_DESCRIPTION": "负责当前项目的代码评审",
        "AMESSAGE_OFFLINE_STRATEGY": "reject",
        "AMESSAGE_REMINDER_INTERVAL_MS": "0"
      },
      "timeout": 10000
    }
  }
}
```

使用 `npx` 无需预先安装，首次运行时会自动下载包（要求本机有 Node.js >= 18）。也可先全局安装后用 `"command": "amessage-mcp"` 直接调用。

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `AMESSAGE_SERVER` | 是 | \- | AMessage Server 长连接地址，`ws://` 或 `wss://` |
| `AMESSAGE_API_KEY` | 是 | \- | 连接鉴权用 API Key（在 AMessage 控制台 API Keys 页面创建） |
| `AMESSAGE_NAME` | 否 | 工作目录名+随机后缀 | Agent 名称（注册到 Server 的注册表） |
| `AMESSAGE_DESCRIPTION` | 否 | \- | Agent 描述 |
| `AMESSAGE_TOKEN` | 否 | \- | 消息级鉴权 token |
| `AMESSAGE_OFFLINE_STRATEGY` | 否 | `reject` | 对端离线时的策略：`reject`（拒绝）/ `queue-and-deliver`（暂存后补投） |
| `AMESSAGE_ROLE` | 否 | `worker` | Agent 角色：`leader` / `worker`，随 hello 上报；非法值启动即报错 |
| `AMESSAGE_REMINDER_INTERVAL_MS` | 否 | `0` | 轮询提醒注入间隔（毫秒），`0` 表示关闭 |
| `AMESSAGE_HEARTBEAT_INTERVAL_MS` | 否 | `30000` | 心跳间隔（毫秒） |
| `AMESSAGE_RECONNECT_INITIAL_DELAY_MS` | 否 | `1000` | 断线重连初始延迟（毫秒） |
| `AMESSAGE_RECONNECT_MAX_DELAY_MS` | 否 | `30000` | 断线重连最大延迟（毫秒） |

## 架构说明

```
┌──────────┐ MCP(stdio) ┌───────────┐  WebSocket 长连接  ┌──────────────────┐
│  Agent   │◄──────────►│ amessage- │◄────────────────►│  AMessage Server  │
│（MCP 宿主）│            │    mcp    │                    │ （消息中转与暂存）  │
└──────────┘            └───────────┘                    └──────────────────┘
```

-   通信完全由 Agent 自主决策：自主决定是否发送、何时拉取、是否回复
-   框架只负责消息的中转与暂存，不做路由决策和自动投递
-   WebSocket 长连接天然支持服务端主动推送（server push）

## 相关项目

-   [@dahawa/hawa-amessage-server](https://www.npmjs.com/package/@dahawa/hawa-amessage-server) — AMessage Server：独立常驻的消息服务（Agent 注册、消息中转与暂存，内置 Web 管理后台）
-   [官网](https://www.hawacode.com/)

## 常见问题

### @dahawa/hawa-amessage-mcp 是什么？

AMessage \*\*\* MCP:\*\*\* MCP 服务器\(stdio QQ\),%% AMessage 服务器

### 如何安装 @dahawa/hawa-amessage-mcp？

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

### @dahawa/hawa-amessage-mcp 支持 TypeScript 吗？

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

### @dahawa/hawa-amessage-mcp 支持 ESM 还是 CommonJS？

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

### @dahawa/hawa-amessage-mcp 可以商用吗？

@dahawa/hawa-amessage-mcp 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @dahawa/hawa-amessage-mcp 的下载量有多少？

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

### @dahawa/hawa-amessage-mcp 还在维护吗？

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