Magicline MCP

magicline mcp服务器

用于Magigline API（OpenAPI、Connect API、Device API、Webhook）的MCP服务器。 服务器加载官方的OpenAPI规范，并将每个操作注册为MCP工具。

概述

此服务器通过stdio向MCP兼容客户端公开Magicline端点。 官方OpenAPI规范中的每个操作都成为一个具有稳定、命名空间名称的工具。

包含的API：

• OpenAPI（核心Magigline API）
• 连接API
• 设备API
• Webhooks API

工具前缀：

• magicline_ （OpenAPI）
• magicline_connect_ （连接API）
• magicline_device_ （设备API）
• magicline_webhooks_ （Webhooks）

通用回退工具：

• magicline_request （JSON或原始正文）
• magicline_request_multipart （多部分/表单数据）

需求

• Node.js 18+（使用内置 fetch)
• Magicline凭据和基本URL

快速开始

1. 安装依赖项：

npm install

1. 获取最新规格（可选但推荐）：

npm run update-openapi

1. 构建：

npm run build

1. 运行（stdio传输）：

MAGICLINE_BASE_URL="https://..." \
MAGICLINE_API_KEY="..." \
node build/index.js

环境变量

OpenAPI（必填）

• MAGICLINE_BASE_URL
• MAGICLINE_API_KEY
• MAGICLINE_API_KEY_HEADER （可选，默认 X-API-KEY)

连接API（可选）

• MAGICLINE_CONNECT_BASE_URL
• MAGICLINE_CONNECT_API_KEY （可选）
• MAGICLINE_CONNECT_API_KEY_HEADER （可选，默认 X-API-KEY)

设备API（可选，承载令牌）

• MAGICLINE_DEVICE_BASE_URL
• MAGICLINE_DEVICE_API_TOKEN
• MAGICLINE_DEVICE_AUTH_HEADER （可选，默认 Authorization)
• MAGICLINE_DEVICE_AUTH_PREFIX （可选，默认 Bearer )

Webhooks API（可选）

• MAGICLINE_WEBHOOKS_BASE_URL
• MAGICLINE_WEBHOOKS_API_KEY
• MAGICLINE_WEBHOOKS_API_KEY_HEADER （可选，默认 X-API-KEY)

规格覆盖（高级）

您可以覆盖更新脚本和运行时加载器使用的规范URL：

• MAGICLINE_OPENAPI_URL
• MAGICLINE_CONNECT_OPENAPI_URL
• MAGICLINE_DEVICE_OPENAPI_URL
• MAGICLINE_WEBHOOKS_OPENAPI_URL

工具是如何生成的

所有工具均源自OpenAPI规范：

• src/openapi.json
• src/connectapi.json
• src/deviceapi.json
• src/webhooks.json

启动时，服务器加载这些规范（如果本地文件丢失，则回退到远程URL） 并注册每个工具 operationId.

工具名称

每个工具名称构造为：

例子：

• magicline_searchCustomers
• magicline_device_activateDevice

工具名称卫生规则：

• 非字母数字字符替换为 _.
• 以数字开头的名称前缀为 op_.
• 如果发生碰撞， _2, _3, ...附后。

工具输入

规范生成的工具接受具有这些可选字段的单个JSON对象 （取决于端点）：

• pathParams：路径参数 {param} 片段
• query：查询参数
• headerParams：规范定义的标头参数
• headers：附加标题
• body：JSON正文
• rawBody：生坯串
• rawBodyBase64：原始主体为base64
• multipart：多部分表单数据部分

执行的规则：

• 只有一个 body, rawBody, rawBodyBase64, multipart 可以设置。
• 如果规范将车身标记为所需，则工具将强制执行。
• 只有在规范声明时才允许使用多部分 multipart/form-data.

多部分格式

当 multipart 支持，每个部分都是以下之一：

• { "kind": "json", "name": "...", "data": { ... } }
• { "kind": "text", "name": "...", "data": "...", "contentType": "..." }
• { "kind": "binary", "name": "...", "dataBase64": "...", "filename": "...", "contentType": "..." }

通用工具

magicline_request

用于对OpenAPI基本URL的即席调用。

输入：

• method: GET | POST | PUT | DELETE | HEAD
• path：相对路径类 /v1/customers
• query, headers, body, rawBody, rawBodyBase64

magicline_request_multipart

用于对OpenAPI基本URL的ad-hoc多部分调用。

输入：

• method: POST | PUT
• path：相对路径类 /v1/customers/{id}/documents
• query, headers, parts

响应格式

所有工具都返回文本响应：

• JSON响应以文本形式打印。
• 非JSON响应返回 { contentType, body } 作为JSON文本。

错误会返回如下文本消息：

Request failed: 

日志记录

服务器仅记录到stderr（stdio要求）。

脚本

• npm run update-openapi：将所有四个规格下载并存储到 src/
• npm run build：编译为 build/ 并将规格复制到 build/

文件布局

• src/index.ts：服务器实现
• src/*.json：OpenAPI规范
• build/index.js：已编译服务器
• build/*.json：复制运行时的规范
• scripts/fetch-openapi.mjs：规范下载器

客户端集成（stdio）

此 MCP 通过 stdio 在本地运行。任何可以启动本地进程的客户端都可以工作。

Codex（CLI和IDE扩展）

Codex 支持 STDIO 服务器，并在 CLI 和 IDE 之间共享 MCP 配置。 您可以通过 CLI 或 config.toml 配置 。

命令行界面（stdio）：

codex mcp add magicline \
  --env MAGICLINE_BASE_URL=https://... \
  --env MAGICLINE_API_KEY=... \
  -- node /absolute/path/to/magicline-mcp-server/build/index.js

config.toml （全球或项目）：

[mcp_servers.magicline]
command = "node"
args = ["/absolute/path/to/magicline-mcp-server/build/index.js"]

[mcp_servers.magicline.env]
MAGICLINE_BASE_URL = "https://..."
MAGICLINE_API_KEY = "..."

克劳德代码（CLI）

Claude Code 可以添加本地 stdio 服务器。重要：所有选项都在服务器名称之前。 和 -- 将 Claude 选项与您的服务器命令分开。

claude mcp add --transport stdio \
  --env MAGICLINE_BASE_URL=https://... \
  --env MAGICLINE_API_KEY=... \
  magicline -- node /absolute/path/to/magicline-mcp-server/build/index.js

克劳德桌面

Claude Desktop 可以通过 MCP 服务器 claude_desktop_config.json 装载 。在那里添加条目 mcpServers 重新启动 Claude Desktop。

{
  "mcpServers": {
    "magicline": {
      "command": "node",
      "args": ["/absolute/path/to/magicline-mcp-server/build/index.js"],
      "env": {
        "MAGICLINE_BASE_URL": "https://...",
        "MAGICLINE_API_KEY": "..."
      }
    }
  }
}

其他 MCP 客户端 （HTTP）

一些客户端，如VS代码（Copilot代理模式）和光标通过JSON文件配置MCP服务器 麻省理工学院 type: "http" 和 url这是为基于HTTP的MCP服务器设计的。如果你这个项目 以后作为HTTP服务器运行，您可以查看其HTTP格式。

故障排除

• Missing MAGICLINE_BASE_URL 或 Missing MAGICLINE_API_KEY:

- 在MCP客户端配置中设置env变量（而不仅仅是shell）。

• Path must be relative:

- 使用 /v1/... 调用通用工具时的样式路径（没有完整的URL）。

• This endpoint does not accept JSON bodies:

- 使用 multipart 如果规范要求 multipart/form-data.

• Request body is required:

- 提供以下之一 body, rawBody, rawBodyBase64，或 multipart.

安全说明

• 不要泄露秘密。使用env变量或本地变量 .env 文件。
• 保持基本URL没有尾随斜线。

开发说明

• TypeScript源代码位于 src/.
• 服务器需要以下规格 src/*.json 在运行时。
• 您可以随时通过以下方式重新生成规格 npm run update-openapi.
• npm test 目前是一个占位符。