llmgraph

@llmgraph/mcp-server

一个 Model Context Protocol（MCP）服务，可将你的 LLMGraph 工作流部署公开为 MCP 工具。将它连接到 Claude Desktop、Claude Code、Cursor 或任何其他 MCP 客户端后，你的助手便可以调用你在 LLMGraph 上构建并部署的工作流。

每个已配置的部署都会成为一个 MCP 工具。该服务通过 stdio 运行，并设计为使用 npx 启动，因此无需永久安装。

前提条件

• Node.js 18 或更高版本
• 已部署的 LLMGraph 工作流：从 LLMGraph 控制面板复制部署端点 URL（格式如 https://llmgraph.ai/api/<graph_id>/<environment>）和 API 密钥

配置

所有配置均通过环境变量进行。

单个部署（简单方式）

变量	必填	说明
LLMGRAPH_ENDPOINT	是	从控制面板复制的完整部署端点 URL
LLMGRAPH_API_KEY	是	部署的 API 密钥
LLMGRAPH_TOOL_NAME	否	显示给客户端的工具名称（默认为：invoke_workflow）
LLMGRAPH_TOOL_DESCRIPTION	否	显示给模型的工具说明
LLMGRAPH_SCHEMA_MODE	否	input（默认）或 chat，见下文
LLMGRAPH_TIMEOUT_MS	否	请求超时时间，单位为毫秒，必须是正整数（默认为：180000）。适用于单个和多个部署模式。

多个部署（高级方式）

将 LLMGRAPH_DEPLOYMENTS 设置为 JSON 数组；每个条目都会成为一个工具。设置此变量后，它的优先级高于单个部署变量。

[
  {
    "name": "summarize_document",
    "description": "Summarizes a document with the LLMGraph summarizer workflow",
    "endpoint": "https://llmgraph.ai/api/abc123/production",
    "apiKey": "your-api-key"
  },
  {
    "name": "support_bot",
    "description": "Asks the support assistant workflow a question",
    "endpoint": "https://llmgraph.ai/api/def456/production",
    "apiKey": "your-other-api-key",
    "inputSchema": "chat"
  }
]

模式类型

• input（默认）：该工具接受 { "input": <object> }，并将对象原样作为 POST 请求体传递，因此适用于任何工作流输入结构。
• chat：适用于聊天式工作流。该工具接受 { "user_input": <string>, "history": [{"role": "user"|"assistant", "content": <string>}] }（history 为可选项），并按聊天工作流所需的格式发送。

客户端设置

Claude Desktop

将以下内容添加到 claude_desktop_config.json（Settings、Developer、Edit Config）：

{
  "mcpServers": {
    "llmgraph": {
      "command": "npx",
      "args": ["-y", "@llmgraph/mcp-server"],
      "env": {
        "LLMGRAPH_ENDPOINT": "https://llmgraph.ai/api/abc123/production",
        "LLMGRAPH_API_KEY": "your-api-key",
        "LLMGRAPH_TOOL_NAME": "summarize_document",
        "LLMGRAPH_TOOL_DESCRIPTION": "Summarizes a document with my LLMGraph workflow"
      }
    }
  }
}

重启 Claude Desktop，工具便会显示在工具菜单中。

Claude Code

claude mcp add llmgraph \
  --env LLMGRAPH_ENDPOINT=https://llmgraph.ai/api/abc123/production \
  --env LLMGRAPH_API_KEY=your-api-key \
  -- npx -y @llmgraph/mcp-server

Cursor

添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "llmgraph": {
      "command": "npx",
      "args": ["-y", "@llmgraph/mcp-server"],
      "env": {
        "LLMGRAPH_ENDPOINT": "https://llmgraph.ai/api/abc123/production",
        "LLMGRAPH_API_KEY": "your-api-key"
      }
    }
  }
}

错误处理

LLMGraph API 返回的非 200 响应会作为 MCP 工具错误返回给客户端，并附带 API 的错误消息：

状态	含义
400	请求正文无效
401	API 密钥缺失或无效
402	订阅受限
403	API 已禁用或来源不允许
404	未知部署或 API 密钥错误
422	工作流运行失败
429	速率或预算受限
504	工作流超时

安全说明

• LLMGraph API 密钥是用于服务端的机密信息。此服务仅在向你配置的端点发送请求时将密钥放在 x-api-key 标头中，绝不会将其写入 stdout、stderr 或错误消息。
• claude_desktop_config.json 这类客户端配置文件会在你的计算机上以纯文本形式存储密钥；请妥善处理。

开发

npm install
npm run build   # compiles TypeScript to dist/
npm test        # builds, then runs unit tests (node --test), no network calls

许可证

MIT，详见 LICENSE。