MCP 与工具协议

标识

Appaloft MCP Server 是可调用工具入口——它把既有的业务操作目录暴露给 MCP 客户端，不会创建新的 AI-only 业务模型。完整 Appaloft Skill负责判断”该做什么”；MCP 负责在工具已配置时，精确执行”command/query 调用”这一步。

启动方式

# stdio 方式启动（大多数 Agent host 的默认接入方式）
appaloft mcp stdio

# 本地 HTTP JSON-RPC 端点，默认只绑定 localhost
appaloft mcp serve --host 127.0.0.1 --port 3939

# 独立 launcher，委托给同一套 Appaloft 运行时
npx appaloft-mcp
npx appaloft-mcp serve --host 127.0.0.1 --port 3939

启动 Server 本身不会部署应用、创建资源或修改任何状态——只有 MCP 客户端真正调用某个工具时，才会进入 Appaloft 的 command/query 总线。只有在可信反向代理或私有网络已提供安全边界时，才应该把 --host 从 127.0.0.1 改成其他值。

输入字段与校验：工具模型

每个工具都对应一个业务操作 key，命名规则是把 . 替换成 _：

Operation key	Tool 名称
`deployments.create`	`deployments_create`
`deployments.plan`	`deployments_plan`
`resources.configure-source`	`resources_configure_source`
`system.doctor`	`system_doctor`

Tool 的输入 JSON Schema 直接来自和 CLI/API 相同的 Command/Query Schema；Command 调用会经过命令总线，Query 调用会经过查询总线，并标注 entrypoint: "mcp"，方便审计区分调用来源。

不存在只有 Agent 才能调用的专属工具。如果某个行为不在公开的业务操作目录里，它就不是合法的 Appaloft MCP 操作。

输出字段与状态值

Tool 描述会带 MCP 标注，标记查询是否只读、命令是否具有破坏性、查询是否幂等，以及部署类操作是否可能触达外部系统。响应会同时返回 JSON 文本和结构化内容，兼容旧版 MCP 客户端和支持结构化结果的新宿主。

只读资源

appaloft://operation-catalog
appaloft://tools/high-value
appaloft://skill/appaloft
appaloft://skill/deploy-protocol
appaloft://tools/mcp-guide
appaloft://docs/agent

Prompts

appaloft-first-deploy
appaloft-recover-deployment
appaloft-configure-resource
appaloft-observe-runtime
appaloft-publish-static-artifact

Resources 和 Prompts 只提供上下文和工作流起点，不拥有写侧策略、租户选择、后台任务或隐藏状态。

错误码与安全边界

不绕过 Appaloft 直接调用仓库、Use Case、Provider SDK、Docker、SSH、代理或数据库。
不读取或输出 .env、私钥、Token、Cookie、数据库 URL、云厂商凭据或未脱敏日志。
鉴权、租户上下文、操作守卫、确认字段、密钥屏蔽和结构化错误都保留在既有运行时边界内，MCP 层不会绕过它们。
删除和破坏性操作仍然必须使用对应 Schema 中的删除安全检查和精确确认字段（例如要求输入完整 id 才能确认删除）。

和 Skill 的关系

当用户在支持 MCP 的 Agent Host 里说”帮我部署这个仓库”时，Host 会先加载完整 Appaloft Skill判断意图，再根据当前会话是否配置了 Appaloft MCP，决定使用 MCP 工具调用、CLI、HTTP/API 还是 Web——四者最终都落到同一套业务操作。

示例

# 用 stdio 方式为本地 Agent host 提供 MCP 工具
appaloft mcp stdio