spec v0.1
ZH

架构模式 · 规范 v0.1

首先为 智能体 构建软件。 界面随后而来。

下一代软件将不再主要通过按钮、表单和表格操作。它将通过安全、描述清晰且可自动化的能力来驱动。

阅读宣言 查看架构 安全模型 →

A screen is just one interface. A capability is the product.

范式转变

Web 应用不再是核心，它是一个客户端。

Klassisch

  1. Webapp
  2. Mobile App
  3. Admin UI
  4. API
  5. Automation
  6. AI-Integration

MCP-first

  1. Domain Model
  2. Action Layer
  3. Permission Layer
  4. MCP Tools
  5. MCP Resources
  6. MCP Workflows
  7. Audit Layer
  8. Webapp · Mobile · Admin · API · Automation

为何 UI-first 会失效

智能体不应该通过点击界面来完成任务。

对人类而言，页面、弹窗和表格是合理的。对智能体、自动化系统和外部系统而言，它们是错误的抽象模型。

✕ 智能体不应该需要知道

  • 按钮在哪个页面上
  • 需要打开哪个弹窗
  • 哪个表格需要先过滤
  • 需要怎样的点击顺序

智能体需要知道

  • 有哪些可用操作
  • 操作的输入和输出是什么
  • 需要哪些权限
  • 哪些操作是危险的或不可逆的

MCP-first 意味着什么

每项能力都成为一个结构化的构建块。

MCP-first 是一种架构原则，软件首先通过其能力来描述——机器可读、类型化、权限验证。

01 Resources 可被读取的数据与上下文。 02 Tools 系统可执行的操作。 03 Workflows 贯穿复杂流程的预定义工作流。 04 Policies 规则、权限、保护级别与审批流程。 05 Audit Events 每项操作的完整可追溯性。 06 Confirmation Gates AI 必须询问用户确认的节点。 07 Risk Metadata 无害、敏感、关键或不可逆的分级标注。

如果你的软件能做到，MCP 就必须能够描述它。如果 MCP 能执行，Policy 就必须能够控制它。

安全优先

支持智能体不等于失去控制。

每项能力都有风险等级。AI 不能自动执行所有操作——但系统必须能够结构化地描述其所有能力。

Low 通常可自主运行。
Medium 上下文明确时可自主运行。
High 通常需要确认。
Critical 始终需要确认，通常需要升级验证。
Forbidden for AI 禁止 AI 访问。
查看风险模型 →

Sales Assistant

emails.send_external
Critical

向 Max Müller 发送 Havelblick 项目的跟进邮件。

收件人
Max Müller · Müller GmbH
附件
下载链接，有效期 14 天

Grund包含项目相关信息的外部通信。

架构

核心是可控的能力层。

业务逻辑不属于 Web 应用，也不属于 MCP 服务器。两者都是适配器。真正的核心是 Capability 层——被所有界面共同使用。

查看完整架构模型 →

身份验证与授权

并非每个智能体都能看到每个工具。

OAuth 2.1 + PKCE

用于 MCP 客户端，配合短期 Token 和轮换机制。

Delegated Context

智能体代表用户行动——而非使用系统权限。

Scopes & Tenants

工具在发现阶段即按权限过滤。

查看身份验证模型 →

按行业

相同的模式，适用每个领域。

CRM & 销售 跟进、展示材料、买家画像均作为工具。 房地产 交易、预约、提醒通过统一操作层处理。 DevOps 部署、回滚、密钥——受控管理。 客户支持 提供上下文而非直接数据库访问。

宣言

十项原则。

  1. 01能力优于界面
  2. 02工具优于按钮
  3. 03资源优于表格
  4. 04工作流优于导航
  5. 05策略优于信任
  6. 06确认优于盲目自动化
  7. 07审计优于不透明
  8. 08上下文优于原始数据
  9. 09人机界面作为客户端
  10. 10100% 可控，而非 100% 自主
阅读完整宣言

For machines

A hard-spec manifest your agents can read.

Beyond this page there is a normative, vendor-neutral edition written for AI agents at mcp-first.ai/manifest.ai. Point an LLM at it to audit any existing MCP server against 40 conformance rules.

Open the machine manifest →
example prompt
Audit my MCP server against https://mcp-first.ai/manifest.ai. For each rule return pass / fail with a one-line reason, then an overall conformance score.

现代软件的核心问题不再是「我们需要哪些界面？」——而是：我们的系统有哪些能力，谁可以使用它们，它们有多安全？

阅读宣言 MCP-first 检查清单