mcpGraph
执行MCP服务器调用的有向图的MCP服务器。
📖 了解更多： 阅读 mcpGraph：“代码模式”的无代码替代方案 了解mcpGraph如何提供Code Mode的上下文效率和准确性，同时保持无代码解决方案的安全性和可观察性。
🎥 观看演示： 看看 mcpGraph概述和mcpGraphUX演示 观看mcpGraph的运行视频，并探索mcpGraphUX的可视化调试功能。
🎥 观看演示： 看看 mcpGraphToolkit深潜 视频显示代理自主构建、测试和部署编排工具——没有代码的“代码模式”。
概述
mcpGraph是一个MCP（模型上下文协议）服务器，它公开了由声明性YAML配置定义的工具。每个工具都执行一个节点的有向图，可以调用其他MCP工具、转换数据和做出路由决策，所有这些都不需要嵌入完整的编程语言。
主要特点：
- 声明性配置：在YAML中定义工具及其执行图
- 数据转换：使用 JSONata 在节点之间转换数据的表达式
- 条件路由：使用 JSON逻辑 用于条件分支
- 可观察对象：每一个转变和决策都是可追溯的
- 无嵌入式代码：使用标准表达式语言表示的所有逻辑(JSONata, JSON逻辑)
相关工具：
- mcpGraphUX：mcpGraph的可视化调试和开发环境。可视化图形结构，在执行过程中通过活动节点设置动画，设置断点，检查节点输入和输出。请参阅 mcpGraphUX存储库 了解详情。
- mcpGraphToolkit：一个MCP服务器，提供用于构建、测试和管理mcpGraph工具的工具。使用它可以发现可用的MCP服务器、测试表达式和交互式创建图形工具。看 mcpGraphToolkit概述 了解详情。
示例
以下是一个简单的示例，用于统计目录中的文件数：
version: "1.0"
# MCP Server Metadata
server:
name: "fileUtils"
version: "1.0.0"
title: "File utilities"
instructions: "This server provides file utility tools for counting files and calculating total file sizes in directories."
# Optional: Execution limits to prevent infinite loops
executionLimits:
maxNodeExecutions: 1000 # Maximum total node executions (default: 1000)
maxExecutionTimeMs: 300000 # Maximum execution time in milliseconds (default: 300000 = 5 minutes)
# MCP Servers used by the graph
mcpServers:
filesystem:
command: "npx"
args:
- "-y"
- "@modelcontextprotocol/server-filesystem"
- "./tests/counting"
# Tool Definitions
tools:
- name: "count_files"
description: "Counts the number of files in a directory"
inputSchema:
type: "object"
properties:
directory:
type: "string"
description: "The directory path to count files in"
required:
- directory
outputSchema:
type: "object"
properties:
count:
type: "number"
description: "The number of files in the directory"
nodes:
# Entry node: Receives tool arguments
- id: "entry"
type: "entry"
next: "list_directory_node"
# List directory contents
- id: "list_directory_node"
type: "mcp"
server: "filesystem"
tool: "list_directory"
args:
path:
expr: "$.entry.directory"
next: "count_files_node"
# Transform and count files
- id: "count_files_node"
type: "transform"
transform:
expr: '{ "count": $count($split($.list_directory_node.content, "\n")) }'
next: "exit"
# Exit node: Returns the count
- id: "exit"
type: "exit"此图：
- 接收目录路径作为输入
- 调用文件系统MCP服务器的
list_directory工具 - 使用JSONata将结果转换为计数文件
- 返回计数
节点类型
entry：工具图形执行的入口点。接收工具参数。
- 输出：工具输入参数（按原样传递）
mcp：调用内部或外部MCP服务器上的MCP工具。
- 输出：MCP工具的响应（从工具内容解析）
transform：适用 JSONata 用于在节点之间转换数据的表达式。
- 输出：JSONata表达式的求值结果 - 表达式格式：The expr 字段是一个包含JSONata表达式的字符串。对简单表达式使用单引号字符串： expr: '{ "result": "value" }'.使用块标量(|)用于复杂的多行表达式，以提高可读性。
switch：用途 JSON逻辑 有条件地路由到不同的节点。注：varJSON逻辑规则中的操作使用JSONata进行评估，从而允许完全的JSONata表达式支持。
- 输出：路由到的目标节点的节点ID（字符串）
exit：将最终结果返回给MCP工具调用者的退出点。
- 输出：执行历史中前一个节点的输出
执行历史和调试
mcpGraph为每个工具执行维护完整的执行历史，从而实现强大的调试和自检功能：
- 执行历史：每个节点的执行都记录了时间、输出和唯一的
executionIndex（顺序：0、1、2、…） - 上下文结构：表达式的上下文是从历史构建的-一个平面结构，其中每个节点ID映射到其最新输出
- 简单符号： $.node_id 访问节点的最新输出 - 当节点执行多次（循环）时，上下文显示最近的执行 - 历史记录功能提供对所有执行情况的访问，而不仅仅是最新执行情况
- 时间旅行调试：使用以下命令获取任何特定执行可用的上下文
getContextForExecution(executionIndex) - 历史功能：使用JSONata函数访问执行历史：
- $previousNode() -获取上一个节点的输出 - $previousNode(index) -获取当前前执行N步的节点 - $executionCount(nodeName) -计算节点执行的次数 - $nodeExecution(nodeName, index) -获取节点的特定执行（0=第一个，-1=最后一个） - $nodeExecutions(nodeName) -以数组形式获取节点的所有执行
- 环路支持：节点可以在循环中执行多次，每次执行都在历史记录中单独跟踪
看 docs/自检调试.md 有关调试功能的详细文档。
上下文访问：
- 所有节点输出都可以通过节点ID访问（例如。，
$.entry.directory,$.list_directory_node) - 最新执行获胜：
$.increment_node当节点执行多次时，返回最近的输出 - 历史函数在所有JSONata表达式中都可用（包括JSON Logic中使用的表达式
var操作）
JSONata表达式格式
这 expr 转换节点中的字段是一个包含JSONata表达式的字符串。在YAML中，你可以使用：
- 单引号字符串 (
'...')对于简单的单行表达式：
transform:
expr: '{ "count": $count($split($.list_directory_node.content, "\n")) }'这使表达式保持在一行上，非常适合简单的转换。
- 块标量 (
|)对于复杂的多行表达式：
transform:
expr: |
$executionCount("increment_node") = 0
? { "counter": 1, "sum": 1, "target": $.entry_sum.n }
: { "counter": $nodeExecution("increment_node", -1).counter + 1, ... }这提高了具有条件逻辑、嵌套对象或多个操作的表达式的可读性。
两种形式的工作方式相同——JSONata将表达式作为字符串进行计算。简单表达式使用单引号，复杂表达式使用块标量，以提高可读性。
对于开发者
如果您有兴趣为mcpGraph做出贡献或使用源代码，请参阅 贡献.md 有关设置说明、开发指南和项目结构。
安装
从npm安装mcpGraph：
npm install -g mcpgraph或者在项目中本地安装：
npm install mcpgraph配置
执行限制
mcpGraph支持循环图，这需要护栏来防止无限循环。执行限制可以在图形级别配置：
version: "1.0"
server:
name: "myServer" # Required: unique identifier
version: "1.0.0" # Required: server version
title: "My MCP server" # Optional: display name (defaults to name if not provided)
instructions: "Instructions for using this server" # Optional: server usage instructions
# Optional: Execution limits to prevent infinite loops
executionLimits:
maxNodeExecutions: 1000 # Maximum total node executions (default: 1000)
maxExecutionTimeMs: 300000 # Maximum execution time in milliseconds (default: 300000 = 5 minutes)
tools:
# ... tool definitions ...执行限制：
maxNodeExecutions（可选）：整个图中节点执行的最大数量。违约：1000。如果执行达到此限制，则抛出错误。maxExecutionTimeMs（可选）：图形执行的最长挂钟时间（毫秒）。违约：300000（5分钟）。如果执行超过此时间，则会抛出错误。
在每个节点执行之前，都会检查这两个限制。如果超过任一限制，执行将立即停止，并显示一条明确的错误消息，指示达到了哪个限制。
注： 这些限制是可选的。如果未指定，则应用默认值。对于长时间运行的批处理作业，可以将它们设置为更高的值，对于快速操作，可以将其设置为较低的值。
作为MCP服务器
使用 mcpgraph 作为MCP客户端（如Claude Desktop）中的MCP服务器，将其添加到MCP客户端的配置文件中。
Claude桌面配置
添加 mcpgraph 到您的Claude Desktop MCP配置（通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上，或 %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：
{
"mcpServers": {
"mcpgraph": {
"command": "mcpgraph",
"args": [
"-g",
"/path/to/your/config.yaml"
]
}
}
}或者如果没有安装（从npm运行）：
{
"mcpServers": {
"mcpgraph": {
"command": "npx",
"args": [
"-y",
"mcpgraph",
"-g",
"/path/to/your/config.yaml"
]
}
}
}注： 替换 /path/to/your/config.yaml 使用YAML配置文件的实际路径。这 -g （或 --graph)flag指定要使用的图形配置文件。
程序化API
这 mcpgraph 包导出可在您自己的应用程序中使用的程序化API（例如，用于构建UX服务器或其他接口）：
import { McpGraphApi } from 'mcpgraph';
// Create an API instance (loads and validates config)
const api = new McpGraphApi('path/to/config.yaml');
// List all available tools
const tools = api.listTools();
// Execute a tool
const result = await api.executeTool('count_files', {
directory: './tests/counting',
});
// Clean up resources
await api.close();看 examples/api-usage.ts 举一个完整的例子。