tt-design-mcp 1.0.0

package/README.md

@@ -0,0 +1,218 @@
+# tt-design-mcp
+
+面向 `tt-design` 组件库的 MCP Server，通过 npm 包分发，供支持 MCP 的 AI 客户端（如 Claude Code）查询组件元数据。
+
+## 功能概述
+
+- 列出基础组件 / 业务组件
+- 查询组件导出位置与推荐导入方式
+- 查询组件 API 元信息（props、默认值、propTypes、forwardRef、memo）
+- 查询组件样式元信息（类名、CSS 变量、主题引用）
+
+数据来源于用户项目中已安装的 `tt-design` 包内的 `dist/meta/*.json`，无需 clone 源码仓库。
+
+## 前置条件
+
+1. 本机已安装 Node.js
+2. 当前项目已安装 `tt-design`
+3. 当前项目可安装开发依赖
+
+## 快速接入
+
+### 1. 安装依赖
+
+```bash
+npm install tt-design
+npm install -D tt-design-mcp
+```
+
+### 2. 配置 MCP Client
+
+在 Claude Code 等 MCP Client 的配置中添加：
+
+```json
+{
+  "mcpServers": {
+    "tt-design": {
+      "command": "npx",
+      "args": ["-y", "tt-design-mcp"]
+    }
+  }
+}
+```
+
+### 3. 验证接入
+
+在 Claude Code 中输入：
+
+- `请用 tt-design MCP 列出所有基础组件`
+- `请用 tt-design MCP 查询 Button 的 API`
+- `请用 tt-design MCP 查询 DatePicker 的样式信息`
+
+能正常返回结果即表示接入成功。
+
+## 可用工具
+
+### `list_components`
+列出组件，支持按分类或关键字过滤。
+
+```
+输入参数：
+  category?: "basic" | "business"  # 可选，按组件分类过滤
+  keyword?: string                 # 可选，按名称子串过滤
+
+适用场景：查看当前有哪些组件，查找某类组件是否存在
+```
+
+### `find_component_exports`
+查询组件导出位置和推荐导入方式。
+
+```
+输入参数：
+  name: string  # 必填，组件名（大小写敏感）
+
+适用场景：确认组件从哪里导出，推荐从哪个入口导入
+```
+
+### `get_component_api`
+查询组件 API 元信息。
+
+```
+输入参数：
+  name: string  # 必填，组件名
+
+适用场景：查看 props、默认值、是否有 propTypes、是否使用 forwardRef/memo
+```
+
+### `get_component_style`
+查询组件样式元信息。
+
+```
+输入参数：
+  name: string  # 必填，组件名
+
+适用场景：查看样式文件路径、主类名、修饰类、CSS 变量、主题引用
+```
+
+## 错误处理
+
+常见错误及排查：
+
+| 错误码 | 说明 | 排查建议 |
+|--------|------|----------|
+| `METADATA_LOAD_FAILED` | 未找到 `tt-design` 包 | 确认当前项目已安装 `tt-design` |
+| `METADATA_FILE_INVALID` | 元数据文件损坏或格式不兼容 | 确认 `tt-design` 版本与 `tt-design-mcp` 兼容 |
+| `COMPONENT_NOT_FOUND` | 组件不在元数据中 | 确认组件名大小写正确 |
+| `INVALID_COMPONENT_NAME` | 组件名格式无效 | 组件名只能包含字母、数字、下划线、美元符 |
+
+## 发布到 npm
+
+### 首次发布
+
+```bash
+cd mcp-package
+
+# 登录 npm（需要 npm 账号）
+npm login
+
+# 发布（需要先确认 package.json 中的 name、version、description 正确）
+npm publish --access public
+```
+
+### 后续更新
+
+```bash
+cd mcp-package
+
+# 升级版本号（遵循 SemVer）
+# patch: npm version patch
+# minor: npm version minor
+# major: npm version major
+npm version patch
+
+# 发布
+npm publish
+```
+
+### 发布前检查清单
+
+- [ ] `package.json` 中 `name` 为 `tt-design-mcp`
+- [ ] `version` 已正确升级
+- [ ] `description` 描述准确
+- [ ] `engines` 指定了 Node.js 版本范围（可选）
+- [ ] 运行测试确认正常：
+  ```bash
+  npm test
+  ```
+- [ ] 在临时项目中验证完整接入流程
+
+### 本地调试
+
+在 `mcp-package` 目录下手动启动：
+
+```bash
+node bin/cli.mjs
+```
+
+运行测试：
+
+```bash
+npm test
+```
+
+## 版本说明
+
+- `tt-design-mcp` 与 `tt-design` 通过 `metadataSchemaVersion` 保持兼容
+- 当前 schema 版本为 `1`
+- 升级 `tt-design` 时会同步更新元数据，schema 不变则 `tt-design-mcp` 无需升级
+- schema 发生不兼容变化时会同步升级 `metadataSchemaVersion`
+
+## 本地仓库开发模式
+
+如果你在 `tt-design` 仓库本地开发，可使用仓库内置的源码分析型 MCP（不需要安装 `tt-design-mcp`）：
+
+```json
+{
+  "mcpServers": {
+    "tt-design": {
+      "command": "node",
+      "args": ["mcp/server.mjs"]
+    }
+  }
+}
+```
+
+此模式直接从源码读取信息，适合调试和贡献者使用。
+
+## 目录结构
+
+```
+mcp-package/
+├── bin/
+│   └── cli.mjs              # CLI 入口
+├── src/
+│   ├── meta/
+│   │   ├── schema.mjs       # Zod schemas
+│   │   ├── load-meta.mjs    # 加载元数据
+│   │   └── resolve-package-root.mjs  # 定位 tt-design 包
+│   ├── tools/
+│   │   ├── list-components.mjs
+│   │   ├── find-component-exports.mjs
+│   │   ├── get-component-api.mjs
+│   │   └── get-component-style.mjs
+│   ├── utils/
+│   │   ├── result.mjs            # ok/fail 结果封装
+│   │   └── component-lookup.mjs   # 组件名校验
+│   └── server.mjs           # MCP Server 引导
+├── test/
+│   ├── load-meta.test.mjs       # 元数据加载测试
+│   └── server-smoke.test.mjs     # 端到端冒烟测试
+└── package.json
+```
+
+## 技术栈
+
+- Node.js ESM
+- `@modelcontextprotocol/sdk` 1.18.0
+- Zod 3.x
+- Node.js 内置测试（`node:test`）

package/bin/cli.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { startServer } from '../src/server.mjs';
+
+startServer().catch((error) => {
+  console.error('tt-design-mcp failed to start');
+  console.error(error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "tt-design-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for querying tt-design component metadata",
+  "type": "module",
+  "bin": {
+    "tt-design-mcp": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test ./test/*.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.18.0",
+    "zod": "^3.23.8"
+  }
+}

package/src/meta/load-meta.mjs

@@ -0,0 +1,55 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  componentsFileSchema,
+  exportsFileSchema,
+  apiFileSchema,
+  stylesFileSchema,
+  versionFileSchema,
+} from './schema.mjs';
+import { resolveInstalledTtDesignRoot } from './resolve-package-root.mjs';
+
+function readJsonFile(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  return JSON.parse(content);
+}
+
+/**
+ * Read and validate all 5 metadata JSON files from the installed tt-design package.
+ * @param {string} packageRoot - Absolute path to the tt-design package root.
+ * @returns {{ version, components, exports, api, styles }}
+ */
+export function loadMetaFromPackageRoot(packageRoot) {
+  const metaDir = path.join(packageRoot, 'dist/meta');
+
+  function readAndValidate(fileName, schema) {
+    try {
+      return schema.parse(readJsonFile(path.join(metaDir, fileName)));
+    } catch (error) {
+      const errorToThrow = new Error(`Failed to parse ${fileName}: ${error.message}`);
+      errorToThrow.fileName = fileName;
+      errorToThrow.schemaErrors = error.errors || [];
+      throw errorToThrow;
+    }
+  }
+
+  return {
+    version: readAndValidate('version.json', versionFileSchema),
+    components: readAndValidate('components.json', componentsFileSchema),
+    exports: readAndValidate('exports.json', exportsFileSchema),
+    api: readAndValidate('api.json', apiFileSchema),
+    styles: readAndValidate('styles.json', stylesFileSchema),
+  };
+}
+
+/**
+ * Locate the installed tt-design package and load its metadata.
+ * @param {string} [startDir] - Directory to start searching from (defaults to process.cwd()).
+ * @returns {{ packageRoot, meta }}
+ */
+export function loadInstalledTtDesignMeta(startDir) {
+  const packageRoot = resolveInstalledTtDesignRoot(startDir);
+  const meta = loadMetaFromPackageRoot(packageRoot);
+  return { packageRoot, meta };
+}

package/src/meta/resolve-package-root.mjs

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Walk upward from startDir looking for node_modules/tt-design/package.json.
+ * Returns the resolved package root, or throws if not found.
+ */
+export function resolveInstalledTtDesignRoot(startDir = process.cwd()) {
+  let current = path.resolve(startDir);
+  const root = path.parse(current).root;
+
+  while (current !== root) {
+    const candidate = path.join(current, 'node_modules/tt-design/package.json');
+    if (fs.existsSync(candidate)) {
+      return path.join(current, 'node_modules/tt-design');
+    }
+    current = path.dirname(current);
+  }
+
+  // Last chance: check the root drive
+  const rootCandidate = path.join(root, 'node_modules/tt-design/package.json');
+  if (fs.existsSync(rootCandidate)) {
+    return path.join(root, 'node_modules/tt-design');
+  }
+
+  throw new Error(
+    `Could not find 'tt-design' package. ` +
+      `Make sure 'tt-design' is installed in your project.\n` +
+      `Searched from: ${path.resolve(startDir)}`
+  );
+}

package/src/meta/schema.mjs

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+
+// Source location embedded in each file
+export const sourceLocationSchema = z.object({
+  file: z.string(),
+  line: z.number().nullable(),
+  column: z.number().nullable(),
+  reason: z.string().optional(),
+});
+
+export const exportedFromSchema = z.object({
+  components: z.union([z.string(), z.boolean()]),
+  business: z.union([z.string(), z.boolean()]),
+  root: z.boolean(),
+});
+
+export const componentSummarySchema = z.object({
+  name: z.string(),
+  category: z.string(),
+  sourcePath: z.string(),
+  version: z.string().nullable(),
+  exportedFrom: exportedFromSchema,
+});
+
+export const exportEntrySchema = z.object({
+  name: z.string(),
+  category: z.string(),
+  sourcePath: z.string(),
+  exportedFrom: exportedFromSchema,
+  preferredImport: z
+    .object({
+      module: z.string(),
+      export: z.string(),
+    })
+    .nullable(),
+  sourceLocations: z.array(sourceLocationSchema),
+  warnings: z.array(z.string()),
+});
+
+export const apiComponentSchema = z.object({
+  name: z.string(),
+  category: z.string(),
+  sourcePath: z.string(),
+  defaultExport: z.string().nullable(),
+  props: z.array(z.string()),
+  defaults: z.record(z.string(), z.unknown()),
+  subcomponents: z.array(z.string()),
+  hasDataComponentVersion: z.boolean(),
+  hasPropTypes: z.boolean(),
+  sourceLocations: z.array(sourceLocationSchema),
+  warnings: z.array(z.string()),
+});
+
+export const styleThemeImportSchema = z.object({
+  path: z.string(),
+  kind: z.string().nullable(),
+});
+
+export const styleComponentSchema = z.object({
+  name: z.string(),
+  category: z.string(),
+  sourcePath: z.string(),
+  stylePath: z.string().nullable(),
+  blockClass: z.string().nullable(),
+  modifierClasses: z.array(z.string()),
+  relatedClasses: z.array(z.string()),
+  cssVariables: z.array(z.string()),
+  hardcodedColors: z.array(z.string()),
+  themeImport: styleThemeImportSchema.nullable(),
+  sourceLocations: z.array(sourceLocationSchema),
+  warnings: z.array(z.string()),
+});
+
+export const versionFileSchema = z.object({
+  generatedAt: z.string(),
+  metadataSchemaVersion: z.number(),
+  packageName: z.string(),
+  packageVersion: z.string(),
+});
+
+export const componentsFileSchema = z.object({
+  generatedAt: z.string(),
+  metadataSchemaVersion: z.number(),
+  packageName: z.string(),
+  components: z.array(componentSummarySchema),
+});
+
+export const exportsFileSchema = z.object({
+  generatedAt: z.string(),
+  metadataSchemaVersion: z.number(),
+  packageName: z.string(),
+  components: z.array(exportEntrySchema),
+});
+
+export const apiFileSchema = z.object({
+  generatedAt: z.string(),
+  metadataSchemaVersion: z.number(),
+  packageName: z.string(),
+  components: z.array(apiComponentSchema),
+});
+
+export const stylesFileSchema = z.object({
+  generatedAt: z.string(),
+  metadataSchemaVersion: z.number(),
+  packageName: z.string(),
+  components: z.array(styleComponentSchema),
+});

package/src/server.mjs

@@ -0,0 +1,149 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { loadInstalledTtDesignMeta } from './meta/load-meta.mjs';
+import { listComponents } from './tools/list-components.mjs';
+import { findComponentExports } from './tools/find-component-exports.mjs';
+import { getComponentApi } from './tools/get-component-api.mjs';
+import { getComponentStyle } from './tools/get-component-style.mjs';
+import { fail, normalizeInfrastructureError } from './utils/result.mjs';
+
+const envelopeOutputSchema = {
+  ok: z.boolean(),
+  data: z.unknown().optional(),
+  error: z
+    .object({
+      code: z.string(),
+      message: z.string(),
+      details: z.record(z.unknown()).optional(),
+    })
+    .optional(),
+  sourceLocations: z.array(
+    z.object({
+      file: z.string(),
+      line: z.number().optional(),
+      column: z.number().optional(),
+    }),
+  ),
+  warnings: z.array(z.string()),
+};
+
+function toToolResult(result) {
+  return {
+    isError: result.ok === false,
+    structuredContent: result,
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(result),
+      },
+    ],
+  };
+}
+
+async function invokeTool(handler, args) {
+  try {
+    let meta;
+    try {
+      ({ meta } = loadInstalledTtDesignMeta());
+    } catch (error) {
+      const code = error.fileName ? 'METADATA_FILE_INVALID' : 'METADATA_LOAD_FAILED';
+      return toToolResult(fail(code, error.message, {
+        ...(error.fileName ? { fileName: error.fileName } : {}),
+        ...(error.schemaErrors ? { schemaErrors: error.schemaErrors } : {}),
+        cwd: process.cwd(),
+      }));
+    }
+    return toToolResult(handler(meta, args));
+  } catch (error) {
+    return toToolResult(normalizeInfrastructureError(error));
+  }
+}
+
+export function createServer() {
+  const server = new McpServer(
+    {
+      name: 'tt-design-mcp',
+      version: '1.0.0',
+    },
+    {
+      instructions:
+        'MCP server for querying tt-design component metadata. ' +
+        'Loads dist/meta/*.json from the user-installed tt-design package.',
+    },
+  );
+
+  server.registerTool(
+    'list_components',
+    {
+      description: 'List tt-design components with optional category and keyword filters.',
+      inputSchema: {
+        category: z.enum(['basic', 'business']).optional(),
+        keyword: z.string().min(1).optional(),
+      },
+      outputSchema: envelopeOutputSchema,
+    },
+    async (args = {}) => invokeTool(listComponents, args),
+  );
+
+  server.registerTool(
+    'find_component_exports',
+    {
+      description: 'Find where a tt-design component is exported and how it should be imported.',
+      inputSchema: {
+        name: z.string().min(1),
+      },
+      outputSchema: envelopeOutputSchema,
+    },
+    async (args) => invokeTool(findComponentExports, args),
+  );
+
+  server.registerTool(
+    'get_component_api',
+    {
+      description:
+        'Inspect a tt-design component source file and return normalized API metadata.',
+      inputSchema: {
+        name: z.string().min(1),
+      },
+      outputSchema: envelopeOutputSchema,
+    },
+    async (args) => invokeTool(getComponentApi, args),
+  );
+
+  server.registerTool(
+    'get_component_style',
+    {
+      description:
+        'Inspect a tt-design component style file and return normalized style metadata.',
+      inputSchema: {
+        name: z.string().min(1),
+      },
+      outputSchema: envelopeOutputSchema,
+    },
+    async (args) => invokeTool(getComponentStyle, args),
+  );
+
+  return server;
+}
+
+export async function startServer() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+const isEntrypoint =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isEntrypoint) {
+  startServer().catch((error) => {
+    console.error('tt-design-mcp server failed to start');
+    console.error(error);
+    process.exit(1);
+  });
+}

package/src/tools/find-component-exports.mjs

@@ -0,0 +1,39 @@
+import { ok, fail } from '../utils/result.mjs';
+import { validateComponentName } from '../utils/component-lookup.mjs';
+
+/**
+ * Find how a tt-design component is exported and where it should be imported from.
+ * @param {object} meta - Loaded metadata object from loadInstalledTtDesignMeta.
+ * @param {{ name: string }} args
+ * @returns {object} Result envelope.
+ */
+export function findComponentExports(meta, { name } = {}) {
+  const nameValidation = validateComponentName(name);
+  if (!nameValidation.valid) {
+    return fail(nameValidation.error.code, nameValidation.error.message, nameValidation.error.details);
+  }
+
+  const component = meta.exports.components.find((entry) => entry.name === name);
+
+  if (!component) {
+    return fail('COMPONENT_NOT_FOUND', 'Component not found in registry', { name });
+  }
+
+  const warnings = [...(component.warnings || [])];
+
+  if (!component.exportedFrom.root) {
+    warnings.push(`${component.name} is not exported from tt-design root (src/index.js).`);
+  }
+
+  return ok(
+    {
+      name: component.name,
+      category: component.category,
+      sourcePath: component.sourcePath,
+      exportedFrom: component.exportedFrom,
+      preferredImport: component.preferredImport,
+    },
+    component.sourceLocations || [],
+    warnings,
+  );
+}

package/src/tools/get-component-api.mjs

@@ -0,0 +1,25 @@
+import { ok, fail } from '../utils/result.mjs';
+import { validateComponentName } from '../utils/component-lookup.mjs';
+
+/**
+ * Return API metadata for a tt-design component.
+ * @param {object} meta - Loaded metadata object from loadInstalledTtDesignMeta.
+ * @param {{ name: string }} args
+ * @returns {object} Result envelope.
+ */
+export function getComponentApi(meta, { name } = {}) {
+  const nameValidation = validateComponentName(name);
+  if (!nameValidation.valid) {
+    return fail(nameValidation.error.code, nameValidation.error.message, nameValidation.error.details);
+  }
+
+  const component = meta.api.components.find((entry) => entry.name === name);
+
+  if (!component) {
+    return fail('COMPONENT_NOT_FOUND', 'Component not found in API metadata', { name });
+  }
+
+  const { sourceLocations, warnings, ...apiData } = component;
+
+  return ok(apiData, sourceLocations || [], warnings || []);
+}

package/src/tools/get-component-style.mjs

@@ -0,0 +1,25 @@
+import { ok, fail } from '../utils/result.mjs';
+import { validateComponentName } from '../utils/component-lookup.mjs';
+
+/**
+ * Return style metadata for a tt-design component.
+ * @param {object} meta - Loaded metadata object from loadInstalledTtDesignMeta.
+ * @param {{ name: string }} args
+ * @returns {object} Result envelope.
+ */
+export function getComponentStyle(meta, { name } = {}) {
+  const nameValidation = validateComponentName(name);
+  if (!nameValidation.valid) {
+    return fail(nameValidation.error.code, nameValidation.error.message, nameValidation.error.details);
+  }
+
+  const component = meta.styles.components.find((entry) => entry.name === name);
+
+  if (!component) {
+    return fail('COMPONENT_NOT_FOUND', 'Component not found in style metadata', { name });
+  }
+
+  const { sourceLocations, warnings, ...styleData } = component;
+
+  return ok(styleData, sourceLocations || [], warnings || []);
+}

package/src/tools/list-components.mjs

@@ -0,0 +1,41 @@
+import { ok, fail } from '../utils/result.mjs';
+
+const VALID_CATEGORIES = new Set(['basic', 'business']);
+
+/**
+ * List tt-design components with optional filters.
+ * @param {object} meta - Loaded metadata object from loadInstalledTtDesignMeta.
+ * @param {{ category?: string, keyword?: string }} args
+ * @returns {object} Result envelope.
+ */
+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 });
+  }
+
+  let components = meta.components.components;
+
+  if (category) {
+    components = components.filter((component) => component.category === category);
+  }
+
+  if (keyword) {
+    components = components.filter((component) => component.name.toLowerCase().includes(keyword.toLowerCase()));
+  }
+
+  const warnings = components.flatMap((component) => component.warnings || []);
+
+  return ok(
+    {
+      components: components.map((component) => ({
+        name: component.name,
+        category: component.category,
+        version: component.version,
+        sourcePath: component.sourcePath,
+        exportedFrom: component.exportedFrom,
+      })),
+    },
+    [],
+    warnings,
+  );
+}

package/src/utils/component-lookup.mjs

@@ -0,0 +1,15 @@
+export const COMPONENT_NAME_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+export function validateComponentName(name) {
+  if (!COMPONENT_NAME_PATTERN.test(name || '')) {
+    return {
+      valid: false,
+      error: {
+        code: 'INVALID_COMPONENT_NAME',
+        message: 'name must be a valid component export identifier',
+        details: { name },
+      },
+    };
+  }
+  return { valid: true };
+}

package/src/utils/result.mjs

@@ -0,0 +1,28 @@
+export function ok(data, sourceLocations = [], warnings = []) {
+  return {
+    ok: true,
+    data,
+    sourceLocations,
+    warnings,
+  };
+}
+
+export function fail(code, message, details = {}) {
+  return {
+    ok: false,
+    error: {
+      code,
+      message,
+      details,
+    },
+    sourceLocations: [],
+    warnings: [],
+  };
+}
+
+export function normalizeInfrastructureError(error) {
+  return fail(
+    'INTERNAL_ERROR',
+    error?.message || 'Unexpected MCP infrastructure error',
+  );
+}