From 53b4fcb8425d70e9b436cde8c3de9ea6857311de Mon Sep 17 00:00:00 2001
From: Syngnat <yangguofeng919@gmail.com>
Date: Mon, 8 Jun 2026 17:06:58 +0800
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20feat(ai-mcp):=20=E8=A1=A5=E5=BC=BAM?=
 =?UTF-8?q?CP=E5=8F=82=E6=95=B0=E5=A1=AB=E5=86=99=E5=BC=95=E5=AF=BC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../components/ai/AIMCPServerCard.test.tsx    |  9 +-
 .../src/components/ai/AIMCPServerCard.tsx     | 91 +++++++++++++++++--
 2 files changed, 89 insertions(+), 11 deletions(-)

diff --git a/frontend/src/components/ai/AIMCPServerCard.test.tsx b/frontend/src/components/ai/AIMCPServerCard.test.tsx
index 9cf344a..ef97c58 100644
--- a/frontend/src/components/ai/AIMCPServerCard.test.tsx
+++ b/frontend/src/components/ai/AIMCPServerCard.test.tsx
@@ -6,7 +6,7 @@ import AIMCPServerCard from './AIMCPServerCard';
 import { buildOverlayWorkbenchTheme } from '../../utils/overlayWorkbenchTheme';
 
 describe('AIMCPServerCard', () => {
-  it('renders explicit MCP parameter hints and the actual launch preview for command, args, and env', () => {
+  it('renders explicit MCP parameter hints, required badges, and the actual launch preview for command, args, and env', () => {
     const markup = renderToStaticMarkup(
       <AIMCPServerCard
         server={{
@@ -34,11 +34,18 @@ describe('AIMCPServerCard', () => {
     );
 
     expect(markup).toContain('启动命令只填可执行程序本身');
+    expect(markup).toContain('推荐填写顺序');
+    expect(markup).toContain('小白用户可以按这个顺序填');
+    expect(markup).toContain('必填');
+    expect(markup).toContain('可选');
+    expect(markup).toContain('固定');
     expect(markup).toContain('直接粘贴完整命令');
     expect(markup).toContain('自动拆分到下方字段');
     expect(markup).toContain('每个参数单独录入一个标签');
     expect(markup).toContain('每行一个 KEY=VALUE');
     expect(markup).toContain('没有等号或 key 含空格的行不会保存');
+    expect(markup).toContain('不要把 node server.js --stdio 整串都塞进这里');
+    expect(markup).toContain('不要写 export');
     expect(markup).toContain('当前阶段只支持 stdio');
     expect(markup).toContain('实际启动命令预览');
     expect(markup).toContain('node server.js --stdio');
diff --git a/frontend/src/components/ai/AIMCPServerCard.tsx b/frontend/src/components/ai/AIMCPServerCard.tsx
index 55ccf89..574440d 100644
--- a/frontend/src/components/ai/AIMCPServerCard.tsx
+++ b/frontend/src/components/ai/AIMCPServerCard.tsx
@@ -33,6 +33,29 @@ const hintStyle = (mutedText: string): React.CSSProperties => ({
   lineHeight: 1.6,
 });
 
+const buildFieldTone = (kind: 'required' | 'optional' | 'fixed', darkMode: boolean) => {
+  switch (kind) {
+    case 'required':
+      return {
+        label: '必填',
+        color: '#b45309',
+        bg: darkMode ? 'rgba(245,158,11,0.18)' : 'rgba(245,158,11,0.12)',
+      };
+    case 'fixed':
+      return {
+        label: '固定',
+        color: '#2563eb',
+        bg: darkMode ? 'rgba(59,130,246,0.18)' : 'rgba(59,130,246,0.12)',
+      };
+    default:
+      return {
+        label: '可选',
+        color: '#475569',
+        bg: darkMode ? 'rgba(148,163,184,0.18)' : 'rgba(148,163,184,0.12)',
+      };
+  }
+};
+
 const MCP_COMMAND_EXAMPLES = [
   'uvx mcp-server-fetch',
   'node server.js --stdio',
@@ -57,11 +80,29 @@ const MCPHelpBlock: React.FC<{
   title: string;
   description: string;
   overlayTheme: OverlayWorkbenchTheme;
+  darkMode: boolean;
+  fieldState: 'required' | 'optional' | 'fixed';
   example?: string;
   children: React.ReactNode;
-}> = ({ title, description, overlayTheme, example, children }) => (
+}> = ({ title, description, overlayTheme, darkMode, fieldState, example, children }) => {
+  const tone = buildFieldTone(fieldState, darkMode);
+  return (
   <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
-    <div style={labelStyle}>{title}</div>
+    <div style={{ display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' }}>
+      <div style={labelStyle}>{title}</div>
+      <span
+        style={{
+          padding: '2px 8px',
+          borderRadius: 999,
+          fontSize: 11,
+          fontWeight: 700,
+          color: tone.color,
+          background: tone.bg,
+        }}
+      >
+        {tone.label}
+      </span>
+    </div>
     <div style={hintStyle(overlayTheme.mutedText)}>
       {description}
       {example ? (
@@ -72,7 +113,8 @@ const MCPHelpBlock: React.FC<{
     </div>
     {children}
   </div>
-);
+  );
+};
 
 export const AIMCPServerCard: React.FC<AIMCPServerCardProps> = ({
   server,
@@ -121,6 +163,35 @@ export const AIMCPServerCard: React.FC<AIMCPServerCardProps> = ({
         </div>
       </div>
 
+      <div style={{ padding: '12px 14px', borderRadius: 12, border: `1px solid ${cardBorder}`, background: darkMode ? 'rgba(255,255,255,0.03)' : 'rgba(255,255,255,0.76)', display: 'flex', flexDirection: 'column', gap: 8 }}>
+        <div style={{ ...labelStyle, color: overlayTheme.titleText }}>推荐填写顺序</div>
+        <div style={hintStyle(overlayTheme.mutedText)}>
+          小白用户可以按这个顺序填：先选上面的模板或粘整行命令，再确认下面的必填项，最后只在需要时补参数、环境变量和超时。
+        </div>
+        <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
+          {[
+            '1. 模板 / 完整命令',
+            '2. 服务名称',
+            '3. 启动命令',
+            '4. 命令参数（可选）',
+            '5. 环境变量 / 超时（按需）',
+          ].map((item) => (
+            <span
+              key={item}
+              style={{
+                padding: '4px 10px',
+                borderRadius: 999,
+                fontSize: 12,
+                color: overlayTheme.titleText,
+                background: darkMode ? 'rgba(255,255,255,0.06)' : 'rgba(15,23,42,0.05)',
+              }}
+            >
+              {item}
+            </span>
+          ))}
+        </div>
+      </div>
+
       <div style={{ padding: '12px', borderRadius: 12, border: `1px solid ${cardBorder}`, background: darkMode ? 'rgba(255,255,255,0.03)' : 'rgba(255,255,255,0.76)', display: 'flex', flexDirection: 'column', gap: 8 }}>
         <div style={{ ...labelStyle, color: overlayTheme.titleText }}>只有一条完整命令？</div>
         <div style={hintStyle(overlayTheme.mutedText)}>
@@ -148,7 +219,7 @@ export const AIMCPServerCard: React.FC<AIMCPServerCardProps> = ({
       </div>
 
       <div style={{ display: 'grid', gridTemplateColumns: 'minmax(0,1fr) 132px', gap: 12 }}>
-        <MCPHelpBlock title="服务名称" description="给这个 MCP 起一个你自己能识别的名字，后面 AI 工具列表里会直接显示。" overlayTheme={overlayTheme} example="Filesystem / Browser / GitHub">
+        <MCPHelpBlock title="服务名称" description="给这个 MCP 起一个你自己能识别的名字，后面 AI 工具列表里会直接显示；不要只写 server、test 这类看不出用途的名字。" overlayTheme={overlayTheme} darkMode={darkMode} fieldState="required" example="Filesystem / Browser / GitHub">
           <Input
             value={server.name}
             onChange={(event) => onChange({ name: event.target.value })}
@@ -156,7 +227,7 @@ export const AIMCPServerCard: React.FC<AIMCPServerCardProps> = ({
             style={{ borderRadius: 10, background: inputBg, border: `1px solid ${cardBorder}` }}
           />
         </MCPHelpBlock>
-        <MCPHelpBlock title="启用状态" description="临时不用可以先禁用，保留配置但不参与 AI 工具发现。" overlayTheme={overlayTheme}>
+        <MCPHelpBlock title="启用状态" description="临时不用可以先禁用，保留配置但不参与 AI 工具发现。" overlayTheme={overlayTheme} darkMode={darkMode} fieldState="optional">
           <Select
             value={server.enabled ? 'enabled' : 'disabled'}
             onChange={(value) => onChange({ enabled: value === 'enabled' })}
@@ -166,14 +237,14 @@ export const AIMCPServerCard: React.FC<AIMCPServerCardProps> = ({
       </div>
 
       <div style={{ display: 'grid', gridTemplateColumns: '132px minmax(0,1fr) 132px', gap: 12 }}>
-        <MCPHelpBlock title="传输方式" description="当前阶段只支持 stdio，表示 GoNavi 会在本机启动这个进程，并通过标准输入输出与它通信。" overlayTheme={overlayTheme}>
+        <MCPHelpBlock title="传输方式" description="当前阶段只支持 stdio，表示 GoNavi 会在本机启动这个进程，并通过标准输入输出与它通信。" overlayTheme={overlayTheme} darkMode={darkMode} fieldState="fixed">
           <Select
             value={server.transport}
             onChange={(value) => onChange({ transport: value as AIMCPServerConfig['transport'] })}
             options={[{ label: 'stdio', value: 'stdio' }]}
           />
         </MCPHelpBlock>
-        <MCPHelpBlock title="启动命令" description="这里只填命令本身；如果是 node/uvx/python 这类启动器，把脚本名或模块名放到下面的参数里。" overlayTheme={overlayTheme} example="node / uvx / python">
+        <MCPHelpBlock title="启动命令" description="这里只填命令本身；如果是 node/uvx/python 这类启动器，把脚本名或模块名放到下面的参数里。不要把 node server.js --stdio 整串都塞进这里。" overlayTheme={overlayTheme} darkMode={darkMode} fieldState="required" example="node / uvx / python">
           <Input
             value={server.command}
             onChange={(event) => onChange({ command: event.target.value })}
@@ -181,7 +252,7 @@ export const AIMCPServerCard: React.FC<AIMCPServerCardProps> = ({
             style={{ borderRadius: 10, background: inputBg, border: `1px solid ${cardBorder}` }}
           />
         </MCPHelpBlock>
-        <MCPHelpBlock title="超时(秒)" description="工具发现和工具调用单次最多等多久。远端服务或启动慢的脚本可以适当调大。" overlayTheme={overlayTheme} example="20">
+        <MCPHelpBlock title="超时(秒)" description="工具发现和工具调用单次最多等多久。大多数本机工具保持默认 20 秒即可；远端服务或启动慢的脚本再调大。" overlayTheme={overlayTheme} darkMode={darkMode} fieldState="optional" example="20">
           <Input
             type="number"
             min={3}
@@ -194,7 +265,7 @@ export const AIMCPServerCard: React.FC<AIMCPServerCardProps> = ({
         </MCPHelpBlock>
       </div>
 
-      <MCPHelpBlock title="命令参数" description="每个参数单独录入一个标签；命令本体不要填在这里。比如 node server.js --stdio，要把 server.js 和 --stdio 分开填。" overlayTheme={overlayTheme} example="server.js、--stdio、-m、your_mcp_server">
+      <MCPHelpBlock title="命令参数" description="每个参数单独录入一个标签；命令本体不要填在这里。比如 node server.js --stdio，要把 server.js 和 --stdio 分开填。不确定怎么拆时，优先回到上面的“完整命令”框自动拆分。" overlayTheme={overlayTheme} darkMode={darkMode} fieldState="optional" example="server.js、--stdio、-m、your_mcp_server">
         <Select
           mode="tags"
           value={server.args || []}
@@ -216,7 +287,7 @@ export const AIMCPServerCard: React.FC<AIMCPServerCardProps> = ({
         </div>
       )}
 
-      <MCPHelpBlock title="环境变量" description="每行一个 KEY=VALUE，通常用于 API Key、工作目录、服务地址等配置；不需要时可以留空。" overlayTheme={overlayTheme} example="OPENAI_API_KEY=...">
+      <MCPHelpBlock title="环境变量" description="每行一个 KEY=VALUE，通常用于 API Key、工作目录、服务地址等配置；不需要时可以留空。这里只填变量本身，不要写 export，也不要把它和启动命令混成一整行。" overlayTheme={overlayTheme} darkMode={darkMode} fieldState="optional" example="OPENAI_API_KEY=...">
         <Input.TextArea
           rows={3}
           value={envDraft}