Echo MCP (Zenlix AI)

回声MCP

一个轻量级的MCP（模型上下文协议）服务器，使代理能够通过MCP工具调用返回发出结构化消息。

英语 | 中文

______________________________________________________________________

目录

• 背景
• 什么是Echo MCP
• 关键设计决策
• 快速开始
• API 参考
• 例子
• 项目结构

______________________________________________________________________

背景

在现有的Agent系统中，Agent通常仅通过自然语言文本来传达中间状态、阶段信息、报告大纲和结构化结果。这带来了几个挑战：

1. 客户难以可靠地提取特定的结构化数据
2. 同类型数据缺乏统一的模式和验证
3. 业务应用程序必须扩展SDK或协议层才能使用这些消息
4. 仅使用自然语言或松散的JSON对代理输出的程序化使用是不可靠的

回声MCP 通过提供一种机制，在不修改底层ACP/SDK协议的情况下，通过MCP工具调用返回来携带结构化消息，从而解决了这个问题。

______________________________________________________________________

什么是Echo MCP

Echo MCP是一种 结构化消息载体和验证工具包 它提供了三个核心功能：

1. 内置架构配置 --通过服务器端配置文件维护可用模式
2. 架构发现 --查询可用的内置架构
3. 回声/发射 --接收有效载荷，根据指定的模式进行验证，并返回不变的结果

Echo MCP不是什么

• ❌ 业务工作流引擎
• ❌ 活动巴士
• ❌ 渲染层协议
• ❌ 权限管理系统
• ❌ 状态管理框架

它只提供低级功能，没有业务层限制。

______________________________________________________________________

关键设计决策

1.MCP工具返回作为消息载体

回波MCP的输出是MCP工具调用返回值。

• 不依赖于副作用流项目
• 客户端不需要额外的协议扩展
• 客户只需观察工具返回情况

2.输入模式=输出模式

Echo MCP接收有效有效载荷并原封不动地返回：

• 输入模式=输出模式
• 无有效载荷转换、归一化或现场注入
• “回声”意味着精确再现

3.配置驱动内置

• 客户端无法在运行时注册新架构
• 内置模式在中维护 config/builtin-schemas.json
• 所有会话都可以使用相同的内置架构集

4.无架构版本控制

如果架构发生更改，请使用新的架构ID。没有显式的版本字段或迁移机制。

5.内置无模式模式

A内置 __schemaless__ 架构ID允许未经验证的结构化输出：

• 可用于快速实验、调试或粗粒度结构化输出
• 请求信封仍在验证中

6.附加语义（不更新）

Echo MCP设计用于 附加新的结构化消息，不更新以前的。

如果您的业务需要“更新”，请在有效载荷中包含标识符（例如。， entity_id, sequence, revision)并让客户端将多条附加消息折叠到“当前状态”中。

7.验证：JSON模式（外部）+Zod（内部）

• 外部架构表达式： JSON模式（用于发现、交换、跨语言兼容性）
• 内部运行时验证： Zod（用于Types/Node.js执行效率）

8.结构化错误响应

所有错误都会返回机器可读的错误代码，其中包含详细的字段级信息：

{
  "ok": false,
  "error": {
    "code": "SCHEMA_VALIDATION_FAILED",
    "message": "Payload does not conform to schema...",
    "schema_id": "zenlix-agent-stage-v1",
    "details": [
      { "path": "/stage", "message": "must be string" }
    ]
  }
}

______________________________________________________________________

快速入门（按技能）

npx skills add https://github.com/ZenlixAI/echo-mcp --skill echo

快速开始

安装

# Clone the repository
git clone https://github.com/zenlix/echo-mcp.git
cd echo-mcp

# Install dependencies (requires pnpm)
pnpm install

发展模式

pnpm dev

服务器运行在 http://localhost:3000 默认情况下。

打开 http://localhost:3000/inspector 在浏览器中以交互方式测试服务器。

为生产而建

pnpm build

运行测试

pnpm test

部署

pnpm deploy

______________________________________________________________________

API 参考

Echo MCP公开了3个MCP工具：

list_schemas

列出所有内置模式（包括内置模式 __schemaless__).

输入： {}

输出：

{
  "schemas": [
    { "schema_id": "__schemaless__", "description": "...", "builtin": true },
    { "schema_id": "zenlix-agent-stage-v1", "description": "...", "builtin": true }
  ]
}

get_schema

获取特定模式的完整定义。

输入： {"schema_id": "zenlix-agent-stage-v1"}

输出： 模式详细信息，包括完整的JSON模式定义。

echo

根据模式验证有效负载，并将其原封不动地返回。

输入：

{
  "schema_id": "zenlix-agent-stage-v1",
  "payload": {
    "stage": "authentication",
    "stage_status": "start",
    "next_stage": "authorization",
    "extra": {
      "user_id": "u_123"
    }
  }
}

输出：

{
  "ok": true,
  "schema_id": "zenlix-agent-stage-v1",
  "payload": {
    "stage": "authentication",
    "stage_status": "start",
    "next_stage": "authorization",
    "extra": {
      "user_id": "u_123"
    }
  }
}

______________________________________________________________________

例子

示例1：工作流阶段通知

zenlix-agent-stage-v1 定义见 config/builtin-schemas.json.

发射阶段更新：

{
  "schema_id": "zenlix-agent-stage-v1",
  "payload": {
    "stage": "authentication",
    "stage_status": "running",
    "next_stage": "authorization",
    "extra": {
      "user_id": "u_123",
      "user_name": "Alice"
    }
  }
}

示例2：最小阶段事件

{
  "schema_id": "zenlix-agent-stage-v1",
  "payload": {
    "stage": "authorization"
  }
}

示例3：无模式输出（快速调试）

{
  "schema_id": "__schemaless__",
  "payload": {
    "kind": "debug_snapshot",
    "raw": { "step": "retrieval_done", "hits": 12 }
  }
}

______________________________________________________________________

项目结构

zenlix-echo-mcp/
├── index.ts              # Process entry point
├── config/
│   └── builtin-schemas.json # Built-in schema configuration
├── src/
│   ├── server.ts         # MCP server assembly and tool registration
│   ├── echo-service.ts   # Built-in schema discovery and echo protocol behavior
│   ├── builtin-schema-config.ts # Built-in schema config loader
│   └── json-schema-zod.ts # JSON Schema to Zod conversion
├── tests/
│   └── echo-service.test.ts  # Protocol and behavior tests
├── docs/
│   └── design-doc.md     # Comprehensive design documentation
├── AGENTS.md             # AI agent navigation guide
└── package.json

______________________________________________________________________

文档

• 设计文档 --全面的产品和技术设计
• 代理商.md --此存储库的AI代理开发指南

______________________________________________________________________

许可证

MIT© ZenlixAI