tt-design-mcp 1.0.3 → 1.0.4

package/README.md

@@ -4,7 +4,7 @@
 
 ## 功能概述
 
-- 列出基础组件 / 业务组件
+- 列出基础组件
 - 查询组件导出位置与推荐导入方式
 - 查询组件 API 元信息（props、默认值、propTypes、forwardRef、memo）
 - 查询组件样式元信息（类名、CSS 变量、主题引用）
@@ -15,31 +15,47 @@
 
 ## 前置条件
 
-1. 本机已安装 Node.js
+1. 本机已安装 Node.js 18+
 2. 当前项目已安装 `tt-design`
-3. 当前项目可安装开发依赖
 
 ## 快速接入
 
-### 1. 安装依赖
+### 推荐原则
+
+- 业务项目只安装 `tt-design`
+- `tt-design-mcp` 作为本地开发工具使用，不写入业务项目 `package.json`
+- 推荐通过 `npx`、全局安装或独立工具目录运行 `tt-design-mcp`
+
+不推荐在业务项目中执行：
 
 ```bash
-npm install tt-design
 npm install -D tt-design-mcp
 ```
 
+原因：
+
+- `tt-design-mcp` 依赖 Node.js 18+
+- 一些 Jenkins / CI 环境会安装 `devDependencies`
+- 如果 CI 仍使用 Node.js 14，安装 `tt-design-mcp` 时可能失败
+
+### 1. 安装业务依赖
+
+```bash
+npm install tt-design
+```
+
 ### 2. 配置 MCP Client
 
 如果使用 Claude Code，推荐在已安装 `tt-design` 的项目根目录执行：
 
 ```bash
-claude mcp add --scope project --transport stdio tt-design -- npx tt-design-mcp
+claude mcp add --scope project --transport stdio tt-design -- npx -y tt-design-mcp
 ```
 
 如果在 Windows 上使用 Claude Code，请加上 `cmd /c` 包装：
 
 ```bash
-claude mcp add --scope project --transport stdio tt-design -- cmd /c npx tt-design-mcp
+claude mcp add --scope project --transport stdio tt-design -- cmd /c "npx -y tt-design-mcp"
 ```
 
 如果需要手动配置，也可以在 Claude Code 等 MCP Client 的配置中添加：
@@ -65,20 +81,73 @@ claude mcp add --scope project --transport stdio tt-design -- cmd /c npx tt-desi
 
 能正常返回结果即表示接入成功。
 
+## 本地使用规范
+
+推荐团队统一采用下面这套流程：
+
+1. 业务项目依赖里只保留 `tt-design`
+2. 本地 MCP Client 统一用 `npx -y tt-design-mcp`
+3. `tt-design-mcp` 不进入业务项目的 `dependencies` 或 `devDependencies`
+4. 本地运行 MCP 时使用 Node.js 18+，不影响业务项目现有构建 Node 版本
+
+这样可以同时满足：
+
+- 开发者本地可正常使用 MCP
+- Jenkins / CI 不会因为安装 `tt-design-mcp` 失败
+- 不污染业务项目锁文件和依赖树
+
+## 其他本地接入方案
+
+### 方案二：全局安装
+
+如果团队成员经常使用，可以在本机全局安装：
+
+```bash
+npm install -g tt-design-mcp
+```
+
+然后在 MCP Client 中配置：
+
+```json
+{
+  "mcpServers": {
+    "tt-design": {
+      "command": "tt-design-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### 方案三：独立工具目录
+
+如果希望进一步与业务项目隔离，可以在本机单独创建工具目录：
+
+```bash
+mkdir -p ~/dev-tools/tt-design-mcp
+cd ~/dev-tools/tt-design-mcp
+npm init -y
+npm install tt-design-mcp
+```
+
+然后让 MCP Client 指向该目录下的可执行文件或通过该目录内的 `npx` 启动。
+
 ## 可用工具
 
 ### `list_components`
-列出组件，支持按分类或关键字过滤。
+
+列出基础组件，支持关键字过滤。
 
 ```
 输入参数：
-  category?: "basic" | "business"  # 可选，按组件分类过滤
+  category?: "basic"               # 可选，仅支持基础组件
   keyword?: string                 # 可选，按名称子串过滤
 
-适用场景：查看当前有哪些组件，查找某类组件是否存在
+适用场景：查看当前有哪些基础组件，按名称筛选基础组件
 ```
 
 ### `find_component_exports`
+
 查询组件导出位置和推荐导入方式。
 
 ```
@@ -89,6 +158,7 @@ claude mcp add --scope project --transport stdio tt-design -- cmd /c npx tt-desi
 ```
 
 ### `get_component_api`
+
 查询组件 API 元信息。
 
 ```
@@ -99,6 +169,7 @@ claude mcp add --scope project --transport stdio tt-design -- cmd /c npx tt-desi
 ```
 
 ### `get_component_style`
+
 查询组件样式元信息。
 
 ```
@@ -112,12 +183,12 @@ claude mcp add --scope project --transport stdio tt-design -- cmd /c npx tt-desi
 
 常见错误及排查：
 
-| 错误码 | 说明 | 排查建议 |
-|--------|------|----------|
-| `METADATA_LOAD_FAILED` | 未找到 `tt-design` 包 | 确认当前项目已安装 `tt-design` |
-| `METADATA_FILE_INVALID` | 元数据文件损坏或格式不兼容 | 确认 `tt-design` 版本与 `tt-design-mcp` 兼容 |
-| `COMPONENT_NOT_FOUND` | 组件不在元数据中 | 确认组件名大小写正确 |
-| `INVALID_COMPONENT_NAME` | 组件名格式无效 | 组件名只能包含字母、数字、下划线、美元符 |
+| 错误码                      | 说明                | 排查建议                                  |
+| ------------------------ | ----------------- | ------------------------------------- |
+| `METADATA_LOAD_FAILED`   | 未找到 `tt-design` 包 | 确认当前项目已安装 `tt-design`                 |
+| `METADATA_FILE_INVALID`  | 元数据文件损坏或格式不兼容     | 确认 `tt-design` 版本与 `tt-design-mcp` 兼容 |
+| `COMPONENT_NOT_FOUND`    | 组件不在元数据中          | 确认组件名大小写正确                            |
+| `INVALID_COMPONENT_NAME` | 组件名格式无效           | 组件名只能包含字母、数字、下划线、美元符                  |
 
 ## 发布到 npm
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tt-design-mcp",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "MCP server for querying tt-design component metadata",
   "type": "module",
   "bin": {

package/src/server.mjs

@@ -81,9 +81,9 @@ export function createServer() {
   server.registerTool(
     'list_components',
     {
-      description: 'List tt-design components with optional category and keyword filters.',
+      description: 'List basic tt-design components with optional keyword filtering.',
       inputSchema: {
-        category: z.enum(['basic', 'business']).optional(),
+        category: z.enum(['basic']).optional(),
         keyword: z.string().min(1).optional(),
       },
       outputSchema: envelopeOutputSchema,

package/src/tools/list-components.mjs

@@ -1,6 +1,6 @@
 import { ok, fail } from '../utils/result.mjs';
 
-const VALID_CATEGORIES = new Set(['basic', 'business']);
+const VALID_CATEGORIES = new Set(['basic']);
 
 /**
  * List tt-design components with optional filters.
@@ -10,10 +10,10 @@ const VALID_CATEGORIES = new Set(['basic', 'business']);
  */
 export function listComponents(meta, { category, keyword } = {}) {
   if (category != null && !VALID_CATEGORIES.has(category)) {
-    return fail('INVALID_FILTER', 'category must be one of: basic, business', { category });
+    return fail('INVALID_FILTER', 'category must be one of: basic', { category });
   }
 
-  let components = meta.components.components;
+  let components = meta.components.components.filter((component) => component.category === 'basic');
 
   if (category) {
     components = components.filter((component) => component.category === category);