Kamai

kamai-mcp

Kamai 的 MCP 服务：为 Kamai 的施工蓝图项目、蓝图和工程量统计提供工具与 MCP Apps 小组件。它通过 Kamai 的 MCP API 运行，并验证由 Kamai OAuth 授权服务器颁发的访问令牌。它不保存任何 Kamai 机密信息。

工具

工具	功能
view_projects	交互式面板，展示用户的项目和蓝图
list_blueprints	按项目分组展示蓝图，包括蓝图 ID 和是否已就绪
view_blueprint	蓝图页面，并在蓝图上绘制工程量统计图形
view_takeoff	以可排序表格展示测量出的工程量
list_elements	按元素展示行（房间、墙壁、门、窗户、对象），并显示轮廓
list_folders	蓝图的图例文件夹
download_plan	生成已处理蓝图的 PDF，其中高亮显示检测到的元素，并提供临时下载链接
update_elements、move_elements、create_folder	重命名、更改颜色并重新归类元素；创建文件夹
set_opening_height	在墙面开口部分保存用户指定的高度或门窗标签
create_project、update_project	创建或重命名项目
list_jobs、get_job、cancel_job	查看项目的处理任务
view_upload	用于上传蓝图 PDF 的面板
ingest_blueprint_from_chat	导入附加在 ChatGPT 消息中的 PDF（仅限 ChatGPT）
open_kamai	在面板中打开 Kamai 应用

启用 KAMAI_QUERY_TOOLS=on 后（见下文）：

工具	功能
count_elements	按 Kamai 类别（门、窗户、墙壁、湿区等）统计数量和总数，并在数据库中分组、汇总
find_elements	查看单个元素的类型、文件夹、标签、开启方向和尺寸
calculate_wall_surface_area	计算房间墙壁的净面积（涂漆或抹灰面积）
render_table	显示表格面板，表格行高亮对应的平面图元素
set_scale	设置蓝图的绘图比例
set_rotation	旋转蓝图的显示方向（仅影响显示）

启用 KAMAI_HOST_PROBE 后（开发和调试环境默认开启，生产环境关闭；见下文）：

工具	功能
probe_host	诊断面板，用于测试此聊天可使用的小组件功能（WebGPU、WebGL2、workers、WebAssembly、GCS 瓦片主机），并将结果记录为 widget_probe 事件

list_blueprints 还接受 include_inventory（需提供 project_id），用于查看每个蓝图包含的内容。

list_projects、get_project、get_blueprint、request_blueprint_upload、finalize_blueprint_upload，以及启用查询工具后的 get_table_row_elements 和 get_element_outlines，还有启用探测功能后的 report_host_probe，都仅供应用调用：小组件可以调用这些工具，但不会向模型公开。

使用 API 密钥在本地运行

使用本地模式连接你自己的 Kamai 数据，是运行此服务最快的方法：宿主会启动服务，通过 stdio 与其通信，并使用 Kamai 的个人 API 密钥（可在 Kamai 应用的 API Keys 中获取）作为凭据，而非 OAuth。

bun install
bun run build:widgets
KAMAI_API_KEY=... MCP_API_BASE_URL=https://mcp-api.kamai.io bun run local

Claude Code：

claude mcp add --env KAMAI_API_KEY=... --env MCP_API_BASE_URL=https://mcp-api.kamai.io \
  --transport stdio kamai -- bun /path/to/kamai-mcp/src/local.ts

Claude Desktop（claude_desktop_config.json）：

{ "mcpServers": { "kamai": {
    "command": "bun", "args": ["/path/to/kamai-mcp/src/local.ts"],
    "env": { "KAMAI_API_KEY": "...", "MCP_API_BASE_URL": "https://mcp-api.kamai.io" } } } }

每次 API 调用都会使用此密钥作为 bearer 凭据；工具以密钥所有者的身份运行。 在环境变量中添加 KAMAI_QUERY_TOOLS=on 以启用查询工具。

运行 HTTP 服务

bun install
cp .env.example .env
bun run dev

.env.example 中的值是占位符：启动前，请将 MCP_PUBLIC_URL 和 MCP_AUTH_ISSUER 设置为你的隧道地址和可访问的授权服务器，否则所有请求都会因 invalid_token 被拒绝。

变量	含义
PORT	监听端口，默认为 8006
MCP_PUBLIC_URL	主机调用并请求令牌的 URL（发现机制中的 resource）；应为隧道地址，而非 localhost
MCP_AUTH_ISSUER	访问令牌的颁发者；必须与令牌的 iss 逐字节匹配
MCP_AUTH_JWKS_URI	可选。默认为 {MCP_AUTH_ISSUER}/jwks.json
MCP_API_BASE_URL	Kamai MCP API 基础 URL，https://mcp-api.kamai.io。访问令牌必须携带此受众
MCP_ACCEPTED_AUDIENCES	可选的逗号分隔受众列表，用于切换期间。默认为 MCP_API_BASE_URL
KAMAI_API_KEY	仅限本地模式：工具运行时使用的个人 API 密钥
KAMAI_APP_ORIGINS	可选的逗号分隔额外来源，open_kamai 可在其中嵌入；第一个来源将成为默认值
KAMAI_QUERY_TOOLS	设置为 on 可注册查询工具。仅当 API 层提供 /v1/vocabulary 时才可用（返回 401，而非 404）
KAMAI_ROTATION	设置为 off 可从查询工具中移除 set_rotation（默认开启；需要 API 层提供 PUT .../blueprints/{id}/rotation）
KAMAI_HOST_PROBE	设置为 on 或 off 可注册 probe_host 和 report_host_probe。未设置时，如果 Cloud Run 的 K_SERVICE 以 dev- 或 debug- 开头，则开启；否则关闭。本地模式下始终关闭
KAMAI_MCP_NO_INSTRUCTIONS	设置为 1 可不包含服务器指令，与 claude.ai 一样；用于评估

MCP API 和授权服务器由 Kamai 运营，因此端到端运行 HTTP 服务需要同时访问这两者。MCP 服务只有在真实主机上才能真正测试，而主机只能访问公开的 HTTPS URL，因此 HTTP 模式开发需要通过隧道运行，并将 MCP_PUBLIC_URL 指向隧道。

bun run dev 会先构建 widgets：服务器提供的是 dist/widgets/ 中构建后的 HTML，而非 React 源码，因此修改 src/widgets/app/ 下的内容后需要重新构建。

widgets 使用 React、TypeScript、Vite、Tailwind CSS、DaisyUI 和 Lucide。Vite 会为每个 widget 生成一个自包含的 HTML 资源，因此无需托管任何内容。

本地构建需要 Bun 1.3.3 和 Node.js 22.12 或更新版本。

目录结构

src/index.ts       HTTP 服务器、OAuth 受保护资源元数据、MCP 传输
src/local.ts       本地模式的 stdio 入口（个人 API 密钥）
src/auth.ts        Bearer 令牌验证（RFC 9728 挑战）
src/server.ts      工具和资源注册
src/api.ts         Kamai MCP API 客户端
src/elements.ts    list_elements 分页、筛选和结果预算
src/errors.ts      工具调用失败时显示给模型的文本
src/query/         查询工具：描述、词汇、筛选条件、预算、契约
src/widgets/       Widget 资源、CSP 元数据和 React widget 源码
scripts/           Widget 构建（转义 &，以便 Open WebUI 嵌入
                   widgets）；针对实时 API 的 check-routes 和 check-vocabulary
scripts/open-webui/
                   Open WebUI 辅助工具：一个 open_kamai 工具、显示模式
                   主机脚本、本地桥接演示

隐私与支持

• 隐私政策：https://kamai.io/privacy-policy
• 支持：https://kamai.io/support 或联系 [email protected]

贡献

参见 CONTRIBUTING.md。安全问题请发送至 SECURITY.md 中的联系地址，而非提交到问题跟踪器。

许可证

Apache-2.0。版权所有 2026 Kamai Enterprises LTD。

Kamai 名称和徽标是 Kamai Enterprises LTD 的商标，不受许可证覆盖。