xiaozhi-client 1.5.0 → 1.6.0-beta.1

package/docs/Architecture.md

@@ -0,0 +1,68 @@
+# 项目架构
+
+```mermaid
+graph TB
+  subgraph ProjectComponents["🏗️ xiaozhi-client"]
+      Core["🔧 核心服务<br/>(Core Service)<br/>MCP Server/Client"]
+      Web["🌐 Web管理界面<br/>(Supervisor)"]
+      CLI["💻 命令行工具<br/>(CLI)"]
+  end
+
+  subgraph Hardware["📱 硬件设备"]
+      ESP32["🎙️ xiaozhi-esp32<br/>(语音互动设备)"]
+  end
+
+  subgraph MCPClients["💼 MCP客户端"]
+      Cursor["Cursor"]
+      Cherry["Cherry Studio"]
+      OtherClient["其他客户端"]
+  end
+
+  subgraph External["☁️ 外部服务"]
+      XiaozhiMe["🌐 xiaozhi.me<br/>(原有服务端)"]
+  end
+
+  subgraph MCPServices["🔌 MCP服务集群"]
+      direction LR
+      MCP1["🏠 Local MCP<br/>(本地服务)"]
+      MCP2["🌍 Remote MCP<br/>(远程服务)"]
+      MCP3["🤖 ModelScope MCP<br/>(模型服务)"]
+      MCPn["⚡ Other MCP<br/>(其他服务)"]
+  end
+
+  %% 新的MCP客户端连接 (重要)
+  Cursor ==>|"MCP协议"| Core
+  Cherry ==>|"MCP协议"| Core
+  OtherClient ==>|"MCP协议"| Core
+
+  %% ESP32连接链路
+  ESP32 -.->|"直连"| Core
+  ESP32 -->|"原有链路"| XiaozhiMe
+  XiaozhiMe --> Core
+
+  %% Core Service到MCP服务
+  Core ==> MCP1
+  Core ==> MCP2
+  Core ==> MCP3
+  Core ==> MCPn
+
+  %% 项目内部管理连接
+  Web -.-> Core
+  CLI -.-> Core
+
+  %% 样式定义
+  classDef coreComponent stroke:#2980b9,stroke-width:3px,fill:#ebf3fd,color:#2c3e50
+  classDef hardware stroke:#e74c3c,stroke-width:2px,fill:#fdedec,color:#2c3e50
+  classDef external stroke:#8e44ad,stroke-width:2px,fill:#f4ecf7,color:#2c3e50
+  classDef mcp stroke:#27ae60,stroke-width:2px,fill:#eafaf1,color:#2c3e50
+  classDef mcpClient stroke:#f39c12,stroke-width:2px,fill:#fef9e7,color:#2c3e50
+  classDef primaryFlow stroke:#27ae60,stroke-width:4px
+  classDef secondaryFlow stroke:#95a5a6,stroke-width:2px
+
+  class Core,Web,CLI coreComponent
+  class ESP32 hardware
+  class XiaozhiMe external
+  class MCP1,MCP2,MCP3,MCPn mcp
+  class Cursor,Cherry,OtherClient mcpClient
+
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xiaozhi-client",
-  "version": "1.5.0",
+  "version": "1.6.0-beta.1",
   "description": "小智 AI 客户端 命令行工具",
   "type": "module",
   "main": "dist/cli.js",
@@ -20,24 +20,6 @@
     "xiaozhi": "./dist/cli.js",
     "xiaozhi-client": "./dist/cli.js"
   },
-  "scripts": {
-    "build": "pnpm run build:web && tsup",
-    "build:web": "cd web && pnpm install && pnpm run build",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:ui": "vitest --ui",
-    "format": "biome format --write .",
-    "lint": "biome lint --write .",
-    "type:check": "tsc --noEmit",
-    "check": "biome check .",
-    "check:write": "biome check --write .",
-    "check:all": "pnpm check && pnpm type:check && pnpm spell:check && pnpm duplicate:check",
-    "spell:check": "cspell \"src/**/*.ts\" \"*.md\" \"*.json\"",
-    "duplicate:check": "jscpd src/",
-    "release": "semantic-release"
-  },
   "keywords": [
     "xiaozhi",
     "mcp",
@@ -56,6 +38,8 @@
     "dotenv": "^16.3.1",
     "eventsource": "^4.0.0",
     "express": "^5.1.0",
+    "json5": "^2.2.3",
+    "jsonc-parser": "^3.3.1",
     "node-fetch": "2",
     "omelette": "^0.4.17",
     "ora": "^8.2.0",
@@ -73,7 +57,7 @@
     "@semantic-release/release-notes-generator": "^14.0.3",
     "@types/eventsource": "^3.0.0",
     "@types/node": "^24.0.1",
-    "@types/node-fetch": "2",
+    "@types/node-fetch": "^2.6.12",
     "@types/omelette": "^0.4.5",
     "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^3.2.3",
@@ -87,5 +71,23 @@
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.3"
+  },
+  "scripts": {
+    "build": "pnpm run build:web && tsup",
+    "build:web": "cd web && pnpm install && pnpm run build",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:ui": "vitest --ui",
+    "format": "biome format --write .",
+    "lint": "biome lint --write .",
+    "type:check": "tsc --noEmit",
+    "check": "biome check .",
+    "check:write": "biome check --write .",
+    "check:all": "pnpm check && pnpm type:check && pnpm spell:check && pnpm duplicate:check",
+    "spell:check": "cspell \"src/**/*.ts\" \"*.md\" \"*.json\"",
+    "duplicate:check": "jscpd src/",
+    "release": "semantic-release"
   }
-}
+}

package/templates/json5/mcpServers/calculator.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Calculator Server - JavaScript Implementation
+ * Provides mathematical calculation tools via MCP protocol
+ * Version: 0.2.0 - Using @modelcontextprotocol/sdk
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// Simple logger utility
+const logger = {
+	info: (message) => {
+		const timestamp = new Date().toISOString();
+		console.error(`${timestamp} - Calculator - INFO - ${message}`);
+	},
+	error: (message) => {
+		const timestamp = new Date().toISOString();
+		console.error(`${timestamp} - Calculator - ERROR - ${message}`);
+	},
+	debug: (message) => {
+		const timestamp = new Date().toISOString();
+		console.error(`${timestamp} - Calculator - DEBUG - ${message}`);
+	},
+};
+
+// Create MCP server instance using the official SDK
+const server = new McpServer({
+	name: "Calculator",
+	version: "0.2.0",
+});
+
+// Register calculator tool using the SDK
+server.tool(
+	"calculator",
+	"For mathematical calculation, always use this tool to calculate the result of a JavaScript expression. Math object and basic operations are available.",
+	{
+		javascript_expression: z
+			.string()
+			.describe("JavaScript expression to evaluate"),
+	},
+	async ({ javascript_expression }) => {
+		try {
+			// Simple and direct evaluation like Python version
+			// Note: In a production environment, you might want to add more security measures
+			const result = eval(javascript_expression);
+			logger.info(
+				`Calculating formula: ${javascript_expression}, result: ${result}`
+			);
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({
+							success: true,
+							result: result,
+						}),
+					},
+				],
+			};
+		} catch (error) {
+			logger.error(`Calculation error: ${error.message}`);
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({
+							success: false,
+							error: error.message,
+						}),
+					},
+				],
+				isError: true,
+			};
+		}
+	}
+);
+
+// Start the server if this file is run directly
+async function main() {
+	logger.info("Starting MCP Calculator server with SDK");
+
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+
+	logger.info("MCP Calculator server is running on stdio");
+}
+
+// Run the server if this file is executed directly
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+
+const currentFile = fileURLToPath(import.meta.url);
+const argFile = process.argv[1] ? resolve(process.argv[1]) : null;
+
+if (argFile && currentFile === argFile) {
+	main().catch((error) => {
+		logger.error(`Failed to start server: ${error.message}`);
+		process.exit(1);
+	});
+}
+
+export default server;

package/templates/json5/mcpServers/datetime.js

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+
+/**
+ * MCP DateTime Server - JavaScript Implementation
+ * Provides date and time tools via MCP protocol
+ * Version: 0.2.0 - Using @modelcontextprotocol/sdk
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// Simple logger utility
+const logger = {
+	info: (message) => {
+		const timestamp = new Date().toISOString();
+		console.error(`${timestamp} - DateTime - INFO - ${message}`);
+	},
+	error: (message) => {
+		const timestamp = new Date().toISOString();
+		console.error(`${timestamp} - DateTime - ERROR - ${message}`);
+	},
+	debug: (message) => {
+		const timestamp = new Date().toISOString();
+		console.error(`${timestamp} - DateTime - DEBUG - ${message}`);
+	},
+};
+
+// Create MCP server instance using the official SDK
+const server = new McpServer({
+	name: "DateTime",
+	version: "0.2.0",
+});
+
+// Register get_current_time tool
+server.tool(
+	"get_current_time",
+	"Get the current time in various formats",
+	{
+		format: z
+			.string()
+			.optional()
+			.describe(
+				"Time format: 'iso' (default), 'timestamp', 'locale', 'time-only'"
+			),
+	},
+	async ({ format = "iso" }) => {
+		try {
+			const now = new Date();
+			let result;
+
+			switch (format) {
+				case "timestamp":
+					result = now.getTime();
+					break;
+				case "locale":
+					result = now.toLocaleString();
+					break;
+				case "time-only":
+					result = now.toLocaleTimeString();
+					break;
+				case "iso":
+				default:
+					result = now.toISOString();
+					break;
+			}
+
+			logger.info(
+				`Getting current time in format: ${format}, result: ${result}`
+			);
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({
+							success: true,
+							result: result,
+							format: format,
+						}),
+					},
+				],
+			};
+		} catch (error) {
+			logger.error(`Get current time error: ${error.message}`);
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({
+							success: false,
+							error: error.message,
+						}),
+					},
+				],
+				isError: true,
+			};
+		}
+	}
+);
+
+// Register get_current_date tool
+server.tool(
+	"get_current_date",
+	"Get the current date in various formats",
+	{
+		format: z
+			.string()
+			.optional()
+			.describe(
+				"Date format: 'iso' (default), 'locale', 'date-only', 'yyyy-mm-dd'"
+			),
+	},
+	async ({ format = "iso" }) => {
+		try {
+			const now = new Date();
+			let result;
+
+			switch (format) {
+				case "locale":
+					result = now.toLocaleDateString();
+					break;
+				case "date-only":
+					result = now.toDateString();
+					break;
+				case "yyyy-mm-dd":
+					result = now.toISOString().split("T")[0];
+					break;
+				case "iso":
+				default:
+					result = now.toISOString();
+					break;
+			}
+
+			logger.info(
+				`Getting current date in format: ${format}, result: ${result}`
+			);
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({
+							success: true,
+							result: result,
+							format: format,
+						}),
+					},
+				],
+			};
+		} catch (error) {
+			logger.error(`Get current date error: ${error.message}`);
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({
+							success: false,
+							error: error.message,
+						}),
+					},
+				],
+				isError: true,
+			};
+		}
+	}
+);
+
+// Register format_datetime tool
+server.tool(
+	"format_datetime",
+	"Format a given date/time string or timestamp into specified format",
+	{
+		datetime: z.string().describe("Date/time string or timestamp to format"),
+		format: z
+			.string()
+			.optional()
+			.describe(
+				"Output format: 'iso', 'locale', 'timestamp', 'yyyy-mm-dd', 'custom'"
+			),
+		custom_format: z
+			.string()
+			.optional()
+			.describe("Custom format string (when format is 'custom')"),
+	},
+	async ({ datetime, format = "iso", custom_format }) => {
+		try {
+			let date;
+
+			// Try to parse the input datetime
+			if (!isNaN(Number(datetime))) {
+				// It's a timestamp
+				date = new Date(Number(datetime));
+			} else {
+				// It's a date string
+				date = new Date(datetime);
+			}
+
+			if (isNaN(date.getTime())) {
+				throw new Error("Invalid date/time format");
+			}
+
+			let result;
+			switch (format) {
+				case "timestamp":
+					result = date.getTime();
+					break;
+				case "locale":
+					result = date.toLocaleString();
+					break;
+				case "yyyy-mm-dd":
+					result = date.toISOString().split("T")[0];
+					break;
+				case "custom":
+					if (custom_format) {
+						// Simple custom formatting (can be extended)
+						result = custom_format
+							.replace("YYYY", date.getFullYear())
+							.replace("MM", String(date.getMonth() + 1).padStart(2, "0"))
+							.replace("DD", String(date.getDate()).padStart(2, "0"))
+							.replace("HH", String(date.getHours()).padStart(2, "0"))
+							.replace("mm", String(date.getMinutes()).padStart(2, "0"))
+							.replace("ss", String(date.getSeconds()).padStart(2, "0"));
+					} else {
+						result = date.toISOString();
+					}
+					break;
+				case "iso":
+				default:
+					result = date.toISOString();
+					break;
+			}
+
+			logger.info(
+				`Formatting datetime: ${datetime} to format: ${format}, result: ${result}`
+			);
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({
+							success: true,
+							result: result,
+							original: datetime,
+							format: format,
+						}),
+					},
+				],
+			};
+		} catch (error) {
+			logger.error(`Format datetime error: ${error.message}`);
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({
+							success: false,
+							error: error.message,
+						}),
+					},
+				],
+				isError: true,
+			};
+		}
+	}
+);
+
+// Register add_time tool
+server.tool(
+	"add_time",
+	"Add or subtract time from a given date/time",
+	{
+		datetime: z.string().describe("Base date/time string or timestamp"),
+		amount: z
+			.number()
+			.describe("Amount to add (positive) or subtract (negative)"),
+		unit: z
+			.string()
+			.describe(
+				"Time unit: 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'weeks', 'months', 'years'"
+			),
+	},
+	async ({ datetime, amount, unit }) => {
+		try {
+			let date;
+
+			// Try to parse the input datetime
+			if (!isNaN(Number(datetime))) {
+				date = new Date(Number(datetime));
+			} else {
+				date = new Date(datetime);
+			}
+
+			if (isNaN(date.getTime())) {
+				throw new Error("Invalid date/time format");
+			}
+
+			// Calculate the new date based on unit
+			const newDate = new Date(date);
+
+			switch (unit.toLowerCase()) {
+				case "milliseconds":
+					newDate.setTime(newDate.getTime() + amount);
+					break;
+				case "seconds":
+					newDate.setTime(newDate.getTime() + amount * 1000);
+					break;
+				case "minutes":
+					newDate.setTime(newDate.getTime() + amount * 60 * 1000);
+					break;
+				case "hours":
+					newDate.setTime(newDate.getTime() + amount * 60 * 60 * 1000);
+					break;
+				case "days":
+					newDate.setDate(newDate.getDate() + amount);
+					break;
+				case "weeks":
+					newDate.setDate(newDate.getDate() + amount * 7);
+					break;
+				case "months":
+					newDate.setMonth(newDate.getMonth() + amount);
+					break;
+				case "years":
+					newDate.setFullYear(newDate.getFullYear() + amount);
+					break;
+				default:
+					throw new Error(`Unsupported time unit: ${unit}`);
+			}
+
+			const result = newDate.toISOString();
+			logger.info(`Adding ${amount} ${unit} to ${datetime}, result: ${result}`);
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({
+							success: true,
+							result: result,
+							original: datetime,
+							amount: amount,
+							unit: unit,
+						}),
+					},
+				],
+			};
+		} catch (error) {
+			logger.error(`Add time error: ${error.message}`);
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({
+							success: false,
+							error: error.message,
+						}),
+					},
+				],
+				isError: true,
+			};
+		}
+	}
+);
+
+// Start the server if this file is run directly
+async function main() {
+	logger.info("Starting MCP DateTime server with SDK");
+
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+
+	logger.info("MCP DateTime server is running on stdio");
+}
+
+// Run the server if this file is executed directly
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+
+const currentFile = fileURLToPath(import.meta.url);
+const argFile = process.argv[1] ? resolve(process.argv[1]) : null;
+
+if (argFile && currentFile === argFile) {
+	main().catch((error) => {
+		logger.error(`Failed to start server: ${error.message}`);
+		process.exit(1);
+	});
+}
+
+export default server;

package/templates/json5/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "hello-world",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "",
+  "keywords": [],
+  "author": "shenjingnan <sjn.code@gmail.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.25.64"
+  }
+}

package/templates/json5/xiaozhi.config.json5

@@ -0,0 +1,41 @@
+{
+  // 小智 AI 客户端配置文件 (JSON5 格式)
+  // JSON5 格式支持注释、尾随逗号等特性，更易于手写和维护
+  
+  // MCP 接入点地址
+  // 请访问 xiaozhi.me 获取你的专属接入点地址
+  mcpEndpoint: "<请填写你的接入点地址（获取地址在 xiaozhi.me）>",
+  
+  // MCP 服务配置
+  mcpServers: {
+    // 计算器服务
+    calculator: {
+      command: "node",
+      args: ["./mcpServers/calculator.js"],
+    },
+    
+    // 日期时间服务
+    datetime: {
+      command: "node",
+      args: ["./mcpServers/datetime.js"],
+    },
+  },
+  
+  // 连接配置
+  connection: {
+    // 心跳检测间隔（毫秒）
+    heartbeatInterval: 30000,
+    
+    // 心跳超时时间（毫秒）
+    heartbeatTimeout: 10000,
+    
+    // 重连间隔（毫秒）
+    reconnectInterval: 5000,
+  },
+  
+  // Web UI 配置
+  webUI: {
+    // Web UI 端口号
+    port: 9999,
+  },
+}