worsoft-frontend-codegen-local-mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,36 +1,38 @@
 # Worsoft Frontend Codegen Local MCP
 
-This plugin is a parallel local-template MVP for frontend code generation.
-It does not call `/admin/generator/mcp/execute`.
+This MCP generates Worsoft frontend files from a local Markdown design document.
 
-## MVP Scope
+## Scope
 
 - local Markdown design file input
 - style-based template selection
 - local template rendering
 - single-table runtime generation
-- master-child runtime generation with relation inference from the design file
-- render plan preview
+- master-child runtime generation with caller-provided relation input
 - optional write-to-disk
 
 ## Current Inputs
 
-- `designFile` : optional, defaults to `../sql/SQL 设计说明.md`
+- `designFile`: optional, defaults to `../sql/SQL 设计说明.md`
 - `tableName`
 - `style`
 - `frontendPath`
 - `moduleName`
 - `writeToDisk`
-- `childTableName` when `style=master_child_jump` : optional, only needed when one main table has multiple child-table relations in the design file
+- `overwrite`
+- `childTableName` when `style=master_child_jump`: required
+- `mainField` when `style=master_child_jump`: required
+- `childField` when `style=master_child_jump`: required
+- `relationType` when `style=master_child_jump`: optional
 
 ## Recommended MCP Arguments
 
-Use `designFile` as the source argument.
+Single table:
 
 ```json
 {
   "tableName": "iwm_sys_trade",
-  "style": "master_child_jump",
+  "style": "single_table_dialog",
   "designFile": "plugins/sql/SQL 设计说明.md",
   "frontendPath": "E:/own-worker-platform/trunk/worsoft-ui",
   "moduleName": "admin/test",
@@ -38,22 +40,41 @@ Use `designFile` as the source argument.
 }
 ```
 
-## Smoke Test Template
+Master-child:
 
-Use `smoke_test_mcp.js` for quick local MCP verification.
+```json
+{
+  "tableName": "iwm_sys_trade",
+  "style": "master_child_jump",
+  "childTableName": "iwm_sys_trade_level",
+  "mainField": "id",
+  "childField": "trade_id",
+  "relationType": "1:N",
+  "designFile": "plugins/sql/SQL 设计说明.md",
+  "frontendPath": "E:/own-worker-platform/trunk/worsoft-ui",
+  "moduleName": "admin/test",
+  "writeToDisk": false
+}
+```
 
-PowerShell is the recommended option on Windows because it does not depend on Node spawning a child Node process.
+## Smoke Test
 
-```bash
-node plugins/worsoft-codegen-local/smoke_test_mcp.js --scenario single
-node plugins/worsoft-codegen-local/smoke_test_mcp.js --scenario master
-node plugins/worsoft-codegen-local/smoke_test_mcp.js --scenario child
-```
+PowerShell:
 
 ```powershell
 powershell -ExecutionPolicy Bypass -File plugins/worsoft-codegen-local/smoke_test_mcp.ps1 -Scenario single
 powershell -ExecutionPolicy Bypass -File plugins/worsoft-codegen-local/smoke_test_mcp.ps1 -Scenario master
 powershell -ExecutionPolicy Bypass -File plugins/worsoft-codegen-local/smoke_test_mcp.ps1 -Scenario child
+powershell -ExecutionPolicy Bypass -File plugins/worsoft-codegen-local/smoke_test_mcp.ps1 -Scenario missing_relation
+```
+
+Node:
+
+```bash
+node plugins/worsoft-codegen-local/smoke_test_mcp.js --scenario single
+node plugins/worsoft-codegen-local/smoke_test_mcp.js --scenario master
+node plugins/worsoft-codegen-local/smoke_test_mcp.js --scenario child
+node plugins/worsoft-codegen-local/smoke_test_mcp.js --scenario missing_relation
 ```
 
 Optional overrides:
@@ -62,21 +83,30 @@ Optional overrides:
 - `--table-name`
 - `--style`
 - `--child-table-name`
+- `--main-field`
+- `--child-field`
+- `--relation-type`
 - `--frontend-path`
 - `--write-to-disk`
 
-For `master_child_jump`, the execution result will return the detected relation. If the relation is ambiguous or not the one you want, the MCP error/result includes a `correctionEntry` with `childTableName`, `example`, and `retryArguments`, so the caller can resubmit directly.
+## Master-Child Contract
+
+For `master_child_jump`, MCP does not infer relations from the design file anymore.
 
-When one main table has multiple child relations in the design file, add `childTableName` to disambiguate:
+The caller must provide:
+
+- `childTableName`
+- `mainField`
+- `childField`
+
+If these fields are missing, MCP returns `relation_input_required`.
+
+Example:
 
 ```json
 {
-  "tableName": "iwm_sys_trade_level",
-  "style": "master_child_jump",
-  "designFile": "plugins/sql/SQL 设计说明.md",
-  "childTableName": "iwm_sys_trade_level_standard",
-  "frontendPath": "E:/own-worker-platform/trunk/worsoft-ui",
-  "writeToDisk": false
+  "type": "relation_input_required",
+  "requiredFields": ["childTableName", "mainField", "childField"]
 }
 ```
 
@@ -94,28 +124,20 @@ When one main table has multiple child relations in the design file, add `childT
 - Machine source: `assets/style-catalog.json`
 
 Declared styles:
+
 - `single_table_jump`
 - `single_table_dialog`
 - `master_child_jump`
 
-Runtime generation support:
-- `single_table_jump`: supported
-- `single_table_dialog`: supported
-- `master_child_jump`: supported
-
-## Non-goals for v0.1
-
-- backend API forwarding
-- generic Velocity rendering
-- dict lookup from backend
-- full compatibility with the old generator contract
-
 ## Notes
 
 - Shared Worsoft template references live under `../template`.
 - Plugin-local runtime assets live under `assets/templates`.
 - The preferred source is `plugins/sql/SQL 设计说明.md`.
-- Markdown mode parses both the field-definition tables and the "主从表关联说明" section.
-- When a main table has multiple child relations, provide `childTableName` to disambiguate.
-- Menu SQL is currently emitted to `frontendPath/menu/` because local mode does not accept `backendPath` yet.
-- The renderer uses a simple placeholder engine instead of the old backend template engine.
+- Markdown parsing is used for field-definition tables.
+- Master-child relation parsing is handled outside MCP and passed in through tool arguments.
+- Menu SQL is emitted to `frontendPath/menu/`.
+
+## IDE Guide
+
+- `IDE_MCP_SETUP.md`

package/assets/templates/master_child_jump/form.tpl

@@ -2,7 +2,7 @@
   <div class="layout-padding-auto layout-padding-view">
     <el-card shadow="never">
       <template #header>
-        <span>{{ form.{{PK_ATTR}} ? (detail ? 'Detail' : 'Edit') : 'Add' }}</span>
+        <span>{{ form.{{PK_ATTR}} ? (detail ? '查看' : '编辑') : '新增' }}</span>
       </template>
       <el-form ref="dataFormRef" :model="form" :rules="dataRules" :disabled="detail" v-loading="loading">
         <el-row :gutter="24">

package/assets/templates/single_table_dialog/form.tpl

@@ -1,5 +1,5 @@
 <template>
-  <el-dialog v-model="visible" :title="form.{{PK_ATTR}} ? 'Edit' : 'Add'" :close-on-click-modal="false" draggable>
+  <el-dialog v-model="visible" :title="form.{{PK_ATTR}} ? '编辑' : '新增'" :close-on-click-modal="false" draggable>
     <el-form ref="dataFormRef" :model="form" :rules="dataRules" label-width="100px" v-loading="loading">
       <el-row :gutter="24">
 {{FORM_FIELDS}}
@@ -7,8 +7,8 @@
     </el-form>
     <template #footer>
       <span class="dialog-footer">
-        <el-button @click="visible = false">Cancel</el-button>
-        <el-button type="primary" @click="onSubmit" :disabled="loading">Confirm</el-button>
+        <el-button @click="visible = false">取消</el-button>
+        <el-button type="primary" @click="onSubmit" :disabled="loading">确认</el-button>
       </span>
     </template>
   </el-dialog>
@@ -39,7 +39,7 @@ const get{{CLASS_NAME}}Data = async (id: string) => {
     const { data } = await getObj({ {{PK_ATTR}}: id });
     Object.assign(form, data[0] || {});
   } catch (error) {
-    useMessage().error('Failed to fetch data');
+    useMessage().error('获取数据失败');
   } finally {
     loading.value = false;
   }
@@ -75,11 +75,11 @@ const onSubmit = async () => {
 
   try {
     form.{{PK_ATTR}} ? await putObj(form) : await addObj(form);
-    useMessage().success(form.{{PK_ATTR}} ? 'Updated successfully' : 'Created successfully');
+    useMessage().success(form.{{PK_ATTR}} ? '修改成功' : '添加成功');
     visible.value = false;
     emit('refresh');
   } catch (err: any) {
-    useMessage().error(err.msg || 'Submit failed');
+    useMessage().error(err.msg || '提交失败');
   } finally {
     loading.value = false;
   }

package/assets/templates/single_table_jump/form.tpl

@@ -2,7 +2,7 @@
   <div class="layout-padding-auto layout-padding-view">
     <el-card shadow="never">
       <template #header>
-        <span>{{ form.{{PK_ATTR}} ? (detail ? 'Detail' : 'Edit') : 'Add' }}</span>
+        <span>{{ form.{{PK_ATTR}} ? (detail ? '查看' : '编辑') : '新增' }}</span>
       </template>
       <el-form ref="dataFormRef" :model="form" :rules="dataRules" :disabled="detail" v-loading="loading">
         <el-row :gutter="24">
@@ -10,8 +10,8 @@
         </el-row>
       </el-form>
       <div class="dialog-footer" style="text-align: right; margin-top: 18px;">
-        <el-button @click="handleBack">Cancel</el-button>
-        <el-button type="primary" @click="onSubmit" :disabled="loading">Confirm</el-button>
+        <el-button @click="handleBack">取消</el-button>
+        <el-button type="primary" @click="onSubmit" :disabled="loading">确认</el-button>
       </div>
     </el-card>
   </div>
@@ -43,7 +43,7 @@ const get{{CLASS_NAME}}Data = async (id: string) => {
     const { data } = await getObj({ {{PK_ATTR}}: id });
     Object.assign(form, data[0] || {});
   } catch (error) {
-    useMessage().error('Failed to fetch data');
+    useMessage().error('获取数据失败');
   } finally {
     loading.value = false;
   }
@@ -90,10 +90,10 @@ const onSubmit = async () => {
 
   try {
     form.{{PK_ATTR}} ? await putObj(form) : await addObj(form);
-    useMessage().success(form.{{PK_ATTR}} ? 'Updated successfully' : 'Created successfully');
+    useMessage().success(form.{{PK_ATTR}} ? '修改成功' : '添加成功');
     closeCurrentPage();
   } catch (err: any) {
-    useMessage().error(err.msg || 'Submit failed');
+    useMessage().error(err.msg || '提交失败');
   } finally {
     loading.value = false;
   }

package/mcp_server.js

@@ -5,7 +5,7 @@ const fs = require('fs');
 const path = require('path');
 
 const SERVER_NAME = 'worsoft-codegen-local';
-const SERVER_VERSION = '0.1.0';
+const SERVER_VERSION = '0.1.2';
 const PROTOCOL_VERSION = '2024-11-05';
 const TOOL_NAME = 'worsoft_codegen_local_generate_frontend';
 const TEMPLATE_LIBRARY_ROOT = path.resolve(__dirname, '..', 'template');
@@ -19,7 +19,10 @@ const TOOL_SCHEMA = {
     designFile: { type: 'string', description: 'Absolute or relative Markdown design file path. Defaults to ../sql/SQL 设计说明.md when omitted.' },
     tableName: { type: 'string', description: 'Target main table name from the design file.' },
     style: { type: 'string', enum: Object.keys(STYLE_CATALOG), description: 'Style id from assets/style-catalog.json.' },
-    childTableName: { type: 'string', description: 'Optional child table name. In master_child_jump mode, this is the correction entry used to choose one child relation from the design file.' },
+    childTableName: { type: 'string', description: 'Child table name. Required when style=master_child_jump.' },
+    mainField: { type: 'string', description: 'Main table relation field. Required when style=master_child_jump.' },
+    childField: { type: 'string', description: 'Child table relation field. Required when style=master_child_jump.' },
+    relationType: { type: 'string', description: 'Optional relation type label, for example 1:N.' },
     frontendPath: { type: 'string', description: 'Absolute frontend output root path.' },
     moduleName: { type: 'string', description: 'Relative frontend module path, for example admin/test.' },
     writeToDisk: { type: 'boolean', default: true, description: 'Whether to write generated files.' },
@@ -375,7 +378,7 @@ function parseMarkdownRelations(markdownText) {
 function parseMarkdownDesignFile(markdownText) {
   return {
     tables: parseMarkdownDesignTables(markdownText),
-    relations: parseMarkdownRelations(markdownText),
+    relations: [],
   };
 }
 
@@ -475,6 +478,18 @@ function buildRetryArguments(safeArgs, sourceFile, childTableName) {
     retryArguments.childTableName = childTableName;
   }
 
+  if (safeArgs.mainField) {
+    retryArguments.mainField = safeArgs.mainField;
+  }
+
+  if (safeArgs.childField) {
+    retryArguments.childField = safeArgs.childField;
+  }
+
+  if (safeArgs.relationType) {
+    retryArguments.relationType = safeArgs.relationType;
+  }
+
   return retryArguments;
 }
 
@@ -522,26 +537,39 @@ function loadSourceDocument(safeArgs) {
 }
 
 function resolveMarkdownChildRelation(sourceDocument, safeArgs) {
-  let candidates = sourceDocument.designDoc.relations.filter((relation) => relation.mainTableName === safeArgs.tableName);
-  if (safeArgs.childTableName) {
-    candidates = candidates.filter((relation) => relation.childTableName === safeArgs.childTableName);
-  }
-
-  if (!candidates.length) {
-    const relationCandidates = getRelationCandidates(sourceDocument.designDoc, safeArgs.tableName);
-    const message = relationCandidates.length
-      ? 'Could not resolve child relation for main table ' + safeArgs.tableName + ' from Markdown design file.'
-      : 'No child relation was found for main table ' + safeArgs.tableName + ' in Markdown design file.';
-    throw createRelationResolutionError(message, safeArgs, sourceDocument.path, relationCandidates, safeArgs.childTableName, 'unresolved');
-  }
-
-  if (candidates.length > 1) {
-    const relationCandidates = candidates.map(formatRelationCandidate);
-    const message = 'Multiple child relations matched main table ' + safeArgs.tableName + '. Provide childTableName to disambiguate.';
-    throw createRelationResolutionError(message, safeArgs, sourceDocument.path, relationCandidates, safeArgs.childTableName, 'ambiguous');
+  const missingFields = ['childTableName', 'mainField', 'childField'].filter((field) => !safeArgs[field]);
+  if (missingFields.length) {
+    const message =
+      'master_child_jump requires externally provided relation fields. Missing: ' +
+      missingFields.join(', ') +
+      '.';
+    const error = new Error(message);
+    error.details = {
+      type: 'relation_input_required',
+      status: 'missing_required_relation_input',
+      tableName: safeArgs.tableName,
+      designFile: sourceDocument.path,
+      message,
+      requiredFields: ['childTableName', 'mainField', 'childField'],
+      correctionEntry: {
+        fields: ['childTableName', 'mainField', 'childField'],
+        example: {
+          ...buildRetryArguments(safeArgs, sourceDocument.path, safeArgs.childTableName || '<child_table_name>'),
+          mainField: safeArgs.mainField || '<main_field>',
+          childField: safeArgs.childField || '<child_field>',
+        },
+      },
+    };
+    throw error;
   }
 
-  return candidates[0];
+  return {
+    mainTableName: safeArgs.tableName,
+    childTableName: safeArgs.childTableName,
+    mainField: safeArgs.mainField,
+    childField: safeArgs.childField,
+    relationType: safeArgs.relationType || '',
+  };
 }
 
 function getStylePreset(styleId) {
@@ -644,7 +672,7 @@ function renderFormField(field) {
     return [
       '          <el-col :span="12" class="mb20">',
       `            <el-form-item label="${label}" prop="${prop}">`,
-      `              <el-select v-model="form.${prop}" placeholder="Please select ${label}" style="width: 100%">`,
+      `              <el-select v-model="form.${prop}" placeholder="请选择${label}" style="width: 100%">`,
       `                <el-option v-for="item in ${field.dictType}" :key="item.value" :label="item.label" :value="Number(item.value)" />`,
       '              </el-select>',
       '            </el-form-item>',
@@ -658,7 +686,7 @@ function renderFormField(field) {
     return [
       '          <el-col :span="12" class="mb20">',
       `            <el-form-item label="${label}" prop="${prop}">`,
-      `              <el-input-number v-model="form.${prop}" :min="0"${max}${precision} placeholder="Please input ${label}" style="width: 100%" />`,
+      `              <el-input-number v-model="form.${prop}" :min="0"${max}${precision} placeholder="请输入${label}" style="width: 100%" />`,
       '            </el-form-item>',
       '          </el-col>',
     ].join('\n');
@@ -670,7 +698,7 @@ function renderFormField(field) {
     return [
       '          <el-col :span="12" class="mb20">',
       `            <el-form-item label="${label}" prop="${prop}">`,
-      `              <el-date-picker type="${pickerType}" placeholder="Please select ${label}" v-model="form.${prop}" :value-format="${formatName}" style="width: 100%"></el-date-picker>`,
+      `              <el-date-picker type="${pickerType}" placeholder="请选择${label}" v-model="form.${prop}" :value-format="${formatName}" style="width: 100%"></el-date-picker>`,
       '            </el-form-item>',
       '          </el-col>',
     ].join('\n');
@@ -680,7 +708,7 @@ function renderFormField(field) {
     return [
       '          <el-col :span="24" class="mb20">',
       `            <el-form-item label="${label}" prop="${prop}">`,
-      `              <el-input type="textarea" v-model="form.${prop}" placeholder="Please input ${label}" />`,
+      `              <el-input type="textarea" v-model="form.${prop}" placeholder="请输入${label}" />`,
       '            </el-form-item>',
       '          </el-col>',
     ].join('\n');
@@ -689,7 +717,7 @@ function renderFormField(field) {
   return [
     '          <el-col :span="12" class="mb20">',
     `            <el-form-item label="${label}" prop="${prop}">`,
-    `              <el-input v-model="form.${prop}" placeholder="Please input ${label}" />`,
+    `              <el-input v-model="form.${prop}" placeholder="请输入${label}" />`,
     '            </el-form-item>',
     '          </el-col>',
   ].join('\n');
@@ -854,6 +882,9 @@ function ensureArguments(input) {
     tableName: String(input.tableName),
     style,
     childTableName: input.childTableName ? String(input.childTableName) : null,
+    mainField: input.mainField ? String(input.mainField) : null,
+    childField: input.childField ? String(input.childField) : null,
+    relationType: input.relationType ? String(input.relationType) : '',
     frontendPath: String(input.frontendPath),
     moduleName: input.moduleName ? String(input.moduleName) : 'admin/test',
     writeToDisk: input.writeToDisk === undefined ? true : Boolean(input.writeToDisk),
@@ -875,7 +906,6 @@ function maybeWriteFiles(files, writeToDisk, overwrite) {
 }
 
 function buildManifest(model, safeArgs, stylePreset, sharedTemplates, files, note) {
-  const relationCandidates = getRelationCandidates(loadSourceDocument(safeArgs).designDoc, safeArgs.tableName);
   return {
     mode: 'local-template',
     style: safeArgs.style,
@@ -901,17 +931,21 @@ function buildManifest(model, safeArgs, stylePreset, sharedTemplates, files, not
       : null,
     relationResolution: model.child
       ? {
-          status: 'resolved',
+          status: 'provided',
           tableName: safeArgs.tableName,
           designFile: model.designFile,
-          message: 'The relation was resolved from the design file. If you need another child table, use correctionEntry.retryArguments to resubmit.',
+          source: 'arguments',
+          message: 'The relation was provided by the caller. MCP skipped design-doc relation inference and generated files directly.',
           selected: formatRelationCandidate({
             childTableName: model.child.tableName,
             mainField: model.child.mainField.fieldName,
             childField: model.child.childField.fieldName,
             relationType: model.child.relationType || '',
           }),
-          correctionEntry: buildRelationCorrectionEntry(safeArgs, model.designFile, relationCandidates, model.child.tableName),
+          correctionEntry: {
+            fields: ['childTableName', 'mainField', 'childField'],
+            example: buildRetryArguments(safeArgs, model.designFile, model.child.tableName),
+          },
         }
       : null,
     summary: {
@@ -962,7 +996,7 @@ async function onMessage(message) {
   }
 
   if (method === 'tools/list') {
-    writeMessage(successResponse(id, { tools: [{ name: TOOL_NAME, description: 'Generate Worsoft frontend files and menu SQL from a local Markdown design file with style-based local templates. In master_child_jump mode, relations are inferred from the Markdown design file.', inputSchema: TOOL_SCHEMA }] }));
+    writeMessage(successResponse(id, { tools: [{ name: TOOL_NAME, description: 'Generate Worsoft frontend files and menu SQL from a local Markdown design file with style-based local templates. In master_child_jump mode, the caller must provide childTableName, mainField, and childField.', inputSchema: TOOL_SCHEMA }] }));
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worsoft-frontend-codegen-local-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Worsoft frontend local-template code generation MCP server.",
   "license": "UNLICENSED",
   "author": "worsoft <sw@worsoft.vip>",