AI导哈

协作图节点管理服务

Nodl MCP是一个允许AI客户端通过公共端点与Nodl协作项目交互的服务，提供图节点和连接的管理工具。

  • by nodldevstudio-hub
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 nodldevstudio-hub/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)
  3. 呼叫 list_capabilities 确认角色/范围/到期。
  4. 使用专用工具进行常见的图形操作(add_node, move_node, connect_nodes, ...).

端点覆盖 .env （生产）

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

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

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

工具合同

join_project

输入：

{
  "token": "<short-lived-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": "<short-lived-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 禁用启动日志。

相关 MCP