Norsk English (UK) English (US) Svenska Deutsch Français Español 中文 (简体)

// GUIDES

Isabyte MCP Server

Isabyte MCP Server

一个独立运行的 Model Context Protocol 服务器，可将任何支持 MCP 的 AI 客户端变成 Isabyte Power Tools 专家。

Isabyte MCP Server 将完整的 Isabyte Power Tools 技能语料打包进一个轻量级 Linux 镜像（约 50 MB），并通过 Model Context Protocol 的 Streamable-HTTP 传输方式对外提供。连接 Claude Desktop、Cline、Cursor、 Continue 或任何其他 MCP 客户端后，你的 AI 助手就会成为 Isabyte 专家，对目录中的每个组件、参数和模式都 掌握有据可依的知识。

一个服务器，一份目录。 这些技能文件描述的是设计系统本身 — 即每个 Isabyte Power Tools 软件包共享的 组件目录、参数和设计令牌 — 因此无论你使用哪个软件包进行构建，同一个服务器都能为你的助手提供可靠依据。

如何运行

  1. 下载 zip 文件并解压。
  2. 将镜像加载到本地 Docker 引擎中：bash load.sh
  3. 启动服务器：docker run --rm -p 7180:7180 isabyte-mcp-server:<version>
  4. 确认其运行正常：curl http://localhost:7180/health 返回 {"status":"ok","skills":10}。
  5. 将任意 MCP 客户端连接到 http://localhost:7180/mcp。

MCP 客户端配置

每个客户端都有自己的配置格式，键写错会导致客户端忽略该条目，或退回到较旧的传输方式。下文的 让 MCP 服务器真正发挥作用一节给出了每个客户端的确切条目。最常见的格式如下，Cursor 使用的就是这种格式：

{
  "mcpServers": {
    "isabyte-expert": {
      "url": "http://localhost:7180/mcp"
    }
  }
}

其他客户端各不相同：VS Code 使用键 servers 并配合 "type": "http"，Windsurf 使用 serverUrl， Gemini CLI 使用 httpUrl，Cline 使用 "type": "streamableHttp"，opencode 则使用 mcp 键并配合 "type": "remote"。Claude Code 和 OpenAI Codex 通过命令添加服务器。

连接后，你的助手即可以 MCP 资源（isabyte-skill://）的形式读取每个 Isabyte 技能，也可以通过 MCP 工具 list_isabyte_skills 和 read_isabyte_skill 读取；对于支持工具但不支持资源的客户端，这两个工具会 返回相同的文本。isabyte_expert_guidance 提示词会将所有技能作为依据上下文注入。

安全

默认情况下，服务器绑定到 0.0.0.0 且不需要身份验证 — 对于单台本地工作站来说没有问题。如果该容器在 localhost 之外也能被访问：

  • 仅绑定到 localhost：-p 127.0.0.1:7180:7180
  • 或要求使用 bearer 令牌：-e MCP_AUTH_TOKEN="$(openssl rand -hex 24)"，并在客户端配置中添加 "headers": { "Authorization": "Bearer YOUR_TOKEN" }。

让 MCP 服务器真正发挥作用

AI 编码代理要用好这个服务器，需要两样东西：一个连接（即客户端 MCP 配置中的服务器条目），以及项目中的一个 指令文件，告诉代理何时使用它。没有指令文件，代理虽然能看到服务器，却不知道在编写 Isabyte 代码之前应当先阅读 Isabyte 文档，于是只能靠猜。

指令文件。 它的内容对每个客户端都相同，只有文件名和所在文件夹不同，因此请在下方下载适用于你的客户端的版本。它特意使用英文：阅读它的是代理，而不是你的团队。浏览器下载无法创建文件夹，因此请将文件移动到为你的客户端列出的路径。如果你的项目中已有同名文件，请将内容追加到其中，而不是替换它。Cursor、Windsurf 和 Continue 的文件以一段简短的头部开头，它让客户端在每个会话中都加载该文件；请将这段头部保留在文件的最顶部。

开始之前。 服务器必须处于运行状态（参见如何运行）。下面的每个示例都以名称 isabyte-expert 将其注册在 http://localhost:7180/mcp。如果你启动服务器时使用了 MCP_AUTH_TOKEN，还需将安全一节中的 Authorization: Bearer 标头添加到客户端配置的 headers 字段中。

资源或工具 — 两种方式都可以。 服务器以相同的文本将 Isabyte 文档提供两次：一次作为 MCP 资源 （isabyte-skill://…），一次通过两个 MCP 工具 list_isabyte_skills 和 read_isabyte_skill。有些客户端会读取 资源，而下面的每个客户端都能调用工具，因此代理总有办法读取文档。指令文件会告诉代理：当它的客户端无法读取资源时，改用工具。

适用于每个客户端的测试提示词。 客户端连接后，在你的项目中打开一个新会话并提问： “在注册表单中添加一个 Isabyte 日期选择器。” 代理应当在编写任何代码之前先读取 isabyte-skill://isabyte-controls.md，或针对 isabyte-controls 调用 read_isabyte_skill。如果它没有先阅读 Isabyte 文档就编写了 Isabyte 代码，则表示指令文件没有被加载。

Claude Code

MCP 配置 — 此命令会在项目根目录写入 .mcp.json，因此每个打开该项目的人都能获得这个服务器：

claude mcp add --transport http --scope project isabyte-expert http://localhost:7180/mcp

指令文件 — 项目根目录下的 CLAUDE.md。 下载 CLAUDE.md

检查是否生效 — 在会话中运行 /mcp：isabyte-expert 应显示为已连接。然后尝试测试提示词。

常见问题 — Claude Code 首次在该项目中启动时，会请你批准 .mcp.json 中的服务器；如果你拒绝了，服务器将保持关闭。只有当项目中没有 CLAUDE.md 时，Claude Code 才会读取 AGENTS.md，因此请将内容放入 CLAUDE.md。

OpenAI Codex

MCP 配置 — codex mcp add isabyte-expert --url http://localhost:7180/mcp，它会将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.isabyte-expert]
url = "http://localhost:7180/mcp"

指令文件 — 项目根目录下的 AGENTS.md。 下载 AGENTS.md

检查是否生效 — 运行 codex mcp list，或在 Codex 终端界面中运行 /mcp。然后尝试测试提示词。

如果你启动服务器时使用了 MCP_AUTH_TOKEN，请将令牌放入一个环境变量，并在条目中添加 bearer_token_env_var = "ISABYTE_TOKEN"（即该变量的名称）；Codex 会将其作为 Authorization: Bearer 标头发送。

常见问题 — 项目级的 .codex/config.toml 只有在你已标记为受信任的项目中才会被读取。Codex 的文档并未列出 MCP 资源，因此代理会通过工具 list_isabyte_skills 和 read_isabyte_skill 读取 Isabyte 文档。如果较长的工具结果被截断， 请在 config.toml 中为 read_isabyte_skill 调高 output_token_limit，或让代理每次只读取技能的一个章节。

GitHub Copilot

MCP 配置 — 在 VS Code 中，使用 .vscode/mcp.json：

{
  "servers": {
    "isabyte-expert": {
      "type": "http",
      "url": "http://localhost:7180/mcp"
    }
  }
}

指令文件 — .github/copilot-instructions.md。 下载 copilot-instructions.md

检查是否生效 — 从命令面板运行 MCP: List Servers：isabyte-expert 应处于运行状态，而 MCP: Browse Resources 会列出它的 isabyte-skill:// 资源。在代理模式下尝试测试提示词。

常见问题 — 此文件使用的键是 servers，而不是 mcpServers。GitHub.com 上的 Copilot 云端代理运行在云端，因此无法访问你 localhost 上的服务器。它只使用 MCP 工具，不使用资源， 因此在它能够访问的服务器上，它会通过 list_isabyte_skills 和 read_isabyte_skill 读取文档。

Cursor

MCP 配置 — 项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "isabyte-expert": {
      "url": "http://localhost:7180/mcp"
    }
  }
}

指令文件 — .cursor/rules/isabyte-mcp.mdc。 下载 isabyte-mcp.mdc

检查是否生效 — Cursor 设置中的 MCP 部分应显示 isabyte-expert 已启用；连接错误位于 Output 面板的“MCP Logs” 下。然后尝试测试提示词。

常见问题 — .cursor/rules/ 中的规则必须以 .mdc 结尾；放在那里的普通 .md 文件会被忽略。Cursor 也会读取项目根目录下的 AGENTS.md，因此如果你的项目中已有该文件，也可以改为将内容追加到其中。

Windsurf

MCP 配置 — 在 Cascade 中从“…”菜单打开 MCPs 部分，并编辑原始配置（mcp_config.json）：

{
  "mcpServers": {
    "isabyte-expert": {
      "serverUrl": "http://localhost:7180/mcp"
    }
  }
}

指令文件 — .windsurf/rules/isabyte-mcp.md。 下载 isabyte-mcp.md

检查是否生效 — MCPs 部分应列出 isabyte-expert 及其工具和资源。然后在 Cascade 中尝试测试提示词。

常见问题 — Windsurf 现已更名为 Devin Desktop。它仍会读取 .windsurf/rules/，但其默认的 Devin Local 代理从 .devin/mcp_config.json 读取 MCP 服务器，而不是从 Cascade 配置中读取；请使用 devin mcp add -s project isabyte-expert http://localhost:7180/mcp 将服务器添加到那里。一个规则文件最多可容纳 12,000 个字符。

Gemini CLI

MCP 配置 — 此命令会在项目中写入 .gemini/settings.json：

gemini mcp add --transport http isabyte-expert http://localhost:7180/mcp

它写入的条目使用 httpUrl：

{
  "mcpServers": {
    "isabyte-expert": {
      "httpUrl": "http://localhost:7180/mcp"
    }
  }
}

指令文件 — 项目根目录下的 GEMINI.md。 下载 GEMINI.md

检查是否生效 — 运行 /mcp：isabyte-expert 应显示为已连接，并列出其工具和资源。然后尝试测试提示词。

常见问题 — 在 settings.json 中，httpUrl 表示 Streamable HTTP，也就是此服务器所使用的传输方式；url 表示较旧的 SSE 传输方式，无法连接。只有当设置中的 context.fileName 列出了它时，Gemini CLI 才会读取 AGENTS.md，因此请使用 GEMINI.md。Gemini CLI 默认会截短超过 40,000 个字符的工具结果 （tools.truncateToolOutputThreshold）；最大的 Isabyte 技能超过了这个长度，因此代理应每次只读取其中一个章节 （read_isabyte_skill 接受一个 section 参数）。

Cline

MCP 配置 — 在 MCP Servers 面板中，选择 Configure → “Configure MCP Servers”，然后添加：

{
  "mcpServers": {
    "isabyte-expert": {
      "type": "streamableHttp",
      "url": "http://localhost:7180/mcp"
    }
  }
}

指令文件 — .clinerules/isabyte-mcp.md。 下载 isabyte-mcp.md

检查是否生效 — MCP Servers 面板应显示 isabyte-expert 已连接，并带有工具 list_isabyte_skills 和 read_isabyte_skill。然后尝试测试提示词。

常见问题 — 如果没有 "type": "streamableHttp"，Cline 会退回到较旧的 SSE 传输方式，因而无法连接。Cline 的文档只是顺带提及 MCP 资源，因此代理会通过工具读取 Isabyte 文档。

Continue

MCP 配置 — 文件 .continue/mcpServers/isabyte-expert.yaml：

name: Isabyte MCP server
version: 0.0.1
schema: v1
mcpServers:
  - name: isabyte-expert
    type: streamable-http
    url: http://localhost:7180/mcp

指令文件 — .continue/rules/isabyte-mcp.md。 下载 isabyte-mcp.md

检查是否生效 — 在代理模式下输入 @：isabyte-expert 的资源应出现在上下文提供程序中。然后尝试测试提示词。

常见问题 — Continue 仅在代理模式下使用 MCP 服务器。该 YAML 文件必须包含 name、version 和 schema 这几行，否则不会被加载。Authorization 标头应放在服务器条目中的 requestOptions: → headers: 之下。

opencode

MCP 配置 — 项目根目录下的 opencode.json：

{
  "mcp": {
    "isabyte-expert": {
      "type": "remote",
      "url": "http://localhost:7180/mcp",
      "enabled": true
    }
  }
}

指令文件 — 项目根目录下的 AGENTS.md，与 OpenAI Codex 读取的是同一个文件。 下载 AGENTS.md

检查是否生效 — opencode mcp list 会显示 isabyte-expert 是否已连接。然后尝试测试提示词。

常见问题 — 只有当项目中没有 AGENTS.md 时，opencode 才会读取 CLAUDE.md。其文档只介绍了 MCP 工具，因此代理会通过工具 list_isabyte_skills 和 read_isabyte_skill 读取 Isabyte 文档。

Claude Desktop

Claude Desktop 没有项目指令文件。请改为在 Claude 项目中，将上面任意一个下载文件的内容粘贴到项目指令中。它的自定义连接器（Customize → Connectors → Add custom connector）是从 Anthropic 的云端而不是从你的计算机发起连接，因此无法访问 localhost 上的服务器：服务器必须能够通过 HTTPS 从互联网访问。

如果仍然无法正常工作

  • curl http://localhost:7180/health 失败：服务器没有在运行。
  • 地址必须以 /mcp 结尾。
  • 客户端报告 401：服务器启动时使用了 MCP_AUTH_TOKEN，而客户端没有发送 Authorization: Bearer 标头， 或者发送的令牌不正确。
  • 代理没有阅读 Isabyte 文档（资源或 read_isabyte_skill）就编写了 Isabyte 代码：指令文件不在为你的客户端 列出的路径中，或者你在添加该文件后尚未启动新会话。
  • 更改客户端的 MCP 配置后，请重启客户端或启动新会话。
发生了未处理的错误。 重新加载 🗙

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please reload the page.