内容
# kip-mcp-server
[](https://github.com/dillan/kip-mcp-server/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/kip-mcp-server)
[](https://www.npmjs.com/package/kip-mcp-server)
[](./LICENSE)
[](https://www.npmjs.com/package/kip-mcp-server)
一个 [MCP](https://modelcontextprotocol.io) 服务器，允许 AI 助手（如 Claude、Codex 或 Gemini）查看您的船的 [Signal K](https://signalk.org) 数据，并帮助您设计和安装 [KIP](https://github.com/mxtommy/Kip) 仪表盘 —— 您在航海图仪或平板电脑上看到的仪表和面板。
您始终保持控制：助手首先向您展示每个仪表盘的预览，只有在您确认后才会保存任何内容到您的船上。
## 功能
- **查看船的数据。** 它查找船通过 Signal K 报告的值 —— 速度、风、深度、电池、发动机等。
- **建议仪表盘。** 它提出一个通用仪表盘和特定任务的仪表盘：航行、机动、电力、锚泊、导航和天气。
- **显示预览。** 您在保存任何内容之前看到每个仪表盘的简单预览。
- **安装它们 —— 经您同意。** 它将仪表盘写入您的 KIP 设置，或为您提供一个您可以自己导入的文件。
## 界面
与 AI 助手进行短暂会话后，指向您的船：
```text
您：查看我的船的数据并建议一些 KIP 仪表盘。
→ analyze_signalk_data 142 路径 · 速度、风、深度、电池、发动机
→ recommend_dashboard_set 6 个仪表盘 数据支持
助手：您的船报告导航、风、深度、电气和发动机数据，因此我可以构建这些。以下是“航行”仪表盘 —— 预览，尚未保存：
┌─────────────┬─────────────┬───────────────────────────┐
│ SOG 6.2 kn │ AWS 14 kn │ │
├─────────────┼─────────────┤ 风向控制 │
│ DPT 8.4 m │ AWA 42° │ │
└─────────────┴─────────────┴───────────────────────────┘
您：看起来不错 —— 安装航行和锚泊仪表盘。
→ apply_kip_config （干预运行） 2 个仪表盘 → KipConfig （全局）
助手：这将添加“航行”和“锚泊”到 KIP。继续吗？
您：是的。
→ apply_kip_config 已写入 ✓ — 打开 KIP 查看它们。
```
助手始终显示预览并在写入任何内容到您的船之前询问。
## 快速入门（适用于船主）
您需要在船上（或在您的网络上）运行一个 [Signal K](https://signalk.org) 服务器，并安装 KIP。
1. **找到您的 Signal K 地址。** 它通常类似于 `http://your-boat:3000`。注意主机名（或 IP）和端口。
2. **获取此服务器。** 您不需要手动安装任何内容 —— 您的 AI 助手可以使用 [`npx`](https://docs.npmjs.com/cli/commands/npx)（随 [Node.js](https://nodejs.org) 24 或更高版本附带）按需运行它：
```bash
npx -y kip-mcp-server
```
下一步是将此命令连接到您的助手。（更喜欢从源代码构建？请参见下面的[开发](#develop)部分。）
3. **将其连接到您的 AI 助手。** 在 [docs/clients](./docs/clients/) 中选择您的助手并按照简短的设置说明进行操作。您告诉助手您的船的主机名和端口。
4. **请求帮助。** 说些类似的话 *"查看我的船的数据并建议一些 KIP 仪表盘。"* 审查它显示的预览。
5. **确认。** 当您满意时，告诉它继续。它在写入任何内容之前都会询问。如果您的 Signal K 服务器较旧，它会为您提供一个 `KipConfig.json` 文件，以便您从 KIP 的设置中导入。
## 连接方式
服务器从其环境中读取几个设置：
| 设置 | 描述 | 默认值 |
| --- | --- | --- |
| `SIGNALK_HOST` | 您的 Signal K 主机名或 IP | `localhost` |
| `SIGNALK_PORT` | 您的 Signal K 端口 | `3000` |
| `SIGNALK_TLS` | 如果您的服务器使用 `https`，请设置为 `true` | `false` |
| `SIGNALK_TOKEN` | Signal K 登录令牌，需要 **写入** 仪表盘 | （无） |
| `SIGNALK_USER` | Signal K 用户名 —— 与 `SIGNALK_PASSWORD` 结合使用，而不是令牌 | （无） |
| `SIGNALK_PASSWORD` | 匹配的 Signal K 密码 | （无） |
| `KIP_URL` | 重定向 KIP 服务的位置（如果不是默认位置） | （派生） |
读取您的数据不需要登录。写入仪表盘到服务器需要令牌或用户名和密码；您始终可以使用文件导出选项，它不需要额外的内容。有关获取令牌（或为什么用户名/密码更简单），请参见 [Signal K 身份验证](./docs/signalk-auth.md)。
## 通过 HTTP 进行远程访问（可选，高级）
默认情况下，服务器通过 **stdio** 进行通信 —— 助手将其作为本地子进程运行。还有一个可选的 **HTTP** 模式（`kip-mcp-http`），允许远程助手（例如 Claude.ai）通过网络访问它。它是可选的，适用于具有反向代理的单个操作员，该代理添加 TLS。
```bash
# 在终止 TLS 的反向代理后面，转发到 127.0.0.1:3017
MCP_BEARER_TOKEN=a-long-random-secret \
MCP_PUBLIC_URL=https://boat.example.com/mcp \
npx kip-mcp-http
```
| 设置 | 描述 | 默认值 |
| --- | --- | --- |
| `HTTP_HOST` | 绑定地址 | `127.0.0.1` （环回） |
| `HTTP_PORT` | 监听端口 | `3017` |
| `HTTP_PATH` | MCP 端点的 URL 路径 | `/mcp` |
| `MCP_BEARER_TOKEN` | 调用者必须提供的 一个或多个（逗号分隔） bearer 令牌 | （无） |
| `MCP_PUBLIC_URL` | 客户端访问的公共 URL，用于主机允许列表和元数据 | （派生） |
| `MCP_ALLOWED_ORIGINS` | 接受的逗号分隔浏览器源（默认关闭） | （无） |
| `MCP_ALLOWED_HOSTS` | 重定向主机允许列表 | （派生） |
| `MCP_ALLOW_INSECURE` | 设置为 `true` 以在不安全的设置中启动 | （未设置） |
每个请求都必须提供有效的 `Authorization: Bearer <token>` 并通过主机/源允许列表，然后才能到达 MCP 层。**服务器拒绝启动** 如果它绑定到非环回地址或在没有 bearer 令牌的情况下运行，除非您设置 `MCP_ALLOW_INSECURE=true`。它为所有会话使用一个 Signal K 登录，因此将其视为单一租户部署；应用上述相同的 `SIGNALK_*` 设置。
## 助手可以执行的操作
服务器为助手提供了一组按任务分组的工具：
- **查看船只** — 列出数据路径、单位和已安装的插件。
- **了解 KIP 组件** — 列出每个 KIP 小部件及其配置，以及 KIP 理解的颜色、图标和单位。
- **设计仪表盘** — 建议一组仪表盘，构建一个特定任务的仪表盘，并绘制预览。
- **审查用户体验** — 使用严重性标记的发现评估仪表盘的海洋可用性（层次结构、分组、一致性、标签）；`review_dashboard` 提示驱动它，由确定性的 `check_dashboard_ux` 校验支持。
- **检查和保存** — 检查仪表盘是否格式正确，导出到文件，或写入船只（先询问）。
## 更多帮助
- **[食谱](./docs/recipes.md)** — 助手设计仪表盘的示例。
- **[故障排除](./docs/troubleshooting.md)** — 常见问题的解决方法，从内置的 `--doctor` 检查开始。
- **[工具参考](./docs/tools.md)** — 助手可以使用的每个工具和提示。
## 词汇表
几个术语，用通俗的话解释：
- **Signal K** — 许多船只用来通过网络共享数据（速度、风、深度等）的开放系统。
- **路径** — 一个数据项的名称，如 `navigation.speedOverGround` （地面速度）。
- **KIP** — 显示船只数据为仪表盘和面板的应用程序。
- **小部件** — 仪表盘上的单个仪表或面板（数字、表盘、风显示等）。
- **仪表盘** — 屏幕上的一组小部件，按网格排列。
- **令牌** — 类似于软件的密码：它允许服务器保存对船只的更改。
- **干预运行** — 助手告诉您它 *将* 执行的操作，而不实际执行。保存默认情况下是干预运行。
## 开发
该项目使用 Node.js 24（LTS）。常见命令：
```bash
npm install # 安装依赖项
npm run typecheck # 检查类型
npm run lint # 检查代码风格
npm test # 运行测试
npm run build # 编译到 dist/
npm run smoke # 启动构建的服务器并检查其响应
npm run ci # 运行完整的检查集
```
有关在开发过程中本地运行和测试服务器的完整指南 — 将 AI 客户端或 MCP 检查器指向本地构建，运行 HTTP 传输，并针对 Signal K（或离线）进行测试 — 请参见 [docs/development.md](./docs/development.md)。
提交记录遵循 [Conventional Commits](https://www.conventionalcommits.org/)；版本和版本号根据这些提交消息自动生成。
## 许可证
MIT — 请参见 [LICENSE](./LICENSE)。
