Echo MCP

A lightweight MCP (Model Context Protocol) server that enables Agents to emit structured messages through MCP tool call returns.

License

English | 中文

Background
What is Echo MCP
Key Design Decisions
Quick Start
API Reference
Examples
Project Structure

Background

In existing Agent systems, Agents typically communicate intermediate states, stage information, report outlines, and structured results only through natural language text. This creates several challenges:

Clients struggle to extract specific structured data reliably
Same-type data lacks unified schema and validation
Business applications must extend SDKs or protocol layers to consume these messages
Programmatic consumption of Agent outputs is unreliable with just natural language or loose JSON

Echo MCP solves this problem by providing a mechanism to carry structured messages via MCP tool call returns — without modifying the underlying ACP/SDK protocols.

What is Echo MCP

Echo MCP is a structured message carrier and validation toolkit that provides three core capabilities:

Built-in Schema Config — Maintain available schemas through a server-side config file
Schema Discovery — Query available built-in schemas
Echo/Emit — Receive payloads, validate against specified schemas, and return unchanged

What Echo MCP IS NOT

❌ A business workflow engine
❌ An event bus
❌ A rendering layer protocol
❌ A permission management system
❌ A state management framework

It only provides low-level capabilities without business-layer restrictions.

Key Design Decisions

1. MCP Tool Return as Message Carrier

Echo MCP's output is the MCP tool call return value.

No dependency on side-effect stream items
No additional protocol extensions required for clients
Clients only need to observe tool returns

2. Input Schema = Output Schema

Echo MCP receives valid payloads and returns them unchanged:

Input schema = Output schema
No payload transformation, normalization, or field injection
"Echo" means exact reproduction

3. Config-Driven Built-ins

Clients cannot register new schemas at runtime
Built-in schemas are maintained in config/builtin-schemas.json
The same built-in schema set is available to all sessions

4. No Schema Versioning

If a schema changes, use a new schema ID. No explicit version fields or migration mechanisms.

5. Built-in Schemaless Mode

A built-in __schemaless__ schema ID allows unvalidated structured output:

Useful for quick experiments, debugging, or coarse-grained structured output
Request envelope is still validated

6. Append Semantics (Not Update)

Echo MCP is designed for appending new structured messages, not updating previous ones.

If your business needs "updates", include identifiers in the payload (e.g., entity_id, sequence, revision) and let the client fold multiple append messages into the "current state".

7. Validation: JSON Schema (External) + Zod (Internal)

External schema expression: JSON Schema (for discovery, exchange, cross-language compatibility)
Internal runtime validation: Zod (for TypeScript/Node.js execution efficiency)

8. Structured Error Responses

All errors return machine-readable error codes with detailed field-level information:

{
  "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" }
    ]
  }
}

Quick Start (By Skill)

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

Quick Start

Installation

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

# Install dependencies (requires pnpm)
pnpm install

Development Mode

pnpm dev

The server runs on http://localhost:3000 by default.

Open http://localhost:3000/inspector in your browser to test the server interactively.

Build for Production

pnpm build

Run Tests

pnpm test

Deploy

pnpm deploy

API Reference

Echo MCP exposes 3 MCP tools:

`list_schemas`

List all built-in schemas (including built-in __schemaless__).

Input: {}

Output:

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

`get_schema`

Fetch the full definition of a specific schema.

Input: {"schema_id": "zenlix-agent-stage-v1"}

Output: Schema details including the full JSON Schema definition.

`echo`

Validate a payload against a schema and return it unchanged.

Input:

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

Output:

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

Examples

Example 1: Workflow Stage Notifications

zenlix-agent-stage-v1 is defined in config/builtin-schemas.json.

Emit stage updates:

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

Example 2: Minimal Stage Event

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

Example 3: Schemaless Output (Quick Debug)

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

Project Structure

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

Documentation

Design Document — Comprehensive product and technical design
AGENTS.md — AI agent development guide for this repository