@rinova/playground-mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @rinova/playground-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 rinova-playground 生成的契约清单（`.playground/manifest.json`）暴露成 MCP 工具，让 Claude Code / Cursor 这类客户端能「读组件能力、看场景、查覆盖」。
+
+## 前置
+
+项目里要先生成清单，也就是 `playground.config.ts` 配了 `components`，然后跑过 `pnpm dev` 或 `pnpm build`。
+
+```ts
+export default defineConfig({
+  components: ['src/components/**/*.vue'],
+})
+```
+
+## 接入
+
+**Claude Code** —— 项目根的 `.mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "rinova-playground": {
+      "command": "npx",
+      "args": ["-y", "@rinova/playground-mcp", "--project", "."]
+    }
+  }
+}
+```
+
+**Cursor** —— `~/.cursor/mcp.json` 同结构。
+
+**本地仓库调试**：
+
+```json
+{
+  "mcpServers": {
+    "rinova-playground": {
+      "command": "node",
+      "args": ["packages/playground-mcp/dist/index.js", "--project", "examples/minimal-lib"]
+    }
+  }
+}
+```
+
+参数：`--project <dir>`（默认当前目录）、`--manifest <file>`（默认 `<project>/.playground/manifest.json`）。
+
+## 工具
+
+| 工具 | 入参 | 返回 |
+|---|---|---|
+| `capability_search` | `query`、`limit?` | 命中的组件 + prop 名 + 场景数 |
+| `capability_get` | `component` | props/events/slots/exposed 全量契约，每个 prop 带 `文件:行号`，附相关场景与未覆盖 props |
+| `scenario_list` | `component?` | 场景 id、标题、分组、文件路径 |
+| `coverage_report` | — | 未覆盖 props 清单 + 覆盖率 |
+
+只读：不改项目文件，也不启动浏览器。写场景仍由人或 AI 直接写 `.vue` 文件（「文件即场景」主线不变）。
+
+## 验证
+
+```bash
+node --experimental-strip-types scripts/probe-mcp.ts   # 仓库根执行，7/7 通过
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+const toPosix = (value) => value.split(path.sep).join('/');
+/** 在源文件里定位某个标识符首次出现的行，产出 `path:line` 锚点 */
+const locate = (root, rel, needle) => {
+    const abs = path.join(root, rel);
+    if (!fs.existsSync(abs))
+        return rel;
+    const lines = fs.readFileSync(abs, 'utf8').split('\n');
+    const pattern = new RegExp(`\\b${needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+    const index = lines.findIndex((line) => pattern.test(line));
+    return index >= 0 ? `${rel}:${index + 1}` : rel;
+};
+const parseArgs = (argv) => {
+    const args = argv.slice(2);
+    const projectIndex = args.indexOf('--project');
+    const manifestIndex = args.indexOf('--manifest');
+    const project = path.resolve(projectIndex > -1 ? (args[projectIndex + 1] ?? '.') : '.');
+    const manifest = manifestIndex > -1
+        ? path.resolve(args[manifestIndex + 1] ?? '')
+        : path.join(project, '.playground/manifest.json');
+    return { project, manifest };
+};
+const loadManifest = (file) => {
+    if (!fs.existsSync(file)) {
+        throw new Error(`找不到契约清单：${file}\n先运行 pnpm dev 或 pnpm build 生成（需要 playground.config.ts 里配置 components）`);
+    }
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+};
+const formatComponent = (root, component, manifest) => {
+    const lines = [
+        `# ${component.name}`,
+        `源码：${locate(root, component.rel, component.name)}`,
+        '',
+        '## Props',
+    ];
+    if (!component.props.length)
+        lines.push('- （无对外 props）');
+    for (const prop of component.props) {
+        const flags = [prop.required ? 'required' : '', prop.default ? `default=${prop.default}` : '']
+            .filter(Boolean)
+            .join(', ');
+        lines.push(`- ${prop.name}: ${prop.type}${flags ? ` (${flags})` : ''}  ← ${locate(root, component.rel, prop.name)}`);
+        if (prop.description)
+            lines.push(`  ${prop.description}`);
+    }
+    if (component.events.length)
+        lines.push('', `## Events`, ...component.events.map((name) => `- ${name}`));
+    if (component.slots.length)
+        lines.push('', `## Slots`, ...component.slots.map((name) => `- ${name}`));
+    if (component.exposed.length)
+        lines.push('', `## Exposed`, ...component.exposed.map((name) => `- ${name}`));
+    const scenes = manifest.scenes.filter((scene) => component.scenes.includes(scene.id));
+    lines.push('', '## 相关场景');
+    if (!scenes.length)
+        lines.push('- （暂无场景，建议补一个）');
+    for (const scene of scenes) {
+        lines.push(`- ${scene.group} / ${scene.title}  ← ${scene.rel}`);
+    }
+    if (component.uncoveredProps.length) {
+        lines.push('', `## 未覆盖 props`, ...component.uncoveredProps.map((name) => `- ${name}`));
+    }
+    return lines.join('\n');
+};
+const matches = (component, query) => {
+    const needle = query.toLowerCase();
+    return (component.name.toLowerCase().includes(needle) ||
+        component.rel.toLowerCase().includes(needle) ||
+        component.props.some((prop) => prop.name.toLowerCase().includes(needle)) ||
+        component.scenes.some((scene) => scene.toLowerCase().includes(needle)));
+};
+const main = async () => {
+    const { project, manifest: manifestPath } = parseArgs(process.argv);
+    let manifest;
+    try {
+        manifest = loadManifest(manifestPath);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+        return;
+    }
+    const server = new McpServer({ name: 'rinova-playground', version: '0.1.0' });
+    server.registerTool('capability_search', {
+        title: '搜索组件能力',
+        description: '按组件名 / prop 名 / 场景 id 搜索，返回带文件行号的摘要',
+        inputSchema: { query: z.string().min(1).describe('关键词'), limit: z.number().int().min(1).max(20).optional() },
+    }, ({ query, limit }) => {
+        const hits = manifest.components.filter((component) => matches(component, query)).slice(0, limit ?? 5);
+        if (!hits.length) {
+            return { content: [{ type: 'text', text: `没有匹配 "${query}" 的组件。已知组件：${manifest.components.map((item) => item.name).join(', ')}` }] };
+        }
+        const text = hits
+            .map((component) => `- ${component.name}（${component.rel}）props: ${component.props.map((prop) => prop.name).join(', ') || '无'}｜场景 ${component.scenes.length} 个`)
+            .join('\n');
+        return { content: [{ type: 'text', text }] };
+    });
+    server.registerTool('capability_get', {
+        title: '获取组件契约',
+        description: '返回组件的 props / events / slots / exposed、源码锚点与相关场景',
+        inputSchema: { component: z.string().min(1).describe('组件名，如 MyButton') },
+    }, ({ component }) => {
+        const found = manifest.components.find((item) => item.name.toLowerCase() === component.toLowerCase() || item.rel.endsWith(component));
+        if (!found) {
+            return {
+                content: [
+                    { type: 'text', text: `没找到组件 "${component}"。可用：${manifest.components.map((item) => item.name).join(', ')}` },
+                ],
+                isError: true,
+            };
+        }
+        return { content: [{ type: 'text', text: formatComponent(project, found, manifest) }] };
+    });
+    server.registerTool('scenario_list', {
+        title: '列出场景',
+        description: '列出全部场景；传 component 则只列该组件相关的场景',
+        inputSchema: { component: z.string().optional().describe('组件名，可选') },
+    }, ({ component }) => {
+        const scenes = component
+            ? manifest.scenes.filter((scene) => {
+                const target = manifest.components.find((item) => item.name === component);
+                return target ? target.scenes.includes(scene.id) : false;
+            })
+            : manifest.scenes;
+        if (!scenes.length)
+            return { content: [{ type: 'text', text: '没有场景。' }] };
+        const text = scenes
+            .map((scene) => `- ${scene.group} / ${scene.title}  id=${scene.id}  ← ${scene.rel}`)
+            .join('\n');
+        return { content: [{ type: 'text', text }] };
+    });
+    server.registerTool('coverage_report', {
+        title: 'props 覆盖报告',
+        description: '列出没有场景覆盖的 props，作为补场景的待办',
+        inputSchema: {},
+    }, () => {
+        const rows = manifest.components.flatMap((component) => component.uncoveredProps.map((prop) => `- ${component.name}.${prop}  ← ${locate(project, component.rel, prop)}`));
+        const total = manifest.components.reduce((sum, component) => sum + component.props.length, 0);
+        const uncovered = rows.length;
+        const head = `覆盖 ${total - uncovered}/${total}｜清单生成时间 ${manifest.generatedAt}`;
+        return { content: [{ type: 'text', text: rows.length ? `${head}\n\n${rows.join('\n')}` : `${head}\n\n全部 props 都有场景覆盖。` }] };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[rinova-playground-mcp] 已启动，清单：${manifestPath}（${manifest.components.length} 个组件）`);
+};
+await main();

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@rinova/playground-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "rinova-playground 的 MCP server：把契约清单暴露给 AI 编码工具",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jove-rina/rinova-playground"
+  },
+  "bin": {
+    "rinova-playground-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.6",
+    "typescript": "5.9.3"
+  }
+}