Generated reference snapshot
Original Cubic page · captured 2026-09-23 · source commit. This AI-generated page has not been verified against the current code. Use the Zhin documentation for current behavior and see known corrections.
Known correction
The current Runtime Host registers Tools only and is mounted only with an explicit top-level mcp: configuration. ai.mcpServers configures the separate Agent MCP client. The generator, Resource, Prompt, and default-enabled server descriptions below are stale. See the Host implementation and the MCP documentation correction.
Relevant source files
The following files were used as context for generating this wiki page:
Model Context Protocol (MCP)
Model Context Protocol (MCP) provides a service for AI assistants to interact with the Zhin framework. It enables Large Language Models (LLMs) to understand, query, and generate Zhin-specific artifacts such as plugins, commands, and adapters. Sources: packages/host/mcp/README.md:1-7, README.md:110-120
The implementation resides primarily in the @zhin.js/mcp package. It utilizes the official @modelcontextprotocol/sdk to expose Tools, Resources, and Prompts to clients like Claude Desktop, Cursor, or custom AI agents. Sources: packages/host/mcp/package.json:44-50, packages/host/mcp/README.md:9-15
Architecture and Transport
The Zhin MCP Server operates as a stateless service using a modernization transport method called Streamable HTTP. This transport handles independent POST requests to a specified endpoint. Sources: packages/host/mcp/README.md:12, packages/host/mcp/README.md:36-40
Communication Flow
The following diagram illustrates how an AI Assistant communicates with the Zhin runtime through the MCP layer.
The MCP Server functions as a host plugin that is automatically assembled by the Zhin CLI during runtime. Sources: packages/host/mcp/README.md:29-35, AGENTS.md:100-110
Connection Parameters
Clients must configure a HTTP URL rather than a long-lived connection like curl -N. The default endpoint is typically served on port 8086. Sources: packages/host/mcp/README.md:38-42, packages/host/mcp/README.md:126-135
Core Capabilities
The protocol implements three primary capability sets: Tools, Resources, and Prompts. Sources: packages/host/mcp/README.md:11
1. Tools
Tools allow the AI assistant to perform actions within the Zhin environment. The server provides generators for boilerplate code and query tools for introspection. Sources: packages/host/mcp/README.md:65-112
| Tool Name | Description | Required Parameters |
|---|---|---|
create_plugin | Creates a new Zhin plugin file structure. | name, description |
create_command | Generates command code snippets using Next.js style patterns. | pattern, description |
create_component | Generates message component code. | name, props |
create_adapter | Generates platform adapter code (e.g., Telegram, Discord). | name, description |
create_model | Generates database model definitions. | name, fields |
query_plugin | Retrieves detailed information about a specific loaded plugin. | pluginName |
list_plugins | Lists all plugins currently active in the Zhin instance. | None |
Sources: packages/host/mcp/README.md:67-105
2. Resources
Resources provide the AI assistant with static or dynamic contextual data. Zhin exposes its internal documentation and examples through a zhin:// URI scheme. Sources: packages/host/mcp/README.md:113-125
- Documentation:
zhin://docs/architecture,zhin://docs/plugin-development,zhin://docs/command-system. - Examples:
zhin://examples/basic-plugin,zhin://examples/adapter.
3. Prompts
Prompts define standardized workflows for the AI to follow. Sources: packages/host/mcp/README.md:126-140
create-plugin-workflow: Guides the AI through creating commands, middleware, or components.debug-plugin: Provides steps and techniques for troubleshooting Zhin errors.best-practices: Suggests development patterns specific to the Zhin framework.
Configuration
MCP is enabled by default in the zhin.config.yml file. The server requires the Zhin HTTP host to be active. Sources: packages/host/mcp/README.md:29-35, packages/host/mcp/README.md:148-155
mcp:
enabled: true
path: /mcp
http:
port: 8086Sources: packages/host/mcp/README.md:32-35, packages/host/mcp/README.md:164-170
Dependency Hierarchy
The MCP functionality is split between the host implementation and the internal feature protocol. Sources: packages/im/runtime/tests/agent-feature-hmr.test.ts:25-35, packages/host/mcp/package.json:1-20
Sources: packages/im/runtime/tests/agent-feature-hmr.test.ts:140-150, packages/host/mcp/package.json:44-50
Implementation Details
The MCP server relies on the McpIndex to manage tool execution and discovery. During Hot Module Replacement (HMR) events, MCP definitions can be projected through candidate generations without restarting the core plugin setup. Sources: packages/im/runtime/tests/agent-feature-hmr.test.ts:36-55
Entry Point Verification
The package provides a standard entry point at src/index.ts with explicit exports for adapter-tools-helper and runtime. Sources: packages/host/mcp/package.json:7-25, packages/host/mcp/tests/index.test.ts:5-15
Manual Smoke Test
You can verify the MCP server status using a JSON-RPC initialize request via curl:
curl -sS -X POST http://127.0.0.1:8086/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'Sources: packages/host/mcp/README.md:58-62
Summary
The Zhin MCP implementation bridges the gap between the TypeScript framework and AI development tools. By providing a structured interface for code generation and system querying, it facilitates an "AI-first" development experience where the assistant can autonomously manage Zhin plugins and configurations. Sources: packages/host/mcp/README.md:1-20, README.md:65-75