Nodl MCP
MCP服务器允许AI客户端通过公共端点与Nodl协作进行交互。
此服务器不包含应用程序机密。它只适用于用户提供的短期协作令牌。
这个MCP做什么
- 连接到Nodl协作项目室。
- 显示图变异工具。
- 尊重后端授权(角色+范围)。
可用工具:
join_projectlist_capabilitieslist_nodeslist_current_nodesdescribe_current_nodesadd_noderemove_nodemove_nodeedit_node_propertiesdescribe_node_propertiesconnect_nodesdisconnect_nodesmove_cursor
在MCP客户端中安装(JSON配置)
使用 npx 所以用户不需要克隆任何东西。
支持私有注册表和作用域包名称(例如 @your-scope/nodl-collab-mcp).```json
{
"mcpServers": {
"nodl": {
"command": "npx",
"args": ["-y", "nodl-collab-mcp"]
}
}
}
笔记:
- 编辑配置后重新启动MCP客户端。
- 配置中没有存储令牌。
## 首次使用流程
1. 在Nodl应用程序中生成MCP代理令牌(`Share -> Collaborate -> MCP token`).
1. 在您的AI客户端中,调用 `join_project`:
- `token`:短期令牌
- `endpoint` (可选):设置为您的生产后端协作命名空间(示例: `wss://api.nodl.dev/collaboration`)
1. 呼叫 `list_capabilities` 确认角色/范围/到期。
1. 使用专用工具进行常见的图形操作(`add_node`, `move_node`, `connect_nodes`, ...).
## 端点覆盖 `.env` (生产)
创建本地 `.env` 包根目录下的文件(未提交):```env
NODL_COLLAB_ENDPOINT=wss://api.nodl.dev/collaboration
启动时会自动加载此覆盖(dotenv/config).
将此端点设置为统一后端Socket。IO命名空间URL。
工具合同
join_project
输入:```json
{
"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`
输入:```json
{
"token": ""
}
输出:
- 角色
- 范围
- 过期状态
list_nodes
输入:```json
{}
输出:
- 来自的本地节点目录 `assets/node-metadata.json` (类型、类别、端口、属性)
### `list_current_nodes`
输入:```json
{}
输出:
- 轻量级会话范围摘要,包括:
initializedsessionScoped: truelastUpdatedAtcounts(nodes,connections)nodeIdsPreviewconnectionIdsPreview
可选输入:
includeFullState: true包括完整nodes和connectionspreviewLimit在摘要模式下调整预览大小(默认20,最大200)
describe_current_nodes
输入:```json
{
"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`:返回节点的允许属性架构和当前值
- `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`)
- 角色/范围允许请求的操作
## 本地开发```bash
npm install
npm run build
npm start
直接运行时(npx -y nodl-collab-mcp),服务器仍在等待stdio。
这是意料之中的。启动日志打印到 stderr.
集 NODL_MCP_SILENT=true 禁用启动日志。
