phinix 0.0.4

package/README.md

@@ -0,0 +1,311 @@
+# phinix MCP 服务器
+
+phinix 是一个基于 Model Context Protocol (MCP) 的服务器，为 AI 模型提供项目内组件的查询和详情获取功能。
+
+## 功能特性
+
+### 🧠 项目知识获取 (`get_project_knowledge`)
+- **【必须首先调用】** 获取项目背景知识和开发规范
+- 包含技术栈、样式规范、组件使用指南和代码示例
+- 在进行任何代码开发前，必须先调用此工具了解项目规范
+
+### 🔍 组件列表查询 (`get_component_list`)
+- 获取项目内所有可用的组件列表
+- 支持按关键词搜索组件名称或使用场景
+- 支持限制返回结果数量
+- 提供组件的基本信息（名称和使用场景）
+
+### 🔧 组件定义获取 (`get_component_define`)
+- 获取组件的TypeScript接口定义和属性说明
+- 返回组件的类型定义和接口文档
+- 支持内容长度限制，防止过长内容
+
+### 📄 组件源码获取 (`get_component_source`)
+- 获取组件的完整实现代码
+- 用于学习和参考组件的具体实现
+- 支持多种文件格式和目录结构
+- 支持内容截取，避免过长输出
+
+### 📖 组件文档获取 (`get_component_readme`)
+- 获取组件的使用文档和说明信息
+- 返回组件的README文档内容
+- 包含组件的使用指南和注意事项
+
+### 🎯 组件示例获取 (`get_component_demos`)
+- 获取组件的使用示例代码和演示效果
+- 支持获取多个示例文件
+- 可配置返回的示例数量和内容长度
+- 可选择是否包含示例文件内容
+
+## 安装和使用
+
+### 环境要求
+- Node.js 18+
+- npm 或 yarn
+
+### 安装依赖
+```bash
+npm install
+```
+
+### 启动服务器
+
+#### 方式1：直接启动（使用当前目录作为项目根目录）
+```bash
+npm start
+```
+
+#### 方式2：指定项目根目录
+```bash
+# 使用环境变量
+PROJECT_ROOT=/path/to/your/project npm start
+
+# 或者使用命令行参数
+node src/index.js /path/to/your/project
+```
+
+### 在 cursor 中配置
+
+在 cursor 的配置文件中添加以下配置：
+
+```json
+{
+  "mcpServers": {
+    "phinix": {
+      "command": "npx",
+      "args": [
+        "phinix",
+        "/Users/wuzixuan/code-lib/dataphin" // 修改此处为你的dataphin项目地址
+      ],
+      "cwd": "/Users/wuzixuan/code-lib/phinix" 
+    }
+  }
+}
+```
+
+## MCP 工具说明
+
+### 1. get_project_knowledge
+
+**【必须首先调用】** 获取项目背景知识和开发规范。
+
+**参数：**
+- 无需参数
+
+**返回：**
+- 项目技术栈信息
+- 样式规范和设计指南
+- 组件使用规范
+- 代码示例和最佳实践
+
+**示例：**
+```
+工具：get_project_knowledge
+参数：{}
+```
+
+### 2. get_component_list
+
+获取项目内所有可用的组件列表。
+
+**参数：**
+- `search` (可选): 搜索关键词，可以匹配组件名称或使用场景
+- `limit` (可选): 返回结果的最大数量，默认为50
+
+**返回：**
+- 组件列表和基本信息
+- 匹配的组件数量
+- 搜索关键词（如果有）
+
+**示例：**
+```
+工具：get_component_list
+参数：{"search": "table", "limit": 5}
+```
+
+
+### 3. get_component_define
+
+获取组件的TypeScript接口定义和属性说明。
+
+**参数：**
+- `componentName` (必需): 要获取定义的组件名称
+- `maxContentLength` (可选): 内容的最大长度（字符数），超过会被截取，默认为5000
+
+**返回：**
+- 组件的TypeScript类型定义
+- 接口属性说明
+- 类型约束信息
+
+**示例：**
+```
+工具：get_component_define
+参数：{"componentName": "DPTable", "maxContentLength": 3000}
+```
+
+### 4. get_component_source
+
+获取组件的完整实现代码。
+
+**参数：**
+- `componentName` (必需): 要获取源码的组件名称
+- `maxContentLength` (可选): 内容的最大长度（字符数），超过会被截取，默认为8000
+
+**返回：**
+- 组件的完整源代码
+- 文件路径信息
+- 代码实现细节
+
+**示例：**
+```
+工具：get_component_source
+参数：{"componentName": "DPButton", "maxContentLength": 5000}
+```
+
+### 5. get_component_readme
+
+获取组件的使用文档和说明信息。
+
+**参数：**
+- `componentName` (必需): 要获取文档的组件名称
+- `maxContentLength` (可选): 内容的最大长度（字符数），超过会被截取，默认为10000
+
+**返回：**
+- 组件的README文档内容
+- 使用指南和说明
+- 注意事项和最佳实践
+
+**示例：**
+```
+工具：get_component_readme
+参数：{"componentName": "DPForm"}
+```
+
+### 6. get_component_demos
+
+获取组件的使用示例代码和演示效果。
+
+**参数：**
+- `componentName` (必需): 要获取示例的组件名称
+- `maxDemoCount` (可选): 最多返回的demo示例数量，默认为5
+- `maxContentLength` (可选): 单个demo文件内容的最大长度（字符数），超过会被截取，默认为3000
+- `includeContent` (可选): 是否包含demo文件内容，false时只返回文件列表，默认为true
+
+**返回：**
+- 组件的示例代码
+- 演示效果说明
+- 使用场景示例
+
+**示例：**
+```
+工具：get_component_demos
+参数：{"componentName": "DPChart", "maxDemoCount": 3, "includeContent": true}
+```
+
+## 项目结构要求
+
+### 必需的资源文件
+
+#### 1. 组件信息文件
+服务器需要 `src/resources/components-info.json` 文件，包含组件的基本信息：
+
+```json
+{
+  "timestamp": "2025-07-04T07:48:06.884Z",
+  "totalCount": 82,
+  "components": [
+    {
+      "name": "ComponentName",
+      "whenToUse": "组件的使用场景描述"
+    }
+  ]
+}
+```
+
+#### 2. 项目知识文件
+服务器需要 `src/resources/project-knowledge.md` 文件，包含项目的背景知识和开发规范：
+- 技术栈信息
+- 样式规范和设计指南
+- 组件使用规范
+- 代码示例和最佳实践
+
+### 组件文件结构
+
+对于每个组件，推荐的目录结构为：
+```
+src/components/ComponentName/
+├── ComponentName.tsx          # 主要实现文件
+├── index.tsx                  # 导出文件
+├── define.ts                  # TypeScript类型定义
+├── README.md                  # 组件文档
+└── demos/                     # 示例目录
+    ├── basic.tsx              # 基础示例
+    ├── advanced.tsx           # 高级示例
+    └── ...
+```
+
+### 组件文件查找
+
+服务器会在以下目录中查找组件实现文件：
+- `src/components/`
+- `components/`
+- `src/`
+- `lib/components/`
+- `packages/`
+
+支持的文件格式：
+- 主要实现：`ComponentName.tsx`, `ComponentName.ts`, `index.tsx`, `index.ts`
+- 类型定义：`define.ts`
+- 文档文件：`README.md`
+- 示例文件：`demos/` 目录下的各种格式文件
+
+## 开发和测试
+
+### 运行测试
+```bash
+# 测试组件列表功能
+node quick-test.js
+
+# 测试组件详情功能
+node test-component-details.js
+
+# 使用调试客户端测试所有功能
+node debug-client.js
+```
+
+### 开发模式
+```bash
+npm run dev
+```
+
+### 测试MCP连接
+```bash
+# 使用测试脚本验证MCP服务器
+./test-mcp.sh
+```
+
+## 技术栈
+
+- **MCP SDK**: @modelcontextprotocol/sdk
+- **Schema验证**: Zod
+- **Transport**: STDIO (标准输入输出)
+- **文件系统**: Node.js fs/promises
+
+## 错误处理
+
+- 自动处理文件路径问题，支持多种部署环境
+- 提供详细的错误信息和建议
+- 当组件不存在时提供可用组件的提示
+
+## 注意事项
+
+1. **项目根目录设置**: 确保正确设置项目根目录，这影响组件文件的查找
+2. **文件权限**: 确保服务器有权限读取项目目录中的文件
+3. **组件信息同步**: 保持 `components-info.json` 文件与实际组件的同步
+4. **项目知识文件**: 确保 `src/resources/project-knowledge.md` 文件存在且内容完整
+5. **首次使用**: 在使用其他工具前，务必先调用 `get_project_knowledge` 获取项目规范
+6. **组件结构**: 推荐按照标准目录结构组织组件文件，以获得最佳体验
+
+## 许可证
+
+MIT License 

package/debug-client.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+async function debugMcpServer() {
+  const transport = new StdioClientTransport({
+    command: "node",
+    args: ["src/index.js"]
+  });
+
+  const client = new Client(
+    {
+      name: "debug-client",
+      version: "1.0.0"
+    },
+    {
+      capabilities: {}
+    }
+  );
+
+  try {
+    console.log("🔌 连接到MCP服务器...");
+    await client.connect(transport);
+    console.log("✅ 连接成功!");
+
+    // 1. 获取工具列表
+    console.log("\n📋 获取工具列表:");
+    const tools = await client.listTools();
+    console.log(JSON.stringify(tools, null, 2));
+
+    // 2. 测试获取组件列表
+    console.log("\n🔍 测试获取组件列表 (限制5个):");
+    const result1 = await client.callTool({
+      name: "get_component_list",
+      arguments: { limit: 5 }
+    });
+    console.log("响应:", JSON.stringify(result1, null, 2));
+
+    // 3. 测试搜索功能
+    console.log("\n🔍 测试搜索功能 (搜索'table'):");
+    const result2 = await client.callTool({
+      name: "get_component_list",
+      arguments: { search: "table", limit: 3 }
+    });
+    console.log("响应:", JSON.stringify(result2, null, 2));
+
+  } catch (error) {
+    console.error("❌ 调试失败:", error);
+  } finally {
+    await client.close();
+    console.log("\n🔌 连接已关闭");
+  }
+}
+
+debugMcpServer().catch(console.error); 

package/docs/src/DPHeader/README.md

@@ -0,0 +1,36 @@
+# DPHeader 组件
+
+页面头部组件，用于显示页面的主标题和副标题。
+
+## 特性
+
+- 支持主标题和可选的副标题显示
+- 可自定义样式类名
+- 响应式设计
+- TypeScript 支持
+
+## 使用场景
+
+- 页面顶部标题展示
+- 文章或内容页面的标题区域
+- 需要突出显示标题的场景
+
+## API 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 描述 |
+|--------|------|------|--------|------|
+| title | string | 是 | - | 页面主标题 |
+| subtitle | string | 否 | - | 页面副标题 |
+| className | string | 否 | '' | 自定义CSS类名 |
+
+## 样式类名
+
+- `.dp-header`: 头部容器
+- `.dp-header__title`: 主标题样式
+- `.dp-header__subtitle`: 副标题样式
+
+## 注意事项
+
+1. 主标题为必填项，副标题为可选
+2. 组件支持自定义样式类名
+3. 建议搭配相应的CSS样式文件使用 

package/docs/src/DPHeader/demo/advanced.tsx

@@ -0,0 +1,49 @@
+// 高级用法示例
+import React from 'react';
+import { DPHeader } from '../../../../src/components/DPHeader/DPHeader';
+
+// 动态标题示例
+export function DynamicHeaderDemo() {
+  const handleTitleClick = () => {
+    console.log('标题被点击了');
+  };
+
+  return (
+    <div>
+      <h2>动态标题示例</h2>
+      
+      <DPHeader 
+        title="可交互的标题" 
+        subtitle="点击查看控制台输出"
+        onClick={handleTitleClick}
+        className="interactive-header"
+      />
+    </div>
+  );
+}
+
+// 多语言支持示例
+export function MultiLanguageDemo() {
+  const titles = {
+    zh: { title: "中文标题", subtitle: "这是中文副标题" },
+    en: { title: "English Title", subtitle: "This is English subtitle" },
+  };
+
+  return (
+    <div>
+      <h2>多语言支持</h2>
+      
+      <DPHeader 
+        title={titles.zh.title}
+        subtitle={titles.zh.subtitle}
+        className="zh-header"
+      />
+      
+      <DPHeader 
+        title={titles.en.title}
+        subtitle={titles.en.subtitle}
+        className="en-header"
+      />
+    </div>
+  );
+} 

package/docs/src/DPHeader/demo/basic.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import { DPHeader } from '../../../../src/components/DPHeader/DPHeader';
+
+export default function BasicDemo() {
+  return (
+    <div>
+      <h2>基础用法</h2>
+      
+      {/* 仅主标题 */}
+      <DPHeader title="页面标题" />
+      
+      {/* 主标题 + 副标题 */}
+      <DPHeader 
+        title="欢迎来到我们的网站" 
+        subtitle="这里是页面的副标题说明"
+      />
+      
+      {/* 自定义样式 */}
+      <DPHeader 
+        title="自定义样式标题" 
+        subtitle="带有自定义类名的标题"
+        className="custom-header"
+      />
+    </div>
+  );
+} 

package/examples/create-button.json

@@ -0,0 +1,38 @@
+{
+  "tool": "create_component",
+  "arguments": {
+    "componentName": "Button",
+    "componentType": "functional",
+    "props": [
+      {
+        "name": "children",
+        "type": "React.ReactNode",
+        "required": true,
+        "description": "Button content"
+      },
+      {
+        "name": "onClick",
+        "type": "() => void",
+        "required": false,
+        "description": "Click handler function"
+      },
+      {
+        "name": "variant",
+        "type": "'primary' | 'secondary' | 'danger'",
+        "required": false,
+        "defaultValue": "'primary'",
+        "description": "Button style variant"
+      },
+      {
+        "name": "disabled",
+        "type": "boolean",
+        "required": false,
+        "defaultValue": "false",
+        "description": "Whether button is disabled"
+      }
+    ],
+    "styling": "css",
+    "includeTests": true,
+    "outputPath": "./src/components"
+  }
+} 

package/examples/create-modal.json

@@ -0,0 +1,43 @@
+{
+  "tool": "create_component",
+  "arguments": {
+    "componentName": "Modal",
+    "componentType": "functional",
+    "props": [
+      {
+        "name": "isOpen",
+        "type": "boolean",
+        "required": true,
+        "description": "Whether modal is visible"
+      },
+      {
+        "name": "onClose",
+        "type": "() => void",
+        "required": true,
+        "description": "Function to close modal"
+      },
+      {
+        "name": "title",
+        "type": "string",
+        "required": false,
+        "description": "Modal title"
+      },
+      {
+        "name": "children",
+        "type": "React.ReactNode",
+        "required": false,
+        "description": "Modal content"
+      },
+      {
+        "name": "size",
+        "type": "'small' | 'medium' | 'large'",
+        "required": false,
+        "defaultValue": "'medium'",
+        "description": "Modal size"
+      }
+    ],
+    "styling": "css",
+    "includeTests": false,
+    "outputPath": "./src/components"
+  }
+} 

package/mcp-config.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "phinix": {
+      "command": "node",
+      "args": ["src/index.js"],
+      "cwd": ".",
+      "env": {}
+    }
+  }
+} 

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "phinix",
+  "version": "0.0.4",
+  "description": "phinix - A Model Context Protocol server for managing and generating React components",
+  "main": "src/index.js",
+  "bin": {
+    "phinix": "src/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "react",
+    "components",
+    "code-generation"
+  ],
+  "author": "Dataphin Team",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}