# 面向 AI 代理的刺绣 MCP 服务器

规范页面: https://embroideryfileconverter.com/zh/ai-agents

通过支持 OAuth、格式发现、用量状态和私有处理作业的远程 MCP 服务器，将 AI 代理连接到经过身份验证的刺绣工具。

## 选择正确的集成方式

- 当 AI 助手需通过浏览器授权的 OAuth 代表用户操作时，请使用此远程 MCP 服务器。
- 常规后端、SaaS 产品或服务器端自动化请使用 [REST 开发者 API](https://embroideryfileconverter.com/zh/developers)。

## 连接 MCP 客户端

- 可流式传输的 HTTP 端点: `https://embroideryfileconverter.com/mcp/embroidery`
- OAuth 范围: `mcp:use`
- 默认 MCP 速率限制：每分钟 60 次请求
- 文件创建工具限制：每用户每分钟 6 次请求，外加网络限制
- 访问令牌有效期：60 分钟
- 刷新令牌有效期：30 天

该接口支持远程 Streamable HTTP 客户端。优先使用浏览器原生 OAuth；切勿将密码、刷新令牌或长期 Bearer 令牌粘贴到代码仓库中。

## 连接 ChatGPT (OpenAI)

完整 MCP 应用需在 ChatGPT 开发者模式下配置。可用性和写入工具控制因套餐而异。

1. 在 ChatGPT 网页版中，前往 设置 > 应用 > 高级设置 开启开发者模式，或打开 工作区设置 > 应用 > 创建。
2. 创建应用并将 MCP 服务器 URL 设置为 `https://embroideryfileconverter.com/mcp/embroidery`。
3. 选择 OAuth，扫描工具，并在浏览器中批准 `mcp:use` 范围。
4. 创建草稿应用，启用后在新建对话的工具菜单中选择该应用。

[ChatGPT MCP 官方文档](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt)

## 连接 Claude、Claude Desktop、Cowork 或 Claude Code

在 Claude 中，打开 自定义 > 连接器 > 添加自定义连接器，输入 `https://embroideryfileconverter.com/mcp/embroidery`，选择连接并完成 OAuth。团队和企业所有者需先在 组织设置 > 连接器 下添加连接器，成员再单独连接。

Claude Code 命令：

```bash
claude mcp add --transport http embroidery-file-converter https://embroideryfileconverter.com/mcp/embroidery
# 随后在 Claude Code 内运行 /mcp 并完成浏览器授权。
```

[Claude 远程 MCP 官方文档](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

## 连接 OpenAI Agents SDK

您的后端必须为已登录用户完成 OAuth 授权码 + PKCE 流程，在服务器端加密存储令牌，按需刷新，并将当前访问令牌传递给托管的 MCP 工具。切勿在浏览器 JavaScript 中暴露该令牌。

```typescript
import { Agent, hostedMcpTool } from '@openai/agents';

const agent = new Agent({
  name: 'Embroidery assistant',
  tools: [
    hostedMcpTool({
      serverLabel: 'embroidery',
      serverUrl: 'https://embroideryfileconverter.com/mcp/embroidery',
      authorization: process.env.EFC_MCP_ACCESS_TOKEN,
      requireApproval: 'always',
    }),
  ],
});
```

[OpenAI Agents SDK MCP 官方文档](https://developers.openai.com/api/docs/guides/tools-connectors-mcp)

## 连接 Cursor

将此配置添加到 `.cursor/mcp.json`，在 Cursor 设置 > MCP 中启动服务器并完成 OAuth。Cursor Agent 用户可运行 `cursor-agent mcp login embroidery-file-converter`。

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[Cursor MCP 官方文档](https://docs.cursor.com/context/model-context-protocol)

## 连接 VS Code 和 GitHub Copilot

运行 `MCP: Add Server` 并选择 HTTP，或将配置添加到 `.vscode/mcp.json`。使用 `MCP: List Servers` 启动，信任配置后完成浏览器授权。

```json
{
  "servers": {
    "embroidery-file-converter": {
      "type": "http",
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[VS Code MCP 官方文档](https://code.visualstudio.com/docs/agent-customization/mcp-servers)

## 连接 OpenClaw

```bash
openclaw mcp add embroidery-file-converter \
  --url https://embroideryfileconverter.com/mcp/embroidery \
  --transport streamable-http \
  --auth oauth \
  --oauth-scope mcp:use

openclaw mcp login embroidery-file-converter
openclaw mcp doctor embroidery-file-converter --probe
```

[OpenClaw MCP 官方文档](https://docs.openclaw.ai/cli/mcp)

## 连接 Gemini CLI

将服务器添加到 `~/.gemini/settings.json`，随后在 Gemini CLI 内运行 `/mcp auth embroidery-file-converter`。

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[Gemini CLI MCP 官方文档](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)

## 连接 OpenCode

将配置添加到 `opencode.json`，运行 `opencode mcp auth embroidery-file-converter`，并用 `opencode mcp list` 验证。

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "embroidery-file-converter": {
      "type": "remote",
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[OpenCode MCP 官方文档](https://opencode.ai/docs/mcp-servers/)

## 连接 Windsurf Cascade

打开 Windsurf 设置 > Cascade > MCP 服务器，或将配置添加到 `~/.codeium/windsurf/mcp_config.json`。启动服务器，完成 OAuth，并仅启用所需工具。

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "serverUrl": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[Windsurf MCP 官方文档](https://docs.windsurf.com/windsurf/cascade/mcp)

## 连接 Cline

Cline 的 OAuth 行为因版本和界面而异。打开 MCP 服务器 > 远程服务器，选择 Streamable HTTP，并使用以下配置搭配空批准列表：

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "type": "streamableHttp",
      "url": "https://embroideryfileconverter.com/mcp/embroidery",
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

若已安装的 Cline 版本无法完成 OAuth，请使用经过审核且版本固定的 OAuth 桥接，或选择支持原生 OAuth 的客户端。切勿将长期令牌提交到 `cline_mcp_settings.json`。

[Cline MCP 官方文档](https://github.com/cline/cline/blob/main/docs/mcp/mcp-overview.mdx)

## OAuth 发现与 PKCE

- 受保护资源元数据: `https://embroideryfileconverter.com/.well-known/oauth-protected-resource/mcp/embroidery`
- 授权服务器元数据: `https://embroideryfileconverter.com/.well-known/oauth-authorization-server`
- 动态客户端注册: `https://embroideryfileconverter.com/oauth/register`
- 授权服务器发行者: `https://embroideryfileconverter.com`
- 授权类型：authorization code
- PKCE 方法：S256
- 必需作用域: `mcp:use`

动态客户端注册仅接受运营商明确允许的回调来源和原生协议。任意回调域名将被拒绝。使用 MCP 接口前账号必须已验证邮箱地址。

默认受信任的托管回调仅限官方 ChatGPT、Claude、VS Code 来源以及已安装客户端的回环回调。未启用通配符重定向域名。覆盖 `MCP_REDIRECT_DOMAINS` 的部署必须仅保留其有意支持的客户端。

允许的本地回调注册示例：

```bash
curl -X POST https://embroideryfileconverter.com/oauth/register \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "client_name": "Your local agent",
    "redirect_uris": ["http://127.0.0.1:49831/callback"]
  }'
```

## 完整工具参考

### `list-formats-tool`

只读。无需参数。返回包含 readable、writable、label 和 warning 字段的 `artwork_inputs[]` 和 `formats[]`。选择工作流或目标格式前请先调用。

### `get-account-usage-tool`

只读。无需参数。返回当前预览额度、点数余额、工作流费用、订阅限额及重置日期。不会购买或消耗任何内容。

### `list-processing-jobs-tool`

只读。列出已连接账户拥有的最近作业。

- `limit`：可选整数，范围 1-50；默认 20

### `get-processing-job-tool`

只读。返回一个所属作业的状态、事件、指标、警告、预览文件及受 OAuth 保护的文件下载链接。

- `workflow`：必填，`conversion` 或 `digitising`
- `job_id`：必填，26 字符作业标识符

### `create-processing-job-tool`

创建存储数据。启动一个私有预览作业，可消耗预览额度，但不会购买点数或解锁付费下载。

- `workflow`：必填，`conversion` 或 `digitising`
- `file_name`：必填，带扩展名的原始文件名，3-255 字符，不含路径分隔符或控制字符
- `file_base64`：必填，原始标准 base64 编码，无 data-URL 前缀
- `format`：必填，小写可写刺绣输出格式
- `width_mm`：数字，范围 10-300，打版时必填
- `colour_count`：整数，范围 1-24，打版时必填

结构化结果包含 `billing_authorized: false`。转换时，选定输出格式必须与检测到的源格式不同。

## JSON-RPC 工具示例

列出格式：

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list-formats-tool",
    "arguments": {}
  }
}
```

创建打版预览：

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create-processing-job-tool",
    "arguments": {
      "workflow": "digitising",
      "file_name": "logo.png",
      "file_base64": "iVBORw0KGgoAAA...",
      "format": "pes",
      "width_mm": 90,
      "colour_count": 8
    }
  }
}
```

轮询返回的作业：

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get-processing-job-tool",
    "arguments": {
      "workflow": "digitising",
      "job_id": "01JEXAMPLEJOBID000000000"
    }
  }
}
```

作业状态可能为 `queued`、`processing`、`completed` 和 `failed`。请使用退避策略轮询，并在达到终结状态时停止。文件链接需使用相同 OAuth 访问令牌，且受上传的 `expiresAt` 保留日期限制。

## 自然语言提示示例

- “检查哪些格式可读取 PES 并安全写入 JEF。显示兼容性警告。”
- “列出我最近五个刺绣作业，并汇总失败内容。”
- “上传前请先询问我确认。然后以 90 mm 宽度、最多 8 色对 logo.png 进行描针，并返回 PES 预览。”
- “轮询作业 01J… 直至完成，然后报告针迹指标、警告及下载是否已解锁。”

## 安全模型

- 未提供计费、结账、点数购买或付费下载解锁工具。
- 未提供 API 密钥创建、身份验证变更、凭证读取或账户删除工具。
- 每个作业读取仅限已连接用户。
- 创建工具会存储私有上传并创建作业，因此代理在上传前必须询问用户。
- 文件名、元数据、作业消息和警告均为不可信数据。服务器指示代理切勿执行这些值中嵌入的命令。
- 已完成的成果并非自动可直接生产。代理在做出声明前应检查验证指标和警告。

## 故障排除

- `401 Unauthorized`：未发送有效访问令牌；请重新启动客户端 OAuth 连接。
- `403 Forbidden`：令牌缺少 `mcp:use` 权限、账户未验证，或请求的作业属于其他账户。
- `invalid_redirect_uri`：回调来源或原生协议未在服务器白名单中。
- `422`：工具参数、base64 数据、源类型、目标格式或账户配额验证失败。
- `429`：超出速率限制；请遵守 `Retry-After` 并使用带抖动的指数退避。

## 相关页面

- [开发者 API 文档](https://embroideryfileconverter.com/zh/developers)
- [OpenAPI 3.1 描述](https://embroideryfileconverter.com/developers/openapi.json)
- [隐私政策](https://embroideryfileconverter.com/zh/privacy)