KIP MCP Server

kip-mcp-server

一个 MCP 服务，让 AI 助手（例如 Claude、Codex 或 Gemini）查看船只的 Signal K 数据，并帮助你设计和安装 KIP 仪表板——即你在海图仪或平板电脑上看到的仪表和面板。

由你掌控：助手会先展示每个仪表板的图片，只有在你同意后才会将内容保存到船只上。

它能做什么

• 查看船只数据。 查找船只通过 Signal K 报告的数值——速度、风力、水深、电池、发动机等。
• 推荐仪表板。 除了通用仪表板，还会针对特定用途提出建议：帆船航行、机动航行、电力、锚泊、导航和天气。
• 提供预览。 在保存任何内容之前，你可以先查看每个仪表板的简易图片。
• 安装仪表板——经你确认。 它会将仪表板写入你的 KIP 配置，或者提供一个可由你自行导入的文件。

效果展示

将 AI 助手连接到船只后的一段简短对话：

You:  Look at my boat's data and suggest some KIP dashboards.

  → analyze_signalk_data            142 paths · speed, wind, depth, battery, engine
  → recommend_dashboard_set         6 dashboards the data supports

Assistant: Your boat reports navigation, wind, depth, electrical and engine data,
so I can build these. Here's the "Sailing" one — a preview, nothing saved yet:

  ┌─────────────┬─────────────┬───────────────────────────┐
  │ SOG  6.2 kn │ AWS 14 kn   │                           │
  ├─────────────┼─────────────┤        wind steering       │
  │ DPT  8.4 m  │ AWA  42°    │                           │
  └─────────────┴─────────────┴───────────────────────────┘

You:  Looks good — install the sailing and anchor ones.

  → apply_kip_config (dry run)      2 dashboards → KipConfig (global)
Assistant: This will add "Sailing" and "Anchor" to KIP. Go ahead?
You:  Yes.
  → apply_kip_config                written ✓  — open KIP to see them.

助手总会先显示预览，并在写入任何内容前征求你的同意。

快速开始（船主适用）

你需要在船上（或网络中）运行 Signal K 服务，并安装 KIP。

1. 找到 Signal K 地址。 地址通常类似于 http://your-boat:3000。记下主机名（或 IP）和端口。
2. 获取此服务。 无需手动安装任何内容——AI 助手可以通过 npx 按需运行它（npx 随 Node.js 24 或更高版本提供）：

   npx -y kip-mcp-server
   

   下一步会将此命令配置到你的助手中。（想从源代码构建？请参阅下文的开发。）
3. 连接到 AI 助手。 在 docs/clients 中选择你的助手，并按照其中的简短说明进行设置。你需要告诉助手船只的主机名和端口。
4. 请它帮忙。 可以这样说：“查看船只的数据，并推荐一些 KIP 仪表板。” 查看它提供的预览。
5. 确认。 满意后，告诉它继续。它会在写入任何内容前征求你的同意。如果你的 Signal K 服务版本较旧，它会提供一个 KipConfig.json 文件，供你从 KIP 的 Settings 中导入。

如何连接

此服务会从环境中读取一些设置：

设置	说明	默认值
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 身份验证。

通过 HTTP 远程访问（可选，高级功能）

默认情况下，服务通过 stdio 通信——助手会将其作为本地子进程运行。 还可以选择使用 HTTP 模式（kip-mcp-http）来托管服务，让远程 助手（例如 Claude.ai）通过网络连接。此模式需显式启用，适用于通过添加 TLS 的反向代理 保护的单人操作场景。

# Behind a TLS-terminating reverse proxy that forwards to 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，用于 Host 允许列表和元数据	（自动生成）
MCP_ALLOWED_ORIGINS	要接受的浏览器来源（以逗号分隔，默认关闭）	（无）
MCP_ALLOWED_HOSTS	覆盖 Host 允许列表	（自动生成）
MCP_ALLOW_INSECURE	设置为 true，即可在不安全的配置下仍然启动	（未设置）

每个请求都必须提供有效的 Authorization: Bearer <token>，并通过 Host/Origin 允许列表检查，之后才能到达 MCP 层。除非设置 MCP_ALLOW_INSECURE=true，否则如果服务要绑定到非环回地址或在没有 Bearer 令牌的情况下运行，服务将拒绝启动。所有会话共用一个 Signal K 登录，因此应将其视为 单租户部署；上述相同的 SIGNALK_* 设置仍然适用。

助手可以做什么

服务会向助手提供一组工具，并按用途分组：

• 查看船只信息 — 列出数据路径、对应单位以及已安装的插件。
• 了解 KIP 的组件 — 列出所有 KIP 小部件及其配置方式，以及 KIP 支持的颜色、 图标和单位。
• 设计仪表板 — 推荐一组仪表板，为指定用途构建仪表板，并绘制预览。
• 检查用户体验 — 从海事可用性角度评估仪表板（层级、分组、 一致性、标签），并标记问题严重程度；review_dashboard 提示词会引导该流程， 并由确定性的 check_dashboard_ux lint 提供支持。
• 检查并保存 — 检查仪表板格式是否正确，将其导出到文件，或写入 船只（会先征求确认）。

更多帮助

• 配方 — 助手设计仪表板的示例。
• 故障排除 — 常见问题的解决方法，首先可运行内置的 --doctor 检查。
• 工具参考 — 助手可使用的所有工具和提示词。

术语表

下面用通俗语言解释几个术语：

• Signal K — 许多船只用于通过 网络共享数据（速度、风、深度……）的开放系统。
• path — 一项数据的名称，例如 navigation.speedOverGround（对地速度）。
• KIP — 将船只数据以仪表盘形式显示的应用，其中包含仪表和面板。
• 小部件 — 仪表盘上的一个仪表或面板（数字、表盘、风况显示……）。
• 仪表盘 — 排列在网格上的一屏小部件。
• 令牌 — 类似软件密码的凭据，可让服务保存对船只所做的更改。
• 试运行 — 助手会告诉你它将会做什么，但不会实际执行。默认情况下，保存操作是试运行。

开发

本项目使用 Node.js 24（LTS）。常用命令：

npm install        # install dependencies
npm run typecheck  # check types
npm run lint       # check code style
npm test           # run the tests
npm run build      # compile to dist/
npm run smoke      # start the built server and check it answers
npm run ci         # run the full set of checks

如需了解在本地开发过程中运行和测试服务的完整指南——将 AI 客户端或 MCP Inspector 指向本地构建版本、运行 HTTP 传输，以及针对 Signal K（或离线）进行测试——请参阅 docs/development.md。

提交遵循 Conventional Commits 规范；发布和版本号会根据提交消息自动生成。

许可证

MIT — 详见 LICENSE。