@web_qiang/aform-mcp 0.0.2 → 0.0.3

package/README.md

@@ -6,15 +6,15 @@
 
 ### Tools（工具）
 
-| 名称 | 说明 |
-| --- | --- |
-| `list_components` | 列出全部组件 / 控件，可按 `category` 过滤（`container`/`control`/`table`/`search`/`display`）。 |
-| `get_component_doc` | 查询某个组件 / 控件的说明与关键配置项（RawConfig 字段）。 |
-| `generate_form_config` | 根据字段清单生成 aform 的 `RawConfig` 配置数组（JSON）。 |
-| `search_dict` | 在内置字典中按关键词（label 或 value）模糊检索选项。 |
-| `list_control_types` | 列出全部「写控件」与「展示组件」类型名。 |
-| `list_dicts` | 列出全部内置字典名及其选项数量。 |
-| `get_control_snippet` | 为指定控件生成一段可运行的 Vue SFC 片段（AForm + 单个 configs 项）。 |
+| 名称 | 说明 | 入参 |
+| --- | --- | --- |
+| `list_components` | 列出全部组件 / 控件，可按 `category` 过滤。 | `category?`: container/control/table/search/display |
+| `get_component_doc` | 查询某个组件 / 控件的说明与关键配置项（RawConfig 字段）。 | `name`: string（必填） |
+| `generate_form_config` | 根据字段清单生成 aform 的 `RawConfig` 配置数组（JSON）。 | `fields`: 字段数组 |
+| `search_dict` | 在内置字典中按关键词（label 或 value）模糊检索选项。 | `keyword`: string（必填）, `dict?`: string |
+| `list_control_types` | 列出全部「写控件」与「展示组件」类型名。 | 无 |
+| `list_dicts` | 列出全部内置字典名及其选项数量。 | 无 |
+| `get_control_snippet` | 为指定控件生成一段可运行的 Vue SFC 片段（AForm + 单个 configs 项）。 | `type`: string（必填） |
 
 ### Resources（资源）
 
@@ -26,13 +26,13 @@
 
 ### Prompts（提示词）
 
-| 名称 | 说明 |
-| --- | --- |
-| `generate-form` | 根据自然语言描述编排「查组件 → 选字典 → 生成配置」的流程。 |
-| `explain-component` | 讲解某组件配置项与用法示例。 |
-| `pick-dict` | 在字典中检索合适的选项，用于 select / radioGroup 等控件。 |
+| 名称 | 说明 | 入参 |
+| --- | --- | --- |
+| `generate-form` | 根据自然语言描述编排「查组件 → 选字典 → 生成配置」的流程。 | `description`: string（必填）, `fields?`: string |
+| `explain-component` | 讲解某组件配置项与用法示例。 | `name`: string（必填） |
+| `pick-dict` | 在字典中检索合适的选项，用于 select / radioGroup 等控件。 | `keyword`: string（必填）, `dict?`: string |
 
-## 开发
+## 快速开始
 
 ```bash
 cd mcp
@@ -40,32 +40,227 @@ pnpm install
 pnpm build        # tsc 编译到 dist/
 ```
 
-## 运行
-
-### stdio（本地子进程，Claude Desktop / Cursor 等接入）
+### 方式一：stdio（本地子进程，Claude Desktop / Cursor 等接入）
 
 ```bash
 pnpm start:stdio
+# 等价于：node dist/stdio.js
 ```
 
-`bin` 已注册为 `aform-mcp`，也可直接：
+`bin` 已注册为 `aform-mcp`，也可直接 `node dist/stdio.js`。
+
+### 方式一（推荐，免安装）：`npx -y @web_qiang/aform-mcp`
+
+无需 clone 仓库、无需 `pnpm install`，只要装了 Node 18+，客户端（或终端）直接：
 
 ```bash
-node dist/stdio.js
+npx -y @web_qiang/aform-mcp
 ```
 
-### Streamable HTTP
+`npx` 支持 scoped 包名，会自动从 npm 拉取 `@web_qiang/aform-mcp` 并运行其 `bin`（`aform-mcp` → `dist/stdio.js` 的 stdio 服务）。首次较慢（需下载），之后 `npx` 会命中本地缓存。
+
+> 本地开发时想先用未发布的源码体验，可在 `mcp/` 目录执行 `pnpm build` 后 `pnpm link --global`（或 `npm link`），把 `aform-mcp` bin 链到全局；之后同样可用 `npx -y @web_qiang/aform-mcp` / 直接 `aform-mcp` 调用当前源码产物。要发布到 npm 则在 `mcp/` 执行 `npm publish --access public`（scoped 包默认私有，需加 `--access public` 才能公开安装；`prepublishOnly` 会自动先 `pnpm build`）。
+
+### 方式二：Streamable HTTP
 
 ```bash
 PORT=3000 pnpm start:http
-# 端点：POST http://127.0.0.1:3000/mcp  （同时支持 JSON 与 SSE 响应）
+# 监听 http://127.0.0.1:3000/mcp
 ```
 
 HTTP 模式使用 v2 官方的 `createMcpHandler` + `@modelcontextprotocol/node` 的 `toNodeHandler`，并默认开启 `localhostHostValidation` / `localhostOriginValidation` 守卫，仅允许本机 Host 与 Origin，防止 DNS 重绑定与跨站请求。
 
-## 客户端接入示例
+## 使用方法
+
+MCP 协议基于 JSON-RPC 2.0。下面给出「客户端实际发送什么、会收到什么」的完整示例。所有请求体均为 JSON-RPC 对象，需带 `jsonrpc: "2.0"` 与自增 `id`。
+
+### 1. 初始化（initialize）
+
+任何客户端接入第一步都是 `initialize`，拿到服务端能力声明：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2026-07-28",
+    "capabilities": {},
+    "clientInfo": { "name": "my-client", "version": "1.0.0" }
+  }
+}
+```
+
+响应（节选）会声明本服务支持 `tools` / `resources` / `prompts`：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "2025-11-25",
+    "capabilities": {
+      "tools": { "listChanged": true },
+      "resources": { "listChanged": true },
+      "prompts": { "listChanged": true }
+    },
+    "serverInfo": { "name": "@web_qiang/aform-mcp", "version": "0.0.1" }
+  }
+}
+```
+
+初始化后需补一条通知（无需应答）：
+
+```json
+{ "jsonrpc": "2.0", "method": "notifications/initialized", "params": {} }
+```
+
+### 2. 调用 Tools（stdio 与 HTTP 通用）
 
-### Claude Desktop（`claude_desktop_config.json`）
+#### list_components（按分类过滤）
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": { "name": "list_components", "arguments": { "category": "control" } }
+}
+```
+
+返回 `content[0].text` 为 JSON 字符串，列出所有「写控件」（el-input / number / price / radioGroup / select …）。不带 `category` 则返回全部 24 个组件。
+
+#### get_component_doc
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": { "name": "get_component_doc", "arguments": { "name": "select" } }
+}
+```
+
+返回 `select` 的 `category: "control"`、`description` 与 `config: ["dict","attrs","rules"]` 等。
+
+#### list_dicts / search_dict
+
+```json
+{ "jsonrpc": "2.0", "id": 4, "method": "tools/call",
+  "params": { "name": "list_dicts", "arguments": {} } }
+
+{ "jsonrpc": "2.0", "id": 5, "method": "tools/call",
+  "params": { "name": "search_dict", "arguments": { "keyword": "研发", "dict": "dept" } } }
+```
+
+`search_dict` 返回 `{ dept: [{ label: "研发部", value: "rd" }, ...] }`；不带 `dict` 则在全部字典里模糊匹配 `keyword`。
+
+#### generate_form_config
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 6,
+  "method": "tools/call",
+  "params": {
+    "name": "generate_form_config",
+    "arguments": {
+      "fields": [
+        { "label": "姓名", "props": "name", "required": true },
+        { "label": "性别", "props": "sex", "type": "radioGroup", "dict": [{ "label": "男", "value": "1" }, { "label": "女", "value": "2" }] },
+        { "label": "入职日期", "props": "hireDate", "type": "date" }
+      ]
+    }
+  }
+}
+```
+
+返回 `RawConfig[]` JSON（必填字段自动带 `rules: true`）。
+
+#### get_control_snippet
+
+```json
+{ "jsonrpc": "2.0", "id": 7, "method": "tools/call",
+  "params": { "name": "get_control_snippet", "arguments": { "type": "select" } } }
+```
+
+返回一段最小可运行的 Vue SFC（`<script setup>`），演示把 `select` 挂到 `<AForm>`。
+
+### 3. 读取 Resources
+
+非工具类知识可通过资源协议读取（适合让客户端把知识库当「文件」缓存）：
+
+```json
+{ "jsonrpc": "2.0", "id": 8, "method": "resources/read",
+  "params": { "uri": "aform://components/AForm" } }
+
+{ "jsonrpc": "2.0", "id": 9, "method": "resources/read",
+  "params": { "uri": "aform://dicts" } }
+```
+
+`resources/list` 会枚举出静态资源与模板实例（如 `aform://components/AForm`、`aform://components/select` …）。
+
+### 4. 使用 Prompts
+
+提示词用于把常见任务编排成可复用的对话起点，`prompts/get` 返回一段 `messages`：
+
+```json
+{ "jsonrpc": "2.0", "id": 10, "method": "prompts/get",
+  "params": { "name": "generate-form",
+              "arguments": { "description": "员工信息录入表单", "fields": "姓名,性别,部门" } } }
+```
+
+返回 `messages[0]` 是一条 `user` 文本，要求模型依次调用 `list_components` / `get_component_doc` / `list_dicts` / `search_dict` / `generate_form_config` 完成任务。客户端可直接把这条 message 投入对话上下文。
+
+### 5. 端到端：搭一个「员工信息表单」
+
+典型工作流（模型自动编排，等价于依次调用）：
+
+1. `list_components({ category: "control" })` → 确认可用控件。
+2. `search_dict({ keyword: "", dict: "dept" })` → 拿到部门选项。
+3. `generate_form_config({ fields: [...] })` → 生成配置。
+4. `get_control_snippet({ type: "select" })` → 取单控件示例核对写法。
+5. 把第 3 步的 `RawConfig[]` 交给前端 `<AForm :configs="..." />` 渲染。
+
+### 6. 通过 HTTP 调用（curl 示例）
+
+Streamable HTTP 端点 `POST /mcp` 接收 JSON-RPC，`Accept` 头带上 `text/event-stream` 可让服务端以 SSE 流式返回：
+
+```bash
+# 调用 list_dicts
+curl -s -X POST http://127.0.0.1:3000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_dicts","arguments":{}}}'
+
+# 打开 SSE 流（接收服务端主动推送的通知，如 listChanged）
+curl -N -X GET http://127.0.0.1:3000/mcp -H "Accept: text/event-stream"
+```
+
+> 用 HTTP 时需先完成 `initialize`（建议用支持会话的 MCP 客户端，如 Inspector / Claude Desktop 的 HTTP 接入），手工 curl 多步调用要自行维护 `Mcp-Session-Id` 会话头。
+
+## 客户端接入
+
+### 方式 A：`npx -y @web_qiang/aform-mcp`（推荐，免安装）
+
+适合 Claude Desktop / Cursor / Cline 等支持 MCP 的客户端。直接让客户端用 `npx` 拉起 stdio 子进程，无需本地构建：
+
+```json
+{
+  "mcpServers": {
+    "aform-mcp": {
+      "command": "npx",
+      "args": ["-y", "@web_qiang/aform-mcp"],
+      "env": {},
+      "disabled": false
+    }
+  }
+}
+```
+
+> 该配置与 `node dist/stdio.js` 等价，区别仅在于 `npx` 会自动确保 `aform-mcp` 已安装并运行其 stdio `bin`。需联网首次下载；若处于内网，请改用方式 B 本地指向构建产物。
+
+### 方式 B：本地构建产物（Claude Desktop `claude_desktop_config.json`）
 
 ```json
 {
@@ -78,14 +273,28 @@ HTTP 模式使用 v2 官方的 `createMcpHandler` + `@modelcontextprotocol/node`
 }
 ```
 
-### 用 MCP Inspector 调试
+### Cursor / 其它 stdio 客户端
+
+同样以子进程方式指定 `node dist/stdio.js`，或 `npx -y @web_qiang/aform-mcp` 即可。
+
+### MCP Inspector 调试
 
 ```bash
+npx @modelcontextprotocol/inspector npx -y @web_qiang/aform-mcp
+# 或调试本地构建产物
 npx @modelcontextprotocol/inspector node ./dist/stdio.js
 # 或调试 HTTP 模式
 npx @modelcontextprotocol/inspector http://127.0.0.1:3000/mcp
 ```
 
+## 安全与部署
+
+- **stdio 模式**：进程由客户端本地拉起，无网络暴露，默认安全。
+- **HTTP 模式**：默认开启 `localhostHostValidation` + `localhostOriginValidation`，仅本机可连。若要跨机访问：
+  - 生产环境务必放在反向代理（Nginx / Caddy）后，启用 HTTPS，并在代理层做认证（如 Bearer Token / mTLS）。
+  - 关闭 localhost 守卫前，确认网络可信；相关守卫在 `src/http.ts` 中通过 `toNodeHandler(handler, { guards: [...] })` 配置。
+- `protocolVersion` 采用 v2 协商；旧版只支持 SSE 的客户端（v1）不兼容此 Streamable HTTP 实现。
+
 ## 目录结构
 
 ```

package/dist/stdio.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 export {};

package/dist/stdio.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import { createAformServer } from './server.js';
 // serveStdio 拥有传输层，每次连接调用工厂构建实例；stdout 仅承载 JSON-RPC，日志走 stderr

package/dist/stdio.js.map

@@ -1 +1 @@
-{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAE/C,+DAA+D;AAC/D,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,iBAAiB,EAAE,CAAC,CAAA;AAEpD,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAA;AAE/C,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;IACxB,KAAK,MAAM,CAAC,KAAK,EAAE,CAAA;AACrB,CAAC,CAAC,CAAA"}
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAE/C,+DAA+D;AAC/D,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,iBAAiB,EAAE,CAAC,CAAA;AAEpD,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAA;AAE/C,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;IACxB,KAAK,MAAM,CAAC,KAAK,EAAE,CAAA;AACrB,CAAC,CAAC,CAAA"}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@web_qiang/aform-mcp",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "description": "MCP server for @web_qiang/aform: 组件查询、配置生成与字典检索（stdio + Streamable HTTP 双传输，基于 @modelcontextprotocol/server v2）。",
   "license": "MIT",
   "author": "web_qiang",
   "bin": {
-    "aform-mcp": "/dist/stdio.js"
+    "aform-mcp": "./dist/stdio.js"
   },
   "files": [
     "dist"
@@ -15,7 +15,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "start:stdio": "node dist/stdio.js",
-    "start:http": "node dist/http.js"
+    "start:http": "node dist/http.js",
+    "prepublishOnly": "pnpm build"
   },
   "dependencies": {
     "@modelcontextprotocol/node": "^2.0.0",