Red by Big Red Cloud

Red MCP 服务

Red 是一款开源的 Model Context Protocol（MCP）服务，可通过一组受控的 MCP 工具，将 AI 助手和 MCP 客户端连接到 Big Red Cloud 会计数据。

目前支持的客户平台包括 ChatGPT、Claude、Mistral（Vibe）和 Microsoft 365 Copilot。Copilot 使用位于 /mcp/copilot 的 Microsoft 联合连接器。由于 Microsoft 联合连接器目前存在限制，该连接器暂时为只读。待 Microsoft 支持后，Copilot 预计将支持创建、更新和删除工具。ChatGPT、Claude 和 Mistral 使用 /mcp，在部署启用这些功能时，已包含相应的写入工具。其他 MCP 客户端在技术上可能可用，但不属于官方支持的平台。Red 仅使用平台检测来进行匿名运行遥测（参见注重隐私的遥测）。

用户无需直接调用 Big Red Cloud REST API，而是可以使用自然语言与系统交互。服务会将请求转换为结构化 API 调用，并对任何会更改数据的操作进行安全检查。

使用 Red，已连接的用户可以：

• 查看 Big Red Cloud 数据，只读查询客户、供应商、产品、发票、报价、名义账目报告等。
• 提交前预览——在将任何内容写入 Big Red Cloud 之前，以通俗易懂的语言查看新建或更改记录的预览。
• 仅在明确确认后创建、更新、删除、批量处理或发送记录（且仅当部署启用了这些功能时）。
• 咨询 Big Red Cloud 使用方法和培训问题——Red 使用官方支持文章、客户文档、截图和网络研讨会资源作答。这些帮助工具无需连接公司即可使用。

---

为什么选择开源？

我们相信 AI 基础设施应当透明。客户应能够检查连接其会计数据与 AI 助手的软件。

我们的竞争优势不在于连接器本身，而在于我们的会计平台、专业簿记建议、客户体验，以及我们在此基础上创造的价值。

通过将 Red 开源，我们希望增进信任、促进社区贡献，并推动开放标准得到更广泛的采用。

---

功能

• 安全的公司连接流程（一次性连接页面；聊天中不提供凭据）
• 在连接页面预先验证公司连接凭据（单公司表单或多公司 CSV 上传）
• 部分连接结果——确认前会拒绝无效密钥，并在 failedCompanies 中报告
• 托管 HTTP connectionRef / activeConnectionRef，让 MCP 客户端可在支持的会话变更中静默复用已确认的连接；信息保留在工具 JSON 中，不向最终用户显示
• 事务操作的请求路由——操作工具在继续创建、更新、删除、批处理或电子邮件工作流之前，需要先从路由器获取短期有效的 routeToken
• 保护隐私的匿名运行遥测（平台、环境、工具名称、已连接公司数量）——请参阅 docs/TELEMETRY.md
• 已连接公司的就绪状态检查（brc_company_readiness_check）
• 只读的 Big Red Cloud 查询
• 客户、供应商、产品、销售代表、增值税和分析类别工具
• 销售报价单、发票、贷项通知单、采购、付款和现金工具
• 创建、更新、删除和批处理操作采用先预览再确认流程（电子邮件工具需明确确认发送）
• 增值税和交易安全检查
• 销售发票防护措施，包括多行生成参考编号验证、Gross Price Entry priceBasis 处理、销售增值税类别验证、占位产品 ID 拦截及相关预检
• MCP 会话中写入操作的会话审计日志，以及针对一家已连接公司的可下载支持诊断信息
• 提供来自 Freshdesk 文章、客户文档、截图和网络研讨会的 Big Red Cloud 官方帮助解答——无需连接公司
• 本地 stdio 和托管 HTTP 传输方式

安全与防护模型

Red 旨在确保由 AI 驱动的会计数据访问受到控制且可审计。

• 代码库中不存储凭据。 公司连接凭据和密钥绝不会提交到代码库。配置通过环境变量在运行时提供。
• 聊天中不存储凭据。 不得将公司连接凭据粘贴到聊天中。公司通过安全的 Red 连接页面进行连接，凭据直接在该页面输入，而非在聊天窗口中输入。
• 两种连接模型。 在 https://red.bigredcloud.com/mcp 上，已连接的公司会在大约配置的会话时长内保持可用，并存储在会话内存中（或在托管部署中存储于可选的共享连接存储中）。在支持的情况下，此流程可以在 MCP 会话变更后复用 connectionRef / activeConnectionRef。在 https://red.bigredcloud.com/mcp/copilot 上，公司会关联到连接该公司的已验证 Microsoft 用户。这些归 Microsoft 用户所有的连接与匿名连接或会话连接相互独立。
• 提交前验证。 在连接页面提交的公司连接凭据会先通过 Big Red Cloud 验证，然后才会存储。无效或过期的凭据不会保存；确认时会显示在 failedCompanies 中。
• 凭据失效处理。 只有经过确认的身份验证失败才会清除已存储的公司凭据。端点、验证、权限、超时和服务端故障均不会被视为 API 密钥已过期。
• 面向用户的展示。 connectionRef、会话 ID 和其他 MCP 诊断信息仅供工具参数使用。除非用户明确询问技术细节，否则助手不得向普通用户显示 redconn_… 值或内部连接元数据。
• 可配置的会话时长。 连接的有效时长由 BRC_API_KEY_TTL_MINUTES 控制。面向用户的文案（连接页面、入门说明、连接状态）均根据该值生成，而非硬编码。
• 写入请求路由。 创建、更新、删除、批处理和电子邮件工具都需要请求路由器为相应工作流签发的有效短期 routeToken。路由令牌不代表有权提交——仍须先预览并确认。
• 写入操作需明确确认。 创建、更新、删除和批处理操作必须先显示预览，再通过明确的确认标志才能提交。电子邮件工具则要求在预览邮件后明确确认发送。
• 提交前先预览。 首次调用写入工具时会返回载荷预览，而不会执行操作。确认前，不会向 Big Red Cloud 写入任何内容。
• 读写分离。 只读查询与会更改数据的操作明确区分。
• 审计日志。 通过 MCP 会话执行的写入操作会记录在会话审计日志中；只读查询不会被视为已完成的更改。活动范围限于当前已连接的公司。每次可为一家已连接的公司生成可下载的支持诊断信息；生成该信息为只读操作，不会向 Big Red Cloud 写入数据。
• 部署标志。 每个部署都可以分别禁用更新、删除、电子邮件、批处理和运维/开发工具。对于该进程，已禁用的技能组不会注册到 MCP 客户端，因此这些工具会被隐藏，而非仍可调用。

销售发票安全检查

销售发票处理包括：

• 含税价格录入要求明确指定 priceBasis 为 gross 或 net，以免猜测 VAT。
• 仅限销售 VAT 税率。 销售发票必须使用销售 VAT 类别；即使百分比相同，也会阻止使用采购 VAT 税率。
• 占位产品 ID（productId 0 和 1）会被视为占位值，并在过账前预览和过账之前予以阻止。
• 多行生成参考号的发票（brc_create_sales_invoice_gen_ref）要求每个 productTrans 行都包含自己的 acEntries 分析分配。过账前会验证行净额／VAT／总额的核对结果、分析分配总额、抬头总额，以及必需的产品／VAT／分析字段；验证失败时会返回结构化的字段级错误。
• 除非明确提供备注，否则 note 默认为客户名称，绝不会设为产品名称。
• 仅当明确提供送货地址时才会包含 deliveryTo。
• 通俗易懂的结果。 技术 HTTP 状态码会转换为用户易懂的消息。

---

架构

Red 提供两个托管 MCP 接口，各自拥有独立的工具注册表。

接口	地址	注册表
普通 Red	https://red.bigredcloud.com/mcp	完整工具注册表，包括创建、更新、删除、批量处理和电子邮件功能（具体取决于部署是否启用）
Microsoft 365 Copilot	https://red.bigredcloud.com/mcp/copilot	独立的只读会计门面，以及帮助和公司管理导航

本地 stdio（src/index.ts、node build/index.js）使用与 /mcp 相同的完整注册表。托管 HTTP 实现位于 src/remote.ts。/mcp 注册完整注册表，并在受保护的写入操作中处理请求路由、routeToken 检查和过账前预览确认。/mcp/copilot 仅注册自己的只读门面，不注册会计创建、更新或删除工具。

主要共享模块：

• src/server.ts — MCP 服务工厂和 stdio 单例
• src/register_all_tools.ts — 集中注册工具；跳过已禁用技能组中的工具，并为写入工具包装路由和过账前预览／确认处理
• src/config/server_config.ts — 由 BRC_ALLOW_* 标志控制的部署技能开关
• src/config/mcp_config.ts — MCP 服务指令、连接安全规则、帮助回答规则和 connectionRef 展示规则
• src/routing/ — 事务性工具的请求分类及短时 routeToken 签发／验证
• src/shared.ts — Big Red Cloud HTTP 客户端、连接处理、审计日志和辅助函数
• src/read_connection_metadata.ts — 工具响应中附带的连接状态元数据（包括供托管客户端使用的 activeConnectionRef）
• src/auth/connection_presentation.ts — 面向用户的 TTL 表述和助手展示提示
• src/auth/credential_validation.ts — 存储公司连接凭据前的 BRC 读取验证
• src/guards/ — 事务、引用、VAT 类别、产品行和写入确认安全检查
• src/auth/ — 安全连接流程、连接存储（内存或 Cosmos）、连接页面和凭据持久化
• src/telemetry/ — 用于托管运营遥测的匿名客户端／会话身份和平台检测
• src/brc-edu/ — Freshdesk 文章、客户文档、网络研讨会索引、截图和统一帮助搜索
• src/edu/ — 共享帮助资源加载、增强、工作簿解析和存储配置
• src/tools/edu/ — 只读帮助工具
• src/tools/routing/ — 请求路由工具注册

领域逻辑位于 src/tools/ 下，通用的创建／更新／删除／列表／批量处理辅助函数位于 src/tools/general/。

技术

• TypeScript / Node.js（ES 模块）
• @modelcontextprotocol/sdk
• 使用 Zod 验证工具输入
• 托管模式使用 Express + Streamable HTTP

---

要求

• Node.js 24 或更高版本（package.json 中的 engines；托管的 Linux 应用使用 Node 24）。
• npm（随 Node.js 一起安装）。

---

安装

npm install
npm run build

如果提供了 .env.example 文件，请将其复制为 .env 并调整其中的值：

cp .env.example .env

切勿提交 .env 文件或任何真实凭据。

---

运行

托管 HTTP 服务：

npm run start
# Serves the MCP endpoint at http://localhost:3000/mcp

本地 stdio 服务：

npm run start:local

在没有 MCP 会话的情况下通过浏览器打开 HTTP 端点会返回错误，这是预期行为。

Microsoft Copilot（可选）

托管部署可以为 Microsoft 365 Copilot 提供 /mcp/copilot，作为联合连接器。该路径使用 Microsoft Entra 登录。公司 API 密钥仍需在 Red 连接页面输入，并会存储到已登录的 Microsoft 用户账户中。设置说明见 docs/copilot-entra-sso.md。

生产环境中的 Copilot 地址为 https://red.bigredcloud.com/mcp/copilot。

Copilot 连接器为只读。它可以搜索和检索受支持的 Big Red Cloud 数据，但不会创建、更新或删除记录。这项限制源于当前的 Microsoft 联合连接器，而不是因为 Red 缺少写入工具。待 Microsoft 支持后，预计 Copilot 将支持创建、更新和删除。在此之前，这些操作仍需通过 /mcp 使用 ChatGPT、Claude 和 Mistral。

MCP 客户端配置

本地 stdio（客户端会启动进程）：

{
  "mcpServers": {
    "red-mcp-server": {
      "command": "node",
      "args": ["build/index.js"],
      "env": {
        "BRC_API_BASE_URL": "https://app.bigredcloud.com/api"
      }
    }
  }
}

托管 HTTP（生产环境）：

对于托管的 Big Red Cloud Red 服务，客户应使用：

https://red.bigredcloud.com/mcp

{
  "mcpServers": {
    "red-mcp-server": {
      "url": "https://red.bigredcloud.com/mcp"
    }
  }
}

托管 HTTP（本地开发）：

{
  "mcpServers": {
    "red-mcp-server": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

---

开发与回归测试

脚本	命令	用途
构建	npm run build	将 TypeScript 编译到 build/
开发 HTTP	npm run dev	使用 tsx 从源代码运行 HTTP 服务
开发 stdio	npm run dev:local	使用 tsx 从源代码运行 stdio 服务
全部测试	npm test	先构建，再运行完整测试套件
单元测试	npm run test:unit	仅运行单元测试
安全测试	npm run test:security	侧重安全性的测试
配置测试	npm run test:config	部署/配置测试
集成测试	npm run test:integration	集成测试
生产环境审计	npm run audit:prod	对生产依赖运行 npm audit

测试涵盖上述安全防护措施，包括销售发票检查、交易日期验证、安全连接流程（CSV 验证、部分确认、凭据失效）、connectionRef 展示规则、请求路由、TTL 措辞和响应措辞。

---

环境变量

托管 Red 服务的客户无需配置其环境。ChatGPT、Claude 和 Mistral 使用 https://red.bigredcloud.com/mcp。Microsoft 365 Copilot 使用 https://red.bigredcloud.com/mcp/copilot。

自行托管 Red 的运营方需要为该进程设置环境变量。规范列表（包括哪些设置是可选的、由平台管理或属于机密）见 docs/environment-variables.md。.env.example 仅为占位模板。切勿提交真实机密。

在 /mcp 上，部署技能标志（BRC_ALLOW_*）决定注册哪些工具组。Copilot 门面使用自己的只读目录，不受这些写入标志影响。brc_get_deployment_policy 汇总面向客户的常规注册表可用性。

---

连接公司

客户应通过安全的 Red 连接页面连接公司。不得通过聊天发送公司连接凭据——只能在安全的 Red 连接页面上输入，不能在聊天窗口中输入。

客户可以在 Big Red Cloud 的 Administration → API Keys 下获取或重新生成公司 API 密钥。

流程如下：

1. 请助手开始连接公司。助手会返回一个安全连接页面链接。
2. 在该页面上，输入单家公司、手动输入多家公司，或上传 CSV 一次添加多家公司。公司连接凭据应在安全页面上输入，而不是在聊天中输入。
3. 服务器会在存储凭据之前，通过 Big Red Cloud 验证每项凭据。验证失败的凭据不会被保存。
4. 返回聊天，并提供成功页面上显示的确认码。
5. 确认后，助手会报告哪些公司已连接、哪些连接失败（如有）。无效凭据会立即显示在 failedCompanies 中——无需先运行查询来发现密钥无效。

连接链接只能使用一次。已连接的公司会在配置的会话时长内保持可用（BRC_API_KEY_TTL_MINUTES，例如 240 分钟，即约 4 小时），除非你断开连接或连接过期。

托管 HTTP 和 connectionRef

在托管 HTTP 模式下（例如 Mistral/Vibe），brc_confirm_company_connection 会在工具 JSON 中返回一个不透明的 connectionRef。当平台轮换会话 ID 时，MCP 客户端应保留并在后续工具调用中静默复用 connectionRef / activeConnectionRef。在支持的情况下，即使 MCP 会话轮换，连接也会保持有效。这是客户端的实现细节——助手不得向最终用户显示 connectionRef 或 redconn_… 值。工具响应包含 assistantInstruction / presentationHint 字段，以强化此规则。

辅助工具：

• 列出会话中已连接的公司
• 清除单个公司的连接
• 清除所有公司的连接

---

注重隐私的遥测

在托管部署中，Red 可能会记录匿名运行遥测数据，以帮助运营人员了解大致的使用情况。典型的数据维度包括匿名客户端和连接会话标识符、检测到的平台、部署环境、工具名称以及已连接的公司数量。

遥测不包含 API 密钥、凭据、原始 connectionRef 值、授权标头、请求正文，也不包含发票、客户或供应商载荷。Big Red Cloud 调用失败时可能会包含安全标识符，例如 company_id 或 record_id。匿名遥测不代表经过验证的 Big Red Cloud 用户身份。Microsoft 365 Copilot 使用经过验证的 Microsoft 登录信息来确定该用户可以访问哪些公司。此处所述的登录与匿名遥测无关。

面向运营人员和开发人员的详情：docs/TELEMETRY.md。

---

工具覆盖范围

Red 提供一组精简的 MCP 工具，并按领域分组。具体工具名称及其端点映射位于 src/tools/ 下的源代码中，开发者文档 docs/TOOLS.md 也对此作了概述。

• 公司设置与就绪状态 — 公司设置配置、财务年度、处理设置、就绪状态检查、交易日期验证，以及账户历史记录文档类型解析。
• 客户与供应商 — 列出／获取／创建／更新／删除，以及期初余额和账户交易。
• 产品与销售代表 — 列出／获取／创建／更新／删除，以及产品类型。
• 销售单据 — 报价单、销售发票、销售贷项通知单和销售分录，包括生成编号的变体，以及根据报价单生成发票。
• 采购与付款 — 采购、付款、现金付款、现金收款和银行账户。
• 增值税与分析查询 — 增值税税率、增值税类别、增值税类型、分析类别、账户及相关参考数据。
• 名义账户报表 — 名义账户列表，以及分组／多公司名义账户报告。
• 审计与会话 — 会话连接管理、会话审计日志，以及可下载的支持诊断报告。
• 帮助与培训 — 通过只读帮助工具访问 Freshdesk 文章、客户文档、已录制的网络研讨会、即将举行的网络研讨会和截图链接。无需连接公司。

主要创建工作流提供批处理变体，并采用与单条记录工具相同的安全检查。

公司就绪状态检查

brc_company_readiness_check 是针对已连接公司的只读整体健康检查。整体状态包括：

• ready
• ready_with_warnings
• not_ready
• connection_problem

该工具会检查连接状态及相关设置，例如财务年度、交易日期位置、启用的销售增值税税率、销售分析类别、产品和销售代表。缺少供应商会作为采购设置警告报告，不会阻止销售发票就绪。手动参考编号设置会被视为警告／预检注意事项，不一定会构成阻碍。

对于特定的增值税敏感型工作流（销售发票、采购、现金收款、对账单），请改用 brc_check_transaction_settings — 该工具检查某个工作流的处理设置，而就绪状态检查评估的是公司的整体就绪情况。仍可使用范围更窄的辅助工具，例如 brc_validate_transaction_date、brc_get_company_processing_settings 和 brc_get_company_reference_settings，进行针对性查询。

支持诊断

brc_list_audit_log 显示当前会话中针对当前已连接公司的 Red 写入活动。只读查询不视为已完成的更改。

brc_generate_support_report 会一次为一家已连接的公司创建可下载的纯文本诊断报告。如果使用了多家公司，请为每家公司单独生成报告。报告包含有助于支持工作的成功／失败信息和关联信息。报告不会包含凭据、API 密钥、令牌或连接引用。生成报告是只读操作，不会写入 Big Red Cloud。

开发者详情：docs/TOOLS.md 和 docs/TELEMETRY.md。

上一财务年度行为

交易日期不在当前财务年度内属于警告，并不代表该操作一定无法执行。完成常规预览和确认后，Red 只会尝试受支持的操作。如果 Big Red Cloud 拒绝该操作或日期，Red 会报告实际响应。并非所有历史交易都可以更改。

交易改进

• 报价确认预览、验证和报价转发票生成（brc_generate_sales_invoice_from_quote）。
• 收款的 VAT 处理，以及更新时保留账簿记录。
• 可通过更新工作流，在现有记录上更正支持的付款字段。
• 在进行特定单据的查询或更改之前，应先将账户历史记录行解析为正确的单据类型（brc_resolve_book_transaction_type）。
• 撤销、冲销和更正请求都先作为规划处理——绝不会自动获准过账另一笔交易。

---

帮助与培训资源

Red 提供只读 MCP 工具，用于解答 Big Red Cloud 的帮助与培训问题。这些工具无需连接公司账户。

典型功能：

• 搜索官方文章、客户文档、已录制的网络研讨会和即将举行的网络研讨会；
• 加载所选资源的完整详情，包括分步指南，以及相关截图链接（如有）；
• 通过帮助流程回答预留的帮助类问题（包括 red-help / /red-help 风格的命令）。

帮助答复可能包含：

• 官方 Freshdesk 文章；
• 客户文档；
• 相关截图；
• 已录制的 YouTube 培训视频；
• 即将举行的网络研讨会链接。

帮助资源索引由部署运维方提供。代码仓库包含运维方用于维护这些索引的上传、目录和同步实现。客户无需配置此工作流。

---

已知限制

• 某些功能取决于 Big Red Cloud 中公司的配置方式。
• 发送电子邮件和某些银行写入操作可能需要额外的租户配置，也可能被部署标志禁用。
• 生成引用编号的行为可能取决于 Big Red Cloud 租户设置，某些生成单据的端点可能会采用租户当前的交易日期。日期不在当前财年内时会发出警告，但不会自动拒绝；以 Big Red Cloud 的响应为准。
• 工具是否可用可能因部署策略而异（已禁用的技能组不会注册）。
• 匿名遥测统计的是大致的客户端数量（例如浏览器／设备 Cookie），而非经过验证的个人用户数量。
• 如果客户端未提供足够的识别信息，平台检测结果可能为 unknown。
• 官方支持的客户平台包括 ChatGPT、Claude、Mistral/Vibe 和 Microsoft 365 Copilot。Copilot 是联合连接器，在 Microsoft 支持该连接器上的写入操作之前，仅支持只读。我们不宣称支持其他 MCP 客户端平台。

---

维护者

本项目由 Big Red Cloud 软件开发团队维护。

---

状态

Red 处于 BETA 阶段。 Red 是 Big Red Cloud 的开源 MCP 集成项目，仍在积极开发中。不同版本之间的工具可用性和行为可能会发生变化，某些功能受部署策略限制。

---

许可证

本项目采用 Apache License 2.0 许可。详情请参阅 LICENSE。

---

支持与负责任的信息披露

如果您认为发现了安全问题，请向 Big Red Cloud 的支持团队报告。