freeform-modeling-mcp 1.0.26

package/README.md

@@ -0,0 +1,61 @@
+# 酷大师 MCP Server
+
+## 核心功能
+- 🔌 WebSocket桥接服务（详见`src/llmClient.ts`）
+- 🧰 丰富工具集（`src/tools/`包含50+建模工具）
+  - 基础建模工具（立方体/球体/圆环创建）
+  - KJL资源库集成（资产搜索/置入/替换）
+  - Tripo3D AI生成
+  - 材质替换
+
+## 快速开始
+
+### 运行环境准备
+1. 安装Node.js（**v18+**）：
+   - 官方下载：[Node.js 18+](https://nodejs.org/zh-cn/download)
+2. 打开系统终端：
+   - Mac系统：[终端使用指南](https://support.apple.com/zh-cn/guide/terminal/apd5265185d-f365-44cb-8b09-71a064a42125/mac)
+   - Windows系统：[CMD打开方式](https://blog.csdn.net/B11050729/article/details/131494056)
+
+### 启动服务
+```bash
+npx -y freeform-modeling-mcp
+```
+当终端显示`MCP Server Endpoint: `即表示启动成功
+
+
+### 故障排除
+若启动失败，可尝试安装指定版本：
+```bash
+npm i -g freeform-modeling-mcp@1.0.26 --registry=https://registry.npmjs.org
+```
+
+## 核心模块
+### 1. 工具系统 (`src/tools/`)
+- **建模工具**：面操作/辅助曲线/扫描建模
+- **资产工具**：KJL资源搜索/批量置入
+- **反馈工具**：场景截图/对象快照
+- **交互工具**：对象选择/移动/旋转/缩放
+
+### 2. 客户端连接 (`src/llmClient.ts`)
+- WebSocket长连接管理
+- 命令队列与超时控制
+- 客户端状态监测
+
+### 3. 提示策略 (`src/prompt.ts`)
+```
+包含300+条建模规范：
+- 坐标系标准 (Z-up右手系)
+- 单位系统 (毫米级精度)
+- 碰撞检测规则
+- KJL资产优先策略
+```
+
+
+## 开发指南
+1. 工具扩展：在`src/tools/`创建新工具类
+2. API集成：参考`tripo3d-tools.ts`接入第三方服务
+3. 客户端协议：遵循`llmClient.ts`定义的消息格式
+
+## 贡献者协议
+请遵循`src/prompt.ts`中定义的建模规范提交代码

package/index.cjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+// 使用 npx tsx 运行 TypeScript 源文件
+/* eslint-disable @typescript-eslint/no-var-requires */
+const { sync: spawnSync } = require('cross-spawn');
+const path = require('path');
+
+// 找到项目根目录的 src/cli.ts 文件
+const cliPath = path.resolve(__dirname, './src/cli.ts');
+
+const args = process.argv.slice(2);
+
+const result = spawnSync('npx', ['tsx', cliPath, ...args], {
+    stdio: 'inherit',
+    env: {
+        ...process.env,
+    },
+});
+
+// 使用相同的退出码
+process.exit(result.status || 0);

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "freeform-modeling-mcp",
+  "version": "1.0.26",
+  "description": "KooMaster MCP Server with WebSocket Bridge",
+  "main": "index.cjs",
+  "type": "module",
+  "bin": {
+    "freeform-modeling-mcp": "index.cjs"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "author": "cadevsh",
+  "scripts": {
+    "inspect": "npx fastmcp inspect src/dev.ts",
+    "dev": "npx fastmcp dev src/dev.ts",
+    "status": "npx tsx src/cli.ts status",
+    "port": "npx tsx src/cli.ts port"
+  },
+  "license": "ISC",
+  "dependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.1",
+    "@types/node": "22.13.5",
+    "@types/uuid": "^10.0.0",
+    "axios": "1.3.4",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "cors": "^2.8.5",
+    "cross-spawn": "^7.0.6",
+    "draco3d": "^1.5.6",
+    "express": "^4.17.1",
+    "fastmcp": "^4.0.0",
+    "fflate": "^0.7.4",
+    "figures": "^6.1.0",
+    "jszip": "^3.10.1",
+    "multer": "^1.4.5-lts.1",
+    "node-fetch": "^3.3.2",
+    "nodemon": "^3.1.9",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "uuid": "^11.1.0",
+    "ws": "^8.18.1",
+    "zod": "^3.25.63"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,47 @@
+import { Command } from 'commander';
+import { startMCPServer } from './commands/start';
+import { getServerStatus } from './commands/status';
+
+const program = new Command();
+
+program
+    .name('freeform-modeling-mcp')
+    .description('KooMaster MCP Server with WebSocket Bridge')
+
+// 启动服务命令
+program
+    .command('start')
+    .description('Start the MCP server and WebSocket bridge')
+    .option('--stdio', 'Output results via standard input/output')
+    .action(async (options) => {
+        await startMCPServer({
+            stdio: options.stdio
+        });
+    });
+
+// 查询服务状态命令
+program
+    .command('status')
+    .description('Show the status of all running servers')
+    .action(async () => {
+        await getServerStatus();
+    });
+
+// 获取端口号命令
+program
+    .command('port')
+    .description('Get the port of the running WebSocket bridge')
+    .option('--url', 'Output as WebSocket URL instead of just port number')
+    .action(async (options) => {
+        await getServerStatus({
+            portOnly: true,
+            asUrl: options.url
+        });
+    });
+
+// 默认命令（如果没有指定命令则启动服务器）
+if (process.argv.length <= 2) {
+    process.argv.push('start');
+}
+
+program.parse();

package/src/commands/start.ts

@@ -0,0 +1,88 @@
+import { createServer, shutdownServer } from '../server';
+// import { ProxyServiceManager } from '../lib/fileproxy';
+import { WebSocketBridge } from '../lib/wsbridge/bridge';
+import { llmClient } from '../llmClient';
+import logger from '../lib/logger';
+import { findAvailablePort } from '../lib/utils';
+import { printServerInfo } from '../lib/print';
+
+// 启动服务器
+export async function startMCPServer(options: { dev?: boolean, stdio?: boolean } = {}) {
+    try {
+        const isDevMode = options.dev || false;
+        const stdioMode = options.stdio || false;
+
+        // 初始化 WebSocket 服务器
+        logger.info('Initializing WebSocket server...');
+
+        const wsBridge = new WebSocketBridge();
+        await wsBridge.initialize();
+        const wsPort = wsBridge.getPort();
+        const wsUrl = `ws://localhost:${wsPort}`;
+
+        await llmClient.connect(wsUrl);
+
+        // // 启动文件下载代理服务
+        // const manager = new ProxyServiceManager();
+        // await manager.start();
+
+        // 创建 MCP 服务器
+        logger.info('Creating MCP server...');
+        const server = createServer();
+
+        // 处理进程终止信号
+        process.on('SIGINT', async () => {
+            logger.info('Caught SIGINT, shutting down...');
+            await shutdownServer();
+            process.exit(0);
+        });
+
+        process.on('SIGTERM', async () => {
+            logger.info('Caught SIGTERM, shutting down...');
+            await shutdownServer();
+            process.exit(0);
+        });
+
+        if (!isDevMode && !stdioMode) {
+            const port = await findAvailablePort(7764); // 尝试从7764开始，找到第一个可用端口
+
+            await server.start({
+                transportType: "sse",
+                sse: {
+                    endpoint: `/sse`,
+                    port: port,
+                }
+            });
+
+            // Print server information in a visually appealing way
+            const sseUrl = `http://localhost:${port}/sse`;
+
+            printServerInfo(
+                'SERVER STARTED SUCCESSFULLY',
+                [
+                    { label: 'MCP Server Endpoint:', value: sseUrl },
+                    { label: 'KooMaster Bridge Server Address:', value: wsUrl }
+                ],
+                {
+                    icon: '📱',
+                    text: 'Enter Bridge Server Address "VALUE" in the KooMaster app to connect',
+                    value: wsUrl
+                }
+            );
+
+            // Also log to file with simpler format
+            logger.info(`MCP server started with SSE endpoint: ${sseUrl}`);
+            logger.info(`WebSocket Bridge running on port: ${wsPort}`);
+        } else {
+            await server.start({
+                transportType: "stdio",
+            });
+            logger.error('Computer control MCP server running on stdio');
+        }
+
+    } catch (error) {
+        logger.error('Failed to start servers:', error);
+        await shutdownServer().catch(err => logger.error('Error during shutdown:', err));
+        process.exit(1);
+    }
+}

package/src/commands/status.ts

@@ -0,0 +1,81 @@
+import { getActiveBridges } from '../lib/wsbridge/lock';
+import * as http from 'http';
+
+interface StatusOptions {
+    portOnly?: boolean;
+    asUrl?: boolean;
+}
+
+export async function getServerStatus(options: StatusOptions = {}): Promise<void> {
+    const activeBridges = getActiveBridges();
+
+    if (activeBridges.length === 0) {
+        if (!options.portOnly) {
+            console.log('No KooMaster MCP servers are currently running.');
+        }
+        process.exit(0);
+        return;
+    }
+
+    // 如果只需要输出端口信息
+    if (options.portOnly) {
+        const port = activeBridges[0].port;
+        if (options.asUrl) {
+            console.log(`ws://localhost:${port}`);
+        } else {
+            console.log(port);
+        }
+        return;
+    }
+
+    // 输出详细状态信息
+    console.log('Active KooMaster MCP servers:');
+
+    for (const bridge of activeBridges) {
+        console.log(`\nPID: ${bridge.pid}, Port: ${bridge.port}`);
+        console.log(`WebSocket URL: ws://localhost:${bridge.port}`);
+
+        // 尝试获取更多状态信息
+        try {
+            const status = await fetchBridgeStatus(bridge.port);
+            if (status) {
+                console.log('Status:', status.status);
+                console.log('Connected clients:');
+                console.log(`  Total: ${status.clients.total}`);
+                console.log(`  MCP: ${status.clients.mcp}`);
+                console.log(`  Koomaster: ${status.clients.koomaster}`);
+            }
+        } catch (error) {
+            console.log('Status: Unable to fetch detailed status');
+        }
+    }
+}
+
+// 从桥接服务器获取状态信息
+async function fetchBridgeStatus(port: number): Promise<any> {
+    return new Promise((resolve, reject) => {
+        const req = http.get(`http://localhost:${port}/bridge-status`, (res) => {
+            let data = '';
+
+            res.on('data', (chunk) => {
+                data += chunk;
+            });
+
+            res.on('end', () => {
+                try {
+                    const status = JSON.parse(data);
+                    resolve(status);
+                } catch (error) {
+                    reject(new Error('Invalid status response'));
+                }
+            });
+        });
+
+        req.on('error', reject);
+
+        req.setTimeout(2000, () => {
+            req.destroy();
+            reject(new Error('Status request timeout'));
+        });
+    });
+}

package/src/dev.ts

@@ -0,0 +1,24 @@
+import { Command } from 'commander';
+import { startMCPServer } from './commands/start';
+import { getServerStatus } from './commands/status';
+
+const program = new Command();
+
+program
+    .name('freeform-modeling-mcp')
+    .description('KooMaster MCP Server with WebSocket Bridge')
+
+// 启动服务命令
+program
+    .command('start')
+    .description('Start the MCP server and WebSocket bridge')
+    .action(async () => {
+        await startMCPServer({ dev: true });
+    });
+
+// 默认命令（如果没有指定命令则启动服务器）
+if (process.argv.length <= 2) {
+    process.argv.push('start');
+}
+
+program.parse();