@zat-design/sisyphus-react-mcp 1.0.2 → 4.5.7

package/src/index.mjs

@@ -2,326 +2,473 @@
 /**
  * @zat-design/sisyphus-react MCP server。
  *
- * stdio 传输，启动时加载包内随附的 AI 元数据 JSON（meta/），离线可用。
- * 向 AI 编码助手暴露四个查询工具：
- *   sisyphus-list-components / sisyphus-get-component-api / sisyphus-get-examples / sisyphus-search
- * 返回内容经脱水压缩（去呈现噪声、双语保留中文、去重），降低 token 占用。
+ * 服务读取包内同版本 AI 元数据，并校验当前业务项目安装的
+ * @zat-design/sisyphus-react 与 MCP 完全同版。
  */
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const META_DIR = path.resolve(__dirname, '..', 'meta');
+const SUPPORTED_SCHEMA_VERSION = 2;
+const PACKAGE_ROOT = path.dirname(fileURLToPath(new URL('../package.json', import.meta.url)));
+const PACKAGE_VERSION = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'),
+).version;
 
-// ---------- 元数据加载（缺失/损坏时显式报错，不静默返回空）----------
+function resolveMetaDir() {
+  if (process.env.SISYPHUS_META_DIR) return path.resolve(process.env.SISYPHUS_META_DIR);
+  return path.join(PACKAGE_ROOT, 'meta');
+}
 
-/** 读取并校验一个元数据 JSON。 */
-function loadMeta(file) {
-  const fp = path.join(META_DIR, file);
-  if (!fs.existsSync(fp)) {
-    throw new Error(`[sisyphus-mcp] 元数据文件缺失: ${fp}。请确认包内 meta/ 目录完整。`);
-  }
-  let parsed;
+function resolveComponentPackage() {
   try {
-    parsed = JSON.parse(fs.readFileSync(fp, 'utf8'));
-  } catch (err) {
-    throw new Error(`[sisyphus-mcp] 元数据文件损坏，无法解析 JSON: ${fp}（${err.message}）`);
+    const projectRequire = createRequire(path.join(process.cwd(), 'package.json'));
+    let current = path.dirname(projectRequire.resolve('@zat-design/sisyphus-react'));
+    while (current !== path.dirname(current)) {
+      const packageFile = path.join(current, 'package.json');
+      if (fs.existsSync(packageFile)) {
+        const packageJson = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+        if (packageJson.name === '@zat-design/sisyphus-react') {
+          return { version: packageJson.version, file: packageFile };
+        }
+      }
+      current = path.dirname(current);
+    }
+    throw new Error('已解析入口，但未找到组件包 package.json');
+  } catch (error) {
+    throw new Error(
+      '[sisyphus-mcp] 无法从当前项目解析 @zat-design/sisyphus-react。' +
+        '请确认业务项目已安装组件库。' +
+        `原始错误：${error.message}`,
+    );
   }
-  return parsed;
 }
 
-const COMPONENTS_META = loadMeta('components.json');
-const PROPS_META = loadMeta('props.json');
-const EXAMPLES_META = loadMeta('examples.json');
+function parseJson(file) {
+  if (!fs.existsSync(file)) throw new Error(`[sisyphus-mcp] 元数据文件缺失: ${file}`);
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new Error(`[sisyphus-mcp] 元数据 JSON 损坏: ${file}（${error.message}）`);
+  }
+}
 
-const VERSION = COMPONENTS_META.version || 'unknown';
-const COMPONENTS = COMPONENTS_META.components || [];
-const PROPS = PROPS_META.components || {};
-const EXAMPLES = EXAMPLES_META.examples || [];
+function loadMeta() {
+  const componentPackage = resolveComponentPackage();
+  const dir = resolveMetaDir();
+  const manifest = parseJson(path.join(dir, 'manifest.json'));
+  if (manifest.schemaVersion !== SUPPORTED_SCHEMA_VERSION) {
+    throw new Error(
+      `[sisyphus-mcp] 不支持元数据 schema v${manifest.schemaVersion}，` +
+        `当前 MCP 支持 v${SUPPORTED_SCHEMA_VERSION}`,
+    );
+  }
+  if (manifest.version !== PACKAGE_VERSION) {
+    throw new Error(
+      `[sisyphus-mcp] 版本不一致：MCP v${PACKAGE_VERSION}，` +
+        `内置元数据 v${manifest.version}。请重新构建并发布同版 MCP。`,
+    );
+  }
+  if (componentPackage.version !== PACKAGE_VERSION) {
+    throw new Error(
+      `[sisyphus-mcp] 版本不一致：MCP v${PACKAGE_VERSION}，` +
+        `项目组件库 v${componentPackage.version}。请安装完全相同版本的三包。`,
+    );
+  }
+  const result = { dir, manifest, componentPackage };
+  for (const name of ['components', 'props', 'examples', 'types']) {
+    const fileName = `${name}.json`;
+    const full = path.join(dir, fileName);
+    if (!fs.existsSync(full)) throw new Error(`[sisyphus-mcp] 元数据文件缺失: ${full}`);
+    const raw = fs.readFileSync(full, 'utf8').trimEnd();
+    const hash = crypto.createHash('sha256').update(raw).digest('hex');
+    if (manifest.files?.[fileName] !== hash) {
+      throw new Error(`[sisyphus-mcp] 元数据校验失败: ${fileName}`);
+    }
+    const parsed = parseJson(full);
+    if (parsed.schemaVersion !== manifest.schemaVersion || parsed.version !== manifest.version) {
+      throw new Error(`[sisyphus-mcp] 元数据版本不一致: ${fileName}`);
+    }
+    result[name] = parsed;
+  }
+  return result;
+}
 
-if (!COMPONENTS.length) {
-  throw new Error('[sisyphus-mcp] 元数据为空：components.json 不含任何组件，拒绝启动。');
+let META;
+try {
+  META = loadMeta();
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
 }
+const VERSION = META.componentPackage.version;
+const COMPONENTS = META.components.components || [];
+const PROPS = META.props.components || {};
+const EXAMPLES = META.examples.examples || [];
+const TYPES = META.types.types || [];
 
-// ---------- 脱水/压缩工具（供各工具复用）----------
+if (!COMPONENTS.length) throw new Error('[sisyphus-mcp] 组件元数据为空，拒绝启动');
 
-/** 折叠多余空行、去首尾空白。 */
-function dehydrateText(s) {
-  if (!s) return '';
-  return s
+function dehydrateText(value = '') {
+  return value
     .replace(/\r\n/g, '\n')
     .replace(/\n{3,}/g, '\n\n')
     .trim();
 }
 
-/**
- * 双语去重：若描述同时含中英文，仅保留中文部分。
- * 简单策略——按句子拆分，剔除不含 CJK 字符的纯英文句子（保留含中文的）。
- * 全英文描述则原样保留。
- */
-function preferChinese(s) {
-  if (!s) return '';
-  const hasCJK = /[一-龥]/.test(s);
-  if (!hasCJK) return s.trim();
-  return s
-    .split(/(?<=[。；！？\n])/)
-    .map((seg) => seg.trim())
-    .filter((seg) => seg && /[一-龥]/.test(seg))
-    .join('')
-    .trim() || s.trim();
+function preferChinese(value = '') {
+  if (!/[\u4e00-\u9fa5]/.test(value)) return value.trim();
+  return (
+    value
+      .split(/(?<=[。；！？\n])/)
+      .map((part) => part.trim())
+      .filter((part) => part && /[\u4e00-\u9fa5]/.test(part))
+      .join('') || value.trim()
+  );
 }
 
-/** 组装一个 prop 的精简描述行。 */
 function formatProp(name, info) {
   const parts = [`- ${name}`];
   if (info.type) parts.push(`\`${info.type}\``);
-  if (info.required) parts.push('(必填)');
-  if (info.defaultValue !== undefined && info.defaultValue !== '')
+  if (info.required === true) parts.push('(必填)');
+  if (info.defaultValue !== undefined && info.defaultValue !== '') {
     parts.push(`默认 \`${info.defaultValue}\``);
-  const desc = preferChinese(dehydrateText(info.description || ''));
-  if (desc) parts.push(`— ${desc}`);
+  }
+  const description = preferChinese(dehydrateText(info.description || ''));
+  if (description) parts.push(`— ${description}`);
   return parts.join(' ');
 }
 
-/** 文本结果包装。 */
 function textResult(text) {
   return { content: [{ type: 'text', text }] };
 }
 
-/** Levenshtein 距离，用于「组件不存在」时给候选。 */
 function editDistance(a, b) {
-  const m = a.length;
-  const n = b.length;
-  const dp = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)]);
-  for (let j = 0; j <= n; j++) dp[0][j] = j;
-  for (let i = 1; i <= m; i++) {
-    for (let j = 1; j <= n; j++) {
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 0; j <= b.length; j++) dp[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
       dp[i][j] =
         a[i - 1] === b[j - 1]
           ? dp[i - 1][j - 1]
           : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
     }
   }
-  return dp[m][n];
+  return dp[a.length][b.length];
+}
+
+function componentNames(component) {
+  return [component.name, ...(component.aliases || [])];
+}
+
+function findComponent(name) {
+  const lower = name.toLowerCase();
+  return COMPONENTS.find((component) =>
+    componentNames(component).some((candidate) => candidate.toLowerCase() === lower),
+  );
 }
 
-/** 找最接近的组件名（用于纠错提示）。 */
 function nearestComponents(name, limit = 3) {
   const lower = name.toLowerCase();
-  return COMPONENTS.map((c) => ({ name: c.name, d: editDistance(lower, c.name.toLowerCase()) }))
-    .sort((a, b) => a.d - b.d)
+  return COMPONENTS.map((component) => ({
+    name: component.name,
+    distance: Math.min(
+      ...componentNames(component).map((candidate) => editDistance(lower, candidate.toLowerCase())),
+    ),
+  }))
+    .sort((a, b) => a.distance - b.distance)
     .slice(0, limit)
-    .map((x) => x.name);
+    .map((item) => item.name);
 }
 
-function findComponent(name) {
-  return COMPONENTS.find((c) => c.name.toLowerCase() === name.toLowerCase());
+function exampleMatches(example, keyword) {
+  if (!keyword) return true;
+  const value = keyword.toLowerCase();
+  return [example.id, example.file, example.title, example.note].some((field) =>
+    (field || '').toLowerCase().includes(value),
+  );
 }
 
-// ---------- MCP server 与工具 ----------
+const server = new McpServer({ name: '@zat-design/sisyphus-react-mcp', version: VERSION });
 
-const server = new McpServer({
-  name: '@zat-design/sisyphus-react-mcp',
-  version: VERSION,
-});
-
-// 1) sisyphus-list-components
 server.registerTool(
   'sisyphus-list-components',
   {
     title: '列出组件',
-    description: `列出 @zat-design/sisyphus-react (v${VERSION}) 的全部组件及其业务域分类与一句话描述。`,
+    description: `列出 @zat-design/sisyphus-react (v${VERSION}) 全部稳定业务组件。`,
     inputSchema: z.object({}),
   },
   async () => {
     const lines = COMPONENTS.map(
-      (c) => `- ${c.name}（${c.category || '未分类'}）：${preferChinese(c.description) || '—'}`,
+      (component) =>
+        `- ${component.name}（${component.category}）：${preferChinese(component.description) || '—'}`,
     );
     return textResult(
-      `sisyphus-react v${VERSION} 组件清单（共 ${COMPONENTS.length}）：\n\n${lines.join('\n')}`,
+      `sisyphus-react v${VERSION} 业务组件（${COMPONENTS.length} 个）：\n\n${lines.join('\n')}`,
     );
   },
 );
 
-// 2) sisyphus-get-component-api
 server.registerTool(
   'sisyphus-get-component-api',
   {
     title: '查询组件 API',
-    description:
-      '按组件名返回其 props/fieldProps 与配置式约定枚举（type/valueType/names 等）。默认不内联示例，示例请用 sisyphus-get-examples。',
-    inputSchema: z.object({
-      name: z.string().describe('组件名，如 ProForm / ProSelect / ProEditTable'),
-    }),
+    description: '返回组件 API 分组、TypeScript 类型、必填性、默认值与配置约定。',
+    inputSchema: z.object({ name: z.string().describe('组件名，如 ProForm') }),
   },
   async ({ name }) => {
-    const comp = findComponent(name);
-    if (!comp) {
-      const candidates = nearestComponents(name);
-      return textResult(
-        `未找到组件「${name}」。最接近的候选：${candidates.join('、')}。可用 sisyphus-list-components 查看全部。`,
-      );
-    }
-    const entry = PROPS[comp.name];
-    const out = [`# ${comp.name}（${comp.category || '未分类'}）v${VERSION}`];
-    if (comp.description) out.push(preferChinese(comp.description));
-    out.push(`导入：\`import { ${comp.name} } from '${comp.importPath}'\``);
-
-    if (!entry) {
-      out.push('\n（暂无 API 元数据）');
-      return textResult(out.join('\n'));
+    const component = findComponent(name);
+    if (!component) {
+      return textResult(`未找到组件「${name}」。最接近：${nearestComponents(name).join('、')}。`);
     }
-
-    // props：docs-api 分组形式 或 ts-interface 扁平形式
-    if (entry.source === 'docs-api' && entry.groups) {
-      for (const g of entry.groups) {
-        const props = Object.entries(g.props || {});
-        if (!props.length) continue;
-        out.push(`\n## ${g.title}`);
-        for (const [pn, info] of props) out.push(formatProp(pn, info));
-      }
-    } else if (entry.props) {
-      const props = Object.entries(entry.props);
-      if (props.length) {
-        out.push('\n## Props');
-        for (const [pn, info] of props) out.push(formatProp(pn, info));
-      }
+    const entry = PROPS[component.name];
+    const output = [
+      `# ${component.name}（${component.category}）v${VERSION}`,
+      preferChinese(component.description),
+      `导入：\`import { ${component.name} } from '${component.importPath}'\``,
+      `Props 类型：\`${component.propsType}\``,
+    ].filter(Boolean);
+    for (const group of entry?.groups || []) {
+      const props = Object.entries(group.props || {});
+      if (!props.length) continue;
+      output.push(`\n## ${group.title}${group.typeName ? `（\`${group.typeName}\`）` : ''}`);
+      for (const [propName, info] of props) output.push(formatProp(propName, info));
     }
-
-    // 配置式约定枚举
-    const conv = entry.conventions || {};
-    const convKeys = Object.keys(conv);
-    if (convKeys.length) {
-      out.push('\n## 配置式约定');
-      for (const key of convKeys) {
-        const c = conv[key];
-        out.push(`\n### ${key}`);
-        if (c.description) out.push(preferChinese(c.description));
-        if (c.example) out.push(`示例：\`${c.example}\``);
-        if (c.values) {
-          for (const v of c.values) out.push(`- \`${v.value}\`${v.desc ? ` — ${v.desc}` : ''}`);
-        }
-        if (c.ref) out.push(`（同 ${c.ref} 约定）`);
+    for (const [key, convention] of Object.entries(entry?.conventions || {})) {
+      output.push(`\n## 配置约定：${key}`);
+      if (convention.description) output.push(preferChinese(convention.description));
+      if (convention.example) output.push(`示例：\`${convention.example}\``);
+      for (const value of convention.values || []) {
+        output.push(`- \`${value.value}\`${value.desc ? ` — ${value.desc}` : ''}`);
       }
+      if (convention.ref) output.push(`参考：${convention.ref}`);
     }
-
-    return textResult(dehydrateText(out.join('\n')));
+    return textResult(dehydrateText(output.join('\n')));
   },
 );
 
-// 3) sisyphus-get-examples
+// 兼容旧工具：仍按组件/关键词返回所有匹配源码。新流程优先 list-examples + get-example。
 server.registerTool(
   'sisyphus-get-examples',
   {
-    title: '查询组件示例',
-    description: '按组件名（可选场景关键词）返回真实可运行的 demo 源码与标题。',
+    title: '查询组件示例（兼容）',
+    description: '按组件名和可选关键词返回 demo 源码；大量示例请优先使用 list/get-example。',
     inputSchema: z.object({
-      name: z.string().describe('组件名，如 ProEditTable'),
-      keyword: z.string().optional().describe('可选场景关键词，按示例标题/说明过滤，如「虚拟」「异步」'),
+      name: z.string(),
+      keyword: z.string().optional(),
     }),
   },
   async ({ name, keyword }) => {
-    const comp = findComponent(name);
-    if (!comp) {
-      return textResult(
-        `未找到组件「${name}」。最接近的候选：${nearestComponents(name).join('、')}。`,
-      );
-    }
-    let list = EXAMPLES.filter((e) => e.component.toLowerCase() === comp.name.toLowerCase());
-    if (keyword) {
-      const kw = keyword.toLowerCase();
-      list = list.filter(
-        (e) =>
-          (e.title || '').toLowerCase().includes(kw) ||
-          (e.note || '').toLowerCase().includes(kw) ||
-          (e.file || '').toLowerCase().includes(kw),
-      );
-    }
-    if (!list.length) {
-      return textResult(
-        `${comp.name} 未找到${keyword ? `匹配「${keyword}」的` : ''}示例。可去掉关键词重试。`,
-      );
-    }
-    const blocks = list.map((e) => {
-      const header = `## ${e.title}${e.note ? `\n${preferChinese(e.note)}` : ''}\n（${e.file}）`;
-      return `${header}\n\`\`\`tsx\n${e.source.trim()}\n\`\`\``;
-    });
-    return textResult(`# ${comp.name} 示例（${list.length} 个）\n\n${blocks.join('\n\n')}`);
+    const component = findComponent(name);
+    if (!component) return textResult(`未找到组件「${name}」。`);
+    const list = EXAMPLES.filter(
+      (example) => example.component === component.name && exampleMatches(example, keyword),
+    );
+    if (!list.length) return textResult(`${component.name} 未找到匹配示例。`);
+    const blocks = list.map(
+      (example) =>
+        `## ${example.title}\nID：\`${example.id}\`${example.note ? `\n${preferChinese(example.note)}` : ''}` +
+        `\n\`\`\`tsx\n${example.source.trim()}\n\`\`\``,
+    );
+    return textResult(`# ${component.name} 示例（${list.length} 个）\n\n${blocks.join('\n\n')}`);
   },
 );
 
-// 4) search
 server.registerTool(
-  'sisyphus-search',
+  'sisyphus-list-examples',
   {
-    title: '关键词搜索',
-    description: '按关键词跨组件清单、props 描述、示例标题检索，返回最相关的组件与能力定位。',
+    title: '分页列出示例',
+    description: '只返回 demo 索引，不内联源码。',
     inputSchema: z.object({
-      query: z.string().describe('自然语言关键词，如「日期范围拆成两个字段」「异步下拉」'),
+      name: z.string(),
+      keyword: z.string().optional(),
+      cursor: z.string().optional().describe('上次返回的 nextCursor'),
+      limit: z.number().int().min(1).max(50).default(20),
     }),
   },
-  async ({ query }) => {
-    const kw = query.toLowerCase();
-    const hits = [];
+  async ({ name, keyword, cursor, limit }) => {
+    const component = findComponent(name);
+    if (!component) return textResult(`未找到组件「${name}」。`);
+    const all = EXAMPLES.filter(
+      (example) => example.component === component.name && exampleMatches(example, keyword),
+    );
+    const offset = Number.parseInt(cursor || '0', 10);
+    if (!Number.isSafeInteger(offset) || offset < 0) return textResult('无效 cursor。');
+    const page = all.slice(offset, offset + limit);
+    const nextCursor = offset + page.length < all.length ? String(offset + page.length) : null;
+    const lines = page.map(
+      (example) =>
+        `- \`${example.id}\` — ${example.title}${example.note ? `：${preferChinese(example.note)}` : ''}`,
+    );
+    return textResult(
+      `# ${component.name} 示例索引（${offset + 1}-${offset + page.length} / ${all.length}）\n` +
+        `${lines.join('\n') || '（无匹配结果）'}\n\nnextCursor: ${nextCursor || 'null'}`,
+    );
+  },
+);
+
+server.registerTool(
+  'sisyphus-get-example',
+  {
+    title: '获取单个示例',
+    description: '按 list-examples 返回的稳定 ID 获取单个 demo 源码。',
+    inputSchema: z.object({ id: z.string() }),
+  },
+  async ({ id }) => {
+    const example = EXAMPLES.find((item) => item.id === id);
+    if (!example) return textResult(`未找到示例「${id}」，请先调用 sisyphus-list-examples。`);
+    return textResult(
+      `# ${example.component} / ${example.title}\nID：\`${example.id}\`` +
+        `${example.note ? `\n${preferChinese(example.note)}` : ''}` +
+        `\n\n\`\`\`tsx\n${example.source.trim()}\n\`\`\``,
+    );
+  },
+);
 
-    for (const c of COMPONENTS) {
-      const hay = [c.name, c.category, c.description, ...(c.whenToUse || [])]
-        .join(' ')
-        .toLowerCase();
-      if (hay.includes(kw)) hits.push(`组件 ${c.name}（${c.category}）：${preferChinese(c.description)}`);
+server.registerTool(
+  'sisyphus-get-type',
+  {
+    title: '查询公开 TypeScript 类型',
+    description: '返回从包根导出的准确 TypeScript 声明。',
+    inputSchema: z.object({ name: z.string().describe('如 ProFormColumnType') }),
+  },
+  async ({ name }) => {
+    const type = TYPES.find((item) => item.name.toLowerCase() === name.toLowerCase());
+    if (!type) {
+      const candidates = TYPES.map((item) => item.name)
+        .sort(
+          (a, b) =>
+            editDistance(name.toLowerCase(), a.toLowerCase()) -
+            editDistance(name.toLowerCase(), b.toLowerCase()),
+        )
+        .slice(0, 3);
+      return textResult(`未找到公开类型「${name}」。最接近：${candidates.join('、')}。`);
     }
+    const properties = Object.entries(type.properties || {});
+    return textResult(
+      `# ${type.name}\n来源：\`${type.source}\`${type.description ? `\n${type.description}` : ''}` +
+        `\n\n\`\`\`ts\n${type.declaration}\n\`\`\`` +
+        (properties.length
+          ? `\n\n## 展开属性\n${properties.map(([propertyName, info]) => formatProp(propertyName, info)).join('\n')}`
+          : ''),
+    );
+  },
+);
 
-    for (const [cn, entry] of Object.entries(PROPS)) {
-      const collectProps = entry.source === 'docs-api'
-        ? (entry.groups || []).flatMap((g) => Object.entries(g.props || {}))
-        : Object.entries(entry.props || {});
-      for (const [pn, info] of collectProps) {
-        if (`${pn} ${info.description || ''}`.toLowerCase().includes(kw)) {
-          hits.push(`${cn}.${pn} — ${preferChinese(info.description || '')}`);
-        }
-      }
-      // 约定命中：枚举值数组 + 约定描述（描述型约定如用法/反模式也可被检索）
-      for (const [convKey, conv] of Object.entries(entry.conventions || {})) {
-        for (const v of conv.values || []) {
-          if (`${v.value} ${v.desc || ''}`.toLowerCase().includes(kw)) {
-            hits.push(`${cn} 约定 ${convKey}=\`${v.value}\` — ${v.desc || ''}`);
-          }
-        }
-        if (conv.description && conv.description.toLowerCase().includes(kw)) {
-          hits.push(`${cn} 约定 ${convKey} — 详见 sisyphus-get-component-api`);
+function searchTerms(query) {
+  const normalized = query.toLowerCase().trim();
+  const terms = new Set([normalized, ...normalized.split(/\s+/).filter(Boolean)]);
+  const chinese = [...normalized].filter((char) => /[\u4e00-\u9fa5]/.test(char)).join('');
+  if (chinese.length >= 4) {
+    for (let i = 0; i < chinese.length - 1; i++) terms.add(chinese.slice(i, i + 2));
+  }
+  return [...terms].filter(Boolean);
+}
+
+server.registerTool(
+  'sisyphus-search',
+  {
+    title: '跨元数据搜索',
+    description: '按多关键词搜索组件、API、约定、类型和示例索引。',
+    inputSchema: z.object({ query: z.string().min(1) }),
+  },
+  async ({ query }) => {
+    const terms = searchTerms(query);
+    const hits = [];
+    const add = (text, haystack, weight = 1) => {
+      const lower = haystack.toLowerCase();
+      const score = terms.reduce((total, term) => total + (lower.includes(term) ? weight : 0), 0);
+      if (score) hits.push({ text, score });
+    };
+    for (const component of COMPONENTS) {
+      add(
+        `组件 ${component.name}（${component.category}）：${preferChinese(component.description)}`,
+        [
+          component.name,
+          ...(component.aliases || []),
+          component.category,
+          component.description,
+          ...(component.whenToUse || []),
+        ].join(' '),
+        3,
+      );
+    }
+    for (const [componentName, entry] of Object.entries(PROPS)) {
+      for (const group of entry.groups || []) {
+        for (const [propName, info] of Object.entries(group.props || {})) {
+          add(
+            `${componentName}.${propName} [${group.title}] — ${preferChinese(info.description || '')}`,
+            `${propName} ${group.title} ${info.type} ${info.description}`,
+            2,
+          );
         }
       }
-    }
-
-    for (const e of EXAMPLES) {
-      if (`${e.title} ${e.note}`.toLowerCase().includes(kw)) {
-        hits.push(`示例 ${e.component}「${e.title}」（${e.file}）→ sisyphus-get-examples 获取源码`);
+      for (const [key, convention] of Object.entries(entry.conventions || {})) {
+        add(
+          `${componentName} 约定 ${key} — 请查询组件 API`,
+          `${key} ${convention.description || ''} ${(convention.values || []).map((value) => `${value.value} ${value.desc}`).join(' ')}`,
+          3,
+        );
       }
     }
-
-    if (!hits.length) {
-      return textResult(`未检索到与「${query}」相关的内容。可尝试更通用的关键词或用 sisyphus-list-components。`);
-    }
-    // 去重
-    const unique = [...new Set(hits)];
-    return textResult(`检索「${query}」命中 ${unique.length} 条：\n\n${unique.join('\n')}`);
+    for (const type of TYPES)
+      add(
+        `类型 ${type.name} → sisyphus-get-type`,
+        `${type.name} ${type.description} ${type.declaration}`,
+        2,
+      );
+    for (const example of EXAMPLES)
+      add(
+        `示例 ${example.component}「${example.title}」 — \`${example.id}\``,
+        `${example.title} ${example.note} ${example.file}`,
+        1,
+      );
+    const unique = [
+      ...new Map(hits.sort((a, b) => b.score - a.score).map((hit) => [hit.text, hit])).values(),
+    ].slice(0, 30);
+    if (!unique.length) return textResult(`未检索到与「${query}」相关的内容。`);
+    return textResult(
+      `检索「${query}」命中 ${unique.length} 条（最多展示 30 条）：\n\n${unique.map((hit) => hit.text).join('\n')}`,
+    );
   },
 );
 
-// ---------- 启动 ----------
+server.registerTool(
+  'sisyphus-get-meta-status',
+  {
+    title: '查询元数据状态',
+    description: '返回当前业务项目的组件库版本、MCP 内置元数据 schema 和覆盖统计。',
+    inputSchema: z.object({}),
+  },
+  async () =>
+    textResult(
+      [
+        '# Sisyphus AI 元数据状态',
+        `- MCP 版本：${PACKAGE_VERSION}`,
+        `- 组件库版本：${VERSION}`,
+        `- schemaVersion：${META.manifest.schemaVersion}`,
+        `- 业务组件：${META.manifest.counts.components}`,
+        `- 文档 demo：${META.manifest.counts.examples}`,
+        `- 公开类型：${META.manifest.counts.types}`,
+        `- 元数据来源：MCP 内置 ${META.dir}`,
+      ].join('\n'),
+    ),
+);
 
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  // stdio 模式下日志走 stderr，避免污染协议通道
-  console.error(`[sisyphus-mcp] 已启动 v${VERSION}，组件 ${COMPONENTS.length} 个，示例 ${EXAMPLES.length} 条`);
+  console.error(
+    `[sisyphus-mcp] 已启动 v${VERSION}，${COMPONENTS.length} 组件 / ${EXAMPLES.length} demo / ${TYPES.length} 类型`,
+  );
 }
 
-main().catch((err) => {
-  console.error('[sisyphus-mcp] 启动失败:', err);
+main().catch((error) => {
+  console.error('[sisyphus-mcp] 启动失败:', error.message);
   process.exit(1);
 });