# Zhin MCP Server

> Guides setup and usage of the Zhin MCP (Model Context Protocol) server plugin. Covers configuration, available tools, resources, and prompts for AI assistant integration. Use when integrating Zhin with AI coding assistants like Claude or Cursor via MCP. Use when this capability is needed.

- Skill: `tomevault-io/zhin-mcp-server` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/zhin-mcp-server`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/zhin-mcp-server/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/zhin-mcp-server

---


# 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

```bash
pnpm add @zhin.js/mcp
```

## Configuration

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

```yaml
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`:

```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.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/zhinjs) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-16 -->