Arch MCP 工具

@koreai/arch-mcp-tools 是一个 Model Context Protocol（MCP）服务器，可将您的 AI 编码助手连接到 Kore.ai Agent Platform。它为助手提供一组工具，用于在平台上构建、评估、优化、调试和分析智能体——创建和编辑项目、智能体和工具；运行评估；检查实时会话和追踪；以及诊断故障——所有这些都可以直接在您的编辑器或终端中完成。

它可与任何兼容 MCP 的客户端（Claude Code、Cursor、VS Code、Codex CLI 等）配合使用。该服务器以 arch-agent-platform 的名称向客户端公开，其工具以 platform_* 和 debug_* 为前缀。

1.5.0 版本

@koreai/arch-mcp-tools@1.5.0 是一个重要的功能版本，同时保持在 1.x 兼容线内的 SemVer 次要更新。

该版本新增了：

• 覆盖全部 45 个公共工具和 13 个功能组中 179 个 schema 声明的操作的代码派生覆盖；

• 操作级别的置信度、安全性、前置条件、限制、依赖关系和验证指南；

• 附加的 arch://guidance/v1/* 资源以及规划和验证提示词；

• 一个仅通过所有权安全的 arch-mcp-guidance 命令安装的 schema 门控 Codex/Claude 技能；以及

• 干净包、授权/隔离、兼容性、故障隔离和四指标覆盖门控。

知识协议保持 schema 版本 1；包版本和知识 schema 版本有意保持独立。现有的 45 工具发现、工具名称和 schema、初始化说明、项目构建器负载/顺序以及先前 Studio 降级行为均保持不变。新资源和提示词为追加式添加，指导构建在不禁用旧版 MCP 表面的情况下软失败。

使用者可以显式固定该版本：

npx -y @koreai/arch-mcp-tools@1.5.0

Related MCP server: MCP Architect

要求

• Node.js 18 或更高版本 — 服务器通过 npx 运行，无需单独安装。

• 一个 Kore.ai Agent Platform 账户 — 您在首次连接时进行身份验证（请参阅 身份验证）。

安装

@koreai/arch-mcp-tools 是一个标准的 stdio MCP 服务器。每个客户端都以相同方式启动它：

command:  npx
args:     -y  @koreai/arch-mcp-tools

使用下方您客户端的配置，将其添加到名为 arch-agent-platform 的服务器下。未固定版本的形式遵循 npm latest 标签；如需可复现的安装，请使用 @koreai/arch-mcp-tools@1.5.0。（未内置任何环境——请参阅 选择环境。）

Claude Code

claude mcp add arch-agent-platform -- npx -y @koreai/arch-mcp-tools

或将其添加到 .mcp.json（项目）或 ~/.claude.json（全局）：

{
  "mcpServers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"]
    }
  }
}

Cursor

添加到 .cursor/mcp.json（项目）或 ~/.cursor/mcp.json（全局）：

{
  "mcpServers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"]
    }
  }
}

VS Code（GitHub Copilot）

添加到 .vscode/mcp.json — 请注意顶层键是 servers（而非 mcpServers）：

{
  "servers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"]
    }
  }
}

Codex CLI

codex mcp add arch-agent-platform -- npx -y @koreai/arch-mcp-tools

或添加到 ~/.codex/config.toml — 请注意这是 TOML 格式，而非 JSON：

[mcp_servers.arch-agent-platform]
command = "npx"
args = ["-y", "@koreai/arch-mcp-tools"]

任何其他 MCP 客户端

配置一个 stdio 服务器，命令为 npx，参数为 ["-y", "@koreai/arch-mcp-tools"]。可选地设置 AGENTS_URL 环境变量以固定环境。

可选的 Codex 或 Claude 指导技能

该包附带一个基于服务器版本化操作目录的规范 arch-platform 技能。安装是显式的，绝不会作为正常 MCP 启动的一部分运行：

# User scope
npx -y -p @koreai/arch-mcp-tools arch-mcp-guidance install --client codex --scope user
npx -y -p @koreai/arch-mcp-tools arch-mcp-guidance install --client claude --scope user

# Project scope (run in the project root)
npx -y -p @koreai/arch-mcp-tools arch-mcp-guidance install --client codex --scope project
npx -y -p @koreai/arch-mcp-tools arch-mcp-guidance install --client claude --scope project

安装程序会拒绝未管理或已修改的文件，并在所有权清单中记录哈希值。将 install 替换为 uninstall 可仅移除本包拥有的未更改文件。

或者直接询问您的助手

将以下内容粘贴到您的编码工具的聊天中，它将为您配置好服务器：

添加一个名为 arch-agent-platform 的 MCP 服务器，运行 npx -y @koreai/arch-mcp-tools，并将其放入此项目的 MCP 配置中。 各工具的配置位置 — Claude Code：.mcp.json（mcpServers）· Cursor：.cursor/mcp.json（mcpServers）· VS Code：.vscode/mcp.json（servers）· Codex：~/.codex/config.toml（[mcp_servers.arch-agent-platform]）。 可选地设置 AGENTS_URL 为我的环境。

选择环境

未硬编码任何环境。首次使用时，工具会询问要连接到哪个环境——或者您可以通过在服务器的 env 中设置 AGENTS_URL（或向 platform_connect 传递 serverUrl）来固定一个环境。

固定环境的示例（Claude Code / Cursor 格式）：

{
  "mcpServers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"],
      "env": {
        "AGENTS_URL": "https://agents.kore.ai"
      }
    }
  }
}

代码支持的操作和依赖知识

Arch 为目录清单、功能族、所有 schema 派生的操作、依赖边以及每个功能/每个工具的详细信息提供附加的 arch://guidance/v1/* 资源。每个已发布的工具恰好出现一次；操作来自向 MCP 客户端通告的相同有效输入 schema。经过策划的安全、范围、前置条件、支持、限制和验证引用仅在它们解析为真实工具/操作时才被接受。

在多功能工作之前使用 plan-platform-operation，在特定操作之后使用 verify-platform-operation。静态依赖指导排序；经过身份验证的项目构建器报告仍然是实时项目就绪状态的权威来源。没有公开 Arch MCP 操作的功能不会作为可执行支持呈现。

工具

Arch 构建

创建和更改平台项目、工作流、智能体、工具、认证配置文件、集成、MCP 服务器、配置、版本、部署和导入。

可扩展的项目构建器协议

项目构建器表面有意保持功能中立。客户端通过 platform_project_builder(action: "describe")、MCP 资源和提示词了解核心本体和已注册的提供者。它们不会通过调用原始工具并在本地合并响应来重建跨功能依赖关系。

工作流是第一个 v1.1 提供者。未来的功能将添加一个提供者注册，包含其自身的限定种类、操作、schema、导入/导出、就绪状态所有者和允许列表的 Studio 路由适配器；它不会添加另一个顶层编排约定。实时请求每次都会协商 Studio 契约支持，然后发出一个权威的项目/提供者请求。缺失或模糊的能力响应被报告为 STUDIO_CAPABILITY_UNKNOWN；只有显式降低通告的契约才是 STUDIO_UPGRADE_REQUIRED。

使用 platform_project_builder_operations 进行持久的 列表/读取/报告/恢复/取消/授权/执行流程。 副作用需要 Studio 返回的确切操作版本和受尝试次数约束的授权。切勿重试结果未知的已消耗尝试，也切勿发送原始机密——通过安全的 Studio 流程创建或授权认证配置文件，并且只传递不透明引用。

platform_auth_profiles(create) 仅创建 authType: "none" 配置文件。携带凭据的配置文件有意返回 secureSetupRequired 交接，因为 API 密钥、客户端机密、证书和令牌绝不能进入 MCP/模型上下文。在安全的 Studio 设置之后，MCP 可以列出、检查、更新元数据、验证、撤销、发起 OAuth（包括非机密的 connectionConfig 模板值），并将不透明的配置文件 ID 绑定到集成或 MCP 服务器。

Arch 评估

生成评估资产、运行评估工作流并读取 CI 证据。

Arch 优化

验证包、检查编译器可见的模型并驱动修复循环。

Arch 调试

连接到实时会话、追踪失败并检查执行状态。

历史会话分析

当保留的会话在其实时 MCP 缓冲区不可用之后需要被分析时，debug_session_history 是显式、只读的替代方案。它在 Codex、Claude 和任何符合标准兼容的 MCP 客户端中工作方式相同。请先使用 platform_connect 连接到目标 Runtime，以便现有的承载者身份、工作区和环境仍然保持权威。

列出第一页（默认值为 limit: 50、offset: 0、sortBy: lastActivityAt、sortDir: desc）：

{ "action": "list", "projectId": "project-id", "status": ["completed"], "range": "7d" }

通过推进 offset 读取中间或最终的跟踪页面；超出最终页面是一个空成功页面，而不是错误：

{
  "action": "get",
  "projectId": "project-id",
  "sessionId": "session-id",
  "limit": 200,
  "offset": 200,
  "types": ["llm_call", "tool_call"]
}

Runtime 控制保留、授权、排序以及返回的 _meta.source、source_chain、is_truncated、warnings 和 errors。该工具发出一个有界请求（2 MiB, 10 秒），绝不探测其他路由、重试、静默将隐藏的 404 转换为空页面、填充实时存储，也不会从历史数据回退到 MCP 实时缓冲区。错误作为有界 MCP 错误返回；不要在过滤值中放置凭据或机密。

Arch 分析

解释文档、诊断和系统健康信号。

认证

当您调用 platform_connect 时，认证是自动的 — 它会按顺序尝试：

1. 显式令牌 — 传递一个 authToken 参数。

2. 存储的凭据 — 读取与 artemis-platform-cli login 使用的相同加密凭据存储。

3. 设备授权 — 打开您的浏览器并轮询直到批准在同一个 platform_connect 调用中完成。

凭据被保存以供将来会话重用。

许可证

MIT — 参见 LICENSE。