我们常常会遇到一个让人哭笑不得的场景：你满怀期待地kan着AI帮你写代码，结果它一本正经地给你胡编乱造了一堆不存在的属性。特别是在低代码平台或者复杂的业务组件库开发中，这种现象简直是灾难性的。AI并不懂你们公司那个封装了三层的“Button”到底支持什么参数，它只Neng凭借训练数据里那些通用的React知识去瞎猜。

怎么破局？这就不得不提Zui近在技术圈火起来的MCP协议了。今天我们就来聊聊如何通过构建一套工业级的MCP Server，让AI学会“按需阅读”，精准地获取文档、源码和类型定义，彻底告别幻觉。

一、 架构哲学：为什么我们选择“Tool-Only”模式？

在深入代码之前，我们得先达成一个共识。MCP协议虽然提供了“握手”、“工具”、“资源”、“提示词”这四种Neng力，但经过我大量的实战测试，发现目前的AI IDE生态对“工具”的支持度远超其他。AI Agentgeng倾向于在遇到问题时主动发起函数调用，而不是像个被动的接收器一样去读取挂载的静态文件。

所以我们这里要纠正一个概念：别太迷信标准的Resources接口。为了稳健和高效，我们将摒弃传统的资源读取方式，把所有Neng力封装成三个核心Tool，构建一套“主动检索”体系。这就好比给AI装上了“手”和“眼”，让它Neng自己去翻书，而不是我们硬塞给它kan。

1.1 源码同步：Git Submodule的艺术

我们的MCP Server通常是一个独立运行的项目，但它必须时刻“盯着”主业务组件库的变动。Ru果靠手动复制粘贴代码来同步文档，那不仅效率低下还极易导致版本滞后AI给出的建议永远是过时的。

这里有个Zui佳实践：使用Git Submodule。

在MCP项目的根目录下我们Ke以把业务组件库挂载到vendor目录中。这样Zuo的好处是解耦与实时性。MCP Server只是组件库的一个“观察者”，而不是持有者。当主仓库geng新了组件，你只需要在Server项目里简单拉取一下 submodule，数据就是Zui新的了。

操作起来非常简单，几行命令就Neng搞定：

mkdir vendor
git submodule add :frontend/chun-components.git vendor/chun-components

搞定之后你的目录结构大概会变成这样，清晰明了：

mcp-server/
├── vendor/
│   └── chun-components/  # 👈 真实源码就在这里安家
│       ├── packages/
│       │   ├── chun-ui/  # 底层核心库 
│       │   └── app-ui/   # 业务封装层 
├── scripts/              # 数据生成脚本
└── index.js              # MCP Server 的入口

二、 构建知识库：从源码到结构化JSON

AI其实并不擅长直接阅读散落在数百个文件中的.tsx源码。原始源码里夹杂了大量的渲染逻辑、状态管理，这些对于AI来说全是干扰信息，不仅消耗Token，还容易让它“走神”。我们需要的是一份经过清洗、提炼过的API字典。

2.1 自动化提取：react-docgen-typescript的威力

为了把TypeScript定义变成AINeng读懂的结构化JSON，我们需要编写一个脚本，比如叫scripts/gen-mcp-docs.js。这里我们就要请出神器react-docgen-typescript了。

这里有个关键点：配置过滤器。我们一定要把那些原生的DOM属性过滤掉。为什么？因为不希望AI在写低代码配置时还去关注这些通用的HTML属性，这既浪费Token又容易引发幻觉。我们只关心业务属性。

核心逻辑大概是这样：

// scripts/gen-mcp-docs.js
import { parse } from 'react-docgen-typescript';
import { globSync } from 'glob';
import path from 'path';
import fs from 'fs';
// 1. 配置过滤器：只保留业务属性，过滤原生 DOM 属性
const options = {
    savePropValueAsString: true,
    propFilter:  => {
        // Ru果属性来自 node_modules，大概率是原生属性，直接丢弃
        if ) {
            return false; 
        }
        return true; 
    }
};
// 2. 扫描并解析
const docsMap = {};
// 假设我们的组件dou在这个目录下
const filePaths = globSync;
filePaths.forEach(filePath => {
    const docs = parse;
    docs.forEach(doc => {
        // 生成 key-value 结构，存入内存
        docsMap = {
            description: doc.description,
            props: doc.props, // 包含 type, required, description, defaultValue
            relativePath: path.relative // 留存路径，为后续源码降级Zuo准备
        };
    });
});
// 3. 落盘，生成 AI 的“组件字典”
fs.writeFileSync);

运行完这个脚本，我们就得到了一份沉甸甸的data/chun-docs.json。这就是AI的“新华字典”，以后它查属性就靠这个了。

2.2 别名映射：解决“名不副实”的难题

低代码场景中有个独有的痛点：名字对不上。

比如在低代码平台的Schema里组件写的是widget: "TextArea"，但在底层代码里它其实是export class ChunTextArea。Ru果AI拿着“TextArea”去查上面的字典，肯定会查无此人，然后就开始瞎编了。

我们需要一张“藏宝图”，告诉AI：“当你kan到TextArea时别慌，去查ChunTextArea的文档。”

我们Ke以编写scripts/scan-imports.js，通过静态分析业务库的入口文件，自动建立这份映射。

// scripts/scan-imports.js
// 正则：穿透封装层，直接找到 @chun/XXX 底层组件
const IMPORT_CORE_REGEX = /import\s+\{\s*\s*\}\s+from\s+@chun\/+/;
// ...  ...
if  {
    const publicName = "TextArea"; // 来自 index.ts 的导出名
    const coreName = coreMatch; // 提取出的 "ChunTextArea"
    mapping = coreName;
}

脚本跑完后会生成data/component-alias.json，长这样：

{
  "TextArea": "ChunTextArea",
  "Select": "ChunSelect",
  "UserPicker": "ChunUserSelect"
}

有了这份Docs和Alias，我们的MCP Server就具备了“懂行”的基础。

三、 核心引擎：四级跳查询策略

有了数据，接下来就是怎么用。这是本Server的“皇冠明珠”。我们设计的get_component_props工具，绝不仅仅是一个简单的Key-Value查表器，而是一个带有四级容错策略的检索引擎。

当AI在低代码Schema中kan到widget: "TextArea"并询问属性时这个工具会执行以下逻辑：

Level 1

Zui简单的情况。输入是ChunTextArea吗？Ru果是直接去内存里查docsMap，秒回结果。

Level 2

这是配合我们第三节“四级跳查询”的关键。输入是TextArea吗？去查aliasMap，发现它映射到ChunTextArea，然后返回ChunTextArea的文档。

Level 3

Ru果输入是Button，但没查到？系统会尝试自动补全前缀，比如变成ChunButton，再试一次。这招对付那些没显式配置别名的组件hen管用。

Level 4

有时候开发者手滑，输入了textarea。我们的索引里Zuo了预处理，把所有keydou转成了小写存了一份。所以这一层Neng通过转小写查表来命中。

这实际上是构建了一个只读的内存数据库，它保证了AI的查询是毫秒级响应的，不消耗任何IO等待时间。

核心代码实现大概是这样的：

// 定义内存缓存
let docsMap = {};       // 核心文档库
let lookupMap = {};     // 影子索引 
let aliasMap = {};      // 别名映射表 
// 预处理：构建全方位的索引
Object.keys.forEach(alias => {
    // 1. 存原始映射: "TextArea" -> "ChunTextArea"
    // 2. 存小写映射: "textarea" -> "ChunTextArea" 
    aliasMap = aliasMap;
});

3.1 返回数据的玄机：Meta信息

我们在返回文档时不仅仅返回props定义，还注入了Meta信息。这告诉AI：“虽然你查的是A，但我给你的是B”。这Neng有效防止AI产生幻觉。

// Tool 实现片段
const responseText = {
    _meta: {
        query: inputName,         // AI 查的词: "TextArea"
        resolvedTo: targetCoreName, // 实际解析为: "ChunTextArea"
        source: "alias_mapping"
    },
    ...doc // 展开 props 定义
};

四、 兜底机制：源码降级与文件穿透

Ru果组件文档没生成，或者是第三方库，AI该怎么办？

我们提供了一个“文件系统穿透”工具read_component_source。它不仅Neng读取vendor下的自研代码，还Neng通过白名单机制读取node_modules。

这给了AI极其强大的自救Neng力。当文档查询失败时Prompt会引导AI：“请尝试直接读取node_modules下的.d.ts类型定义文件。”

逻辑如下：

Ru果是chun-ui/src/... -> 去vendor目录找。

Ru果是antd/lib/... -> 去node_modules目录找。

通过这三个工具，我们形成了一个完美的闭环。

五、 规范页面分析逻辑：上下文合并

这是低代码场景中Zui复杂的逻辑：上下文合并。

页面配置通常一部分存在数据库里另一部分写在前端代码里。AI必须懂得如何将这两者合并，否则就会逻辑混乱。

比如数据库里配置了readonly: false，但前端代码里强行覆写了readonly: true。AIRu果不kan代码，只kan数据库，生成的逻辑就是错的。

我们的SOP设计如下：

触发：kan到ChunPageParser pageCode="..."。

动作：立即调用get_page_detail_by_code抓取Schema。

获取上下文：拿到组件名TextArea。

智Neng查询：调用get_component_props，映射为ChunTextArea并获取文档。

合并：代码中的customProps优先级高于Schema。Ru果代码里写了readonly: true，哪怕数据库里是false，也要以代码为准。

六、 提示词策略：强制AI遵守规则

Zui后我们需要编写一份工业级的提示词协议，强制AI遵守我们的游戏规则。

在Prompt的开头，必须明确禁止AI进行“无根据的推断”。我们采用Tool-Only Mode，意味着一切信息获取必须经过工具。

❌ 禁止：禁止 AI 凭借训练数据中的通用 React 知识来猜测组件属性。
✅ 强制：遇到组件，必须调用 get_component_props。

比如当AI遇到TextArea等简写时无需猜测。直接调用get_component_props。工具会自动将其映射为ChunTextArea并返回标准文档。AI需要根据返回结果中的_meta.resolvedTo字段来理解组件的真实身份。

将上述逻辑整合，我们得到了这份Ke以直接投喂给Trae/OpenCode的Zui终版协议。哈哈，这个架构和之前两课小打小闹的实现不同，伴随着hen多的工程实践，应该geng具参考价值。

通过这套系统，我们不仅解决了AI“瞎猜”的问题，还建立了一套可 、可维护的知识管理体系。让AI真正成为我们代码库的专家，而不是一个只会背通用模板的实习生。

---