Nodl MCP Public

Nodl MCP

MCP服务器允许AI客户端通过公共端点与Nodl协作进行交互。

此服务器不包含应用程序机密。它只适用于用户提供的短期协作令牌。

这个MCP做什么

• 连接到Nodl协作项目室。
• 显示图变异工具。
• 尊重后端授权（角色+范围）。

可用工具：

• join_project
• list_capabilities
• list_nodes
• list_current_nodes
• describe_current_nodes
• add_node
• remove_node
• move_node
• edit_node_properties
• describe_node_properties
• connect_nodes
• disconnect_nodes
• move_cursor

在MCP客户端中安装（JSON配置）

使用 npx 所以用户不需要克隆任何东西。 支持私有注册表和作用域包名称（例如 @your-scope/nodl-collab-mcp).

{
  "mcpServers": {
    "nodl": {
      "command": "npx",
      "args": ["-y", "nodl-collab-mcp"]
    }
  }
}

笔记：

• 编辑配置后重新启动MCP客户端。
• 配置中没有存储令牌。

首次使用流程

1. 在Nodl应用程序中生成MCP代理令牌(Share -> Collaborate -> MCP token).
2. 在您的AI客户端中，调用 join_project:

- token：短期令牌 - endpoint （可选）：设置为您的生产后端协作命名空间（示例： wss://api.nodl.dev/collaboration)

1. 呼叫 list_capabilities 确认角色/范围/到期。
2. 使用专用工具进行常见的图形操作(add_node, move_node, connect_nodes, ...).

端点覆盖 .env （生产）

创建本地 .env 包根目录下的文件（未提交）：

NODL_COLLAB_ENDPOINT=wss://api.nodl.dev/collaboration

启动时会自动加载此覆盖(dotenv/config). 将此端点设置为统一后端Socket。IO命名空间URL。

工具合同

join_project

输入：

{
  "token": "",
  "endpoint": "wss://api.nodl.dev/collaboration",
  "displayName": "MCP - Claude"
}

输出：

• endpointUsed （MCP使用的有效Socket.IO端点）
• session (projectId, mode, role, snapshotSummary)
• 解码令牌元数据(scopes, exp)
• 游标标识元数据(actorId, displayName)被使用 move_cursor
• 默认情况下省略完整快照（设置 includeSnapshot: true 包括它）
• 如果令牌过期或令牌没有，则会快速失败 projectId 声称
• ACK处理同时支持Socket。避免错误的IO回调形状 join timeout or rejection 错误。

list_capabilities

输入：

{
  "token": ""
}

输出：

• 角色
• 范围
• 过期状态

list_nodes

输入：

{}

输出：

• 来自的本地节点目录 assets/node-metadata.json （类型、类别、端口、属性）

list_current_nodes

输入：

{}

输出：

• 轻量级会话范围摘要，包括：

- initialized - sessionScoped: true - lastUpdatedAt - counts (nodes, connections) - nodeIdsPreview - connectionIdsPreview

可选输入：

• includeFullState: true 包括完整 nodes 和 connections
• previewLimit 在摘要模式下调整预览大小（默认20，最大200）

describe_current_nodes

输入：

{
  "nodeIds": ["noise-1", "edge-1"],
  "includeRaw": false
}

输出：

• 仅针对请求的ID进行目标节点诊断：

- nodeType 和回退 type - 可用对象 keys - x / y - propertyKeys

• 在以下情况下使用此 connect_nodes 抱怨失踪 nodeType/type 领域。

语义：

• 该状态仅限于活动MCP进程/会话，
• 它从空开始 join_project （不获取历史快照），
• 更新时间：

- 成功的局部突变ACK， - 传入的 collaboration:mutation 其他演员的事件。

专用图形工具

• add_node：已验证包装 addNode
• remove_node：已验证包装 deleteNode
• move_node：已验证包装 moveNode
• edit_node_properties：已验证包装 updateNodeProperties
• describe_node_properties：返回节点的允许属性架构和当前值

- 重要提示：此工具返回运行时属性 key 应与一起使用的值（稳定、未翻译） edit_node_properties.

• connect_nodes：已验证包装 addConnection
• disconnect_nodes：已验证包装 deleteConnection
• move_cursor：发出协作光标更新

类型兼容性开启 connect_nodes

connect_nodes 验证源输出和目标输入与本地节点目录的兼容性：

• 它解析当前节点类型 list_current_nodes 国家，
• 从解析端口定义 list_nodes 目录，
• 当输出/输入端口类型不兼容时，拒绝调用。

安全属性编辑流程

打电话之前 edit_node_properties，呼叫 describe_node_properties:

• 解析精确节点类型的允许属性名称，
• 检查预期值类型(number, boolean, select等等），
• 允许检查 select 选项和数值边界，
• 检查当前值/模式以避免无效更新。

安全模型

• 令牌仅在MCP进程生命周期内保存在内存中。
• 此包从不持久化令牌。
• 令牌解析错误被掩盖（错误中不发出明文令牌）。
• 后端是访问控制的权威。
• 过期/无效的令牌被后端拒绝。

故障排除

所有工具错误都包括内联错误 Mitigation: 提示以指导后续步骤（令牌刷新、websocket模式不匹配、缺少作用域、模式修复、目标节点检查等）。

身份验证错误(ENEEDAUTH, E404 scope not found)在npm发布期间

这是CI/CD包发布配置，而不是MCP运行时使用情况。

• 运行时用户只需要：

- npx nodl-collab-mcp - 有效的Nodl协作令牌

join_project 失败

检查：

• 令牌未过期
• 端点正确(endpoint 那么，论点具有优先权 NODL_COLLAB_ENDPOINT/COLLAB_SECURE_WS_URL)
• 角色/范围允许请求的操作

本地开发

npm install
npm run build
npm start

直接运行时(npx -y nodl-collab-mcp)，服务器仍在等待stdio。 这是意料之中的。启动日志打印到 stderr. 集 NODL_MCP_SILENT=true 禁用启动日志。