Zhin MCP Server Guide

Use this skill to set up the @zhin.js/mcp plugin, enabling AI assistants (Claude, Cursor, etc.) to understand and generate Zhin plugins via the Model Context Protocol.

Installation

pnpm add @zhin.js/mcp

Configuration

MCP requires the HTTP plugin. Enable both in zhin.config.yml:

plugins:
  - http
  - mcp

http:
  port: 8086

mcp:
  enabled: true
  path: /mcp

The MCP endpoint is available at http://localhost:8086/mcp.

Connecting AI Assistants

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zhin": {
      "command": "curl",
      "args": ["-N", "http://localhost:8086/mcp"]
    }
  }
}

Cursor/VSCode

Install an MCP extension and configure the server URL in settings.

Available Tools

create_plugin

Create a new Zhin plugin file.

Parameter	Required	Description
`name`	Yes	Plugin name
`description`	Yes	Plugin description
`features`	No	Feature list: `command`, `middleware`, `component`, `context`, `database`
`directory`	No	Save directory (default: `src/plugins`)

create_command

Generate command code snippets.

Parameter	Required	Description
`pattern`	Yes	Command pattern, e.g. `hello <name:text>`
`description`	Yes	Command description
`hasPermission`	No	Whether to include permission checks

create_component

Generate message component code.

Parameter	Required	Description
`name`	Yes	Component name
`props`	Yes	Property definitions
`usesJsx`	No	Whether to use JSX syntax

create_adapter

Generate platform adapter code.

Parameter	Required	Description
`name`	Yes	Adapter name
`description`	Yes	Adapter description
`hasWebhook`	No	Whether webhook support is needed

create_model

Generate database model definition.

Parameter	Required	Description
`name`	Yes	Model name
`fields`	Yes	Field definitions

query_plugin

Query details of an existing plugin.

Parameter	Required	Description
`pluginName`	Yes	Plugin name to query

list_plugins

List all loaded plugins (no parameters).

Available Resources

MCP exposes documentation as resources:

URI	Description
`zhin://docs/architecture`	Zhin architecture design
`zhin://docs/plugin-development`	Plugin development guide
`zhin://docs/best-practices`	Development best practices
`zhin://docs/command-system`	Command system docs
`zhin://docs/component-system`	Component system docs
`zhin://docs/context-system`	Context system docs
`zhin://examples/basic-plugin`	Basic plugin example
`zhin://examples/command-plugin`	Command plugin example
`zhin://examples/adapter`	Adapter example

Available Prompts

create-plugin-workflow

Guides the full plugin creation workflow.

Parameter: feature_type — command, middleware, component, or adapter.

debug-plugin

Step-by-step plugin debugging guidance.

Parameter: error_message (optional) — the error to diagnose.

best-practices

Returns Zhin development best practices.

Usage Scenarios

Create a Plugin via AI

User: Create a plugin named "welcome" that replies when users say hello

AI: [Uses create_plugin tool] Created plugin with command feature...

Debug a Plugin via AI

User: My plugin reports "Context not found"

AI: [Uses query_plugin to inspect] This error usually means the context
    dependency hasn't been registered yet...

Generate an Adapter via AI

User: Create a WhatsApp adapter with webhook support

AI: [Uses create_adapter tool] Generated WhatsApp adapter scaffold...

Checklist

Install @zhin.js/mcp and @zhin.js/http.
Add both http and mcp to the plugins list.
Configure mcp.path (default /mcp).
Start the Zhin app, then connect your AI assistant.
Use MCP tools to scaffold plugins, commands, components, and adapters.
Access zhin://docs/* resources for framework documentation.

zhin-mcp-server