@maplezzk/mcps 1.0.24 → 1.0.29

package/README.md

@@ -6,10 +6,13 @@
 
 ## 功能特性
 
-- 🔌 **服务管理**：轻松添加、移除、查看和更新 MCP 服务（支持 Stdio 和 SSE 模式）。
-- 🛠️ **工具发现**：查看已配置服务中所有可用的工具。
-- 🚀 **工具执行**：直接在命令行调用工具，支持参数自动解析。
-- 🔄 **持久化存储**：配置自动保存至 `~/.mcps/mcp.json`。
+- 🔌 **服务管理**：轻松添加、移除、查看和更新 MCP 服务（支持 Stdio、SSE 和 HTTP 模式）
+- 🛠️ **工具发现**：查看已配置服务中所有可用的工具
+- 🚀 **工具执行**：直接在命令行调用工具，支持参数自动解析
+- 🔄 **守护进程**：保持与 MCP 服务的长连接，显著提高性能
+- 📊 **表格输出**：清晰的服务器状态和工具列表展示
+- 🔍 **工具筛选**：按关键词筛选工具，支持简洁模式
+- 🚨 **详细日志**：可选的详细日志模式，方便调试
 
 ## 安装
 
@@ -17,6 +20,25 @@
 npm install -g @maplezzk/mcps
 ```
 
+## 快速开始
+
+```bash
+# 1. 添加一个服务
+mcps add fetch --command uvx --args mcp-server-fetch
+
+# 2. 启动守护进程
+mcps start
+
+# 3. 查看服务状态
+mcps status
+
+# 4. 查看可用工具
+mcps tools fetch
+
+# 5. 调用工具
+mcps call fetch fetch url="https://example.com"
+```
+
 ## 使用指南
 
 ### 1. 守护进程 (Daemon Mode)
@@ -25,12 +47,25 @@ mcps 支持守护进程模式，可以保持与 MCP 服务的长连接，显著
 
 **启动守护进程：**
 ```bash
+# 普通模式
 mcps start
+
+# 详细模式（显示每个服务器的连接过程和禁用的服务器）
+mcps start --verbose
 ```
 
-**重启连接：**
-如果修改了配置文件，或者服务出现异常，可以使用重启命令刷新连接：
+输出示例：
+```
+Starting daemon in background...
+[Daemon] Connecting to 7 server(s)...
+[Daemon] - chrome-devtools... Connected ✓
+[Daemon] - fetch... Connected ✓
+[Daemon] - gitlab-mr-creator... Connected ✓
+[Daemon] Connected: 7/7
+Daemon started successfully on port 4100.
+```
 
+**重启连接：**
 ```bash
 # 重置所有连接
 mcps restart
@@ -49,15 +84,36 @@ mcps stop
 mcps status
 ```
 
-> **注意**：旧的三词命令（如 `mcps daemon start`）仍然可用，保持向后兼容。
+输出示例：
+```
+Daemon is running (v1.0.29)
+
+Active Connections:
+NAME                STATUS      TOOLS
+─────────────────   ──────────  ──────
+chrome-devtools     Connected   26
+fetch               Connected   1
+gitlab-mr-creator   Connected   30
+Total: 3 connection(s)
+```
 
 ### 2. 服务管理 (Server Management)
 
-**查看所有服务：**
+**查看所有服务（配置信息）：**
 ```bash
 mcps ls
 ```
 
+输出示例：
+```
+NAME                TYPE    ENABLED  COMMAND/URL
+─────────────────   ──────  ───────  ─────────────
+chrome-devtools     stdio   ✓        npx -y chrome-devtools-mcp ...
+fetch               stdio   ✓        uvx mcp-server-fetch
+my-server           stdio   ✗        npx my-server
+Total: 3 server(s)
+```
+
 **添加 Stdio 服务：**
 ```bash
 # 添加本地 Node.js 服务
@@ -65,6 +121,9 @@ mcps add my-server --command node --args ./build/index.js
 
 # 使用 npx/uvx 添加服务
 mcps add fetch --command uvx --args mcp-server-fetch
+
+# 添加带环境变量的服务
+mcps add my-db --command npx --args @modelcontextprotocol/server-postgres --env POSTGRES_CONNECTION_STRING="${DATABASE_URL}"
 ```
 
 **添加 SSE 服务：**
@@ -92,13 +151,61 @@ mcps update my-server --command new-command
 
 # 更新特定服务的参数
 mcps update my-server --args arg1 arg2
+
+# 同时更新命令和参数
+mcps update my-server --command node --args ./new-build/index.js
 ```
 
 ### 3. 工具交互 (Tool Interaction)
 
 **查看服务下的可用工具：**
 ```bash
-mcps tools fetch
+# 详细模式（显示所有信息）
+mcps tools chrome-devtools
+
+# 简洁模式（只显示工具名称）
+mcps tools chrome-devtools --simple
+
+# 筛选工具（按关键词）
+mcps tools chrome-devtools --tool screenshot
+
+# 多个关键词 + 简洁模式
+mcps tools gitlab-mr-creator --tool file --tool wiki --simple
+```
+
+详细模式输出示例：
+```
+Available Tools for chrome-devtools:
+
+- take_screenshot
+  Take a screenshot of the page or element.
+  Arguments:
+    format*: string (Type of format to save the screenshot as...)
+    quality: number (Compression quality from 0-100)
+    uid: string (The uid of an element to screenshot...)
+    ...
+
+- click
+  Clicks on the provided element
+  Arguments:
+    uid*: string (The uid of an element...)
+    ...
+```
+
+简洁模式输出示例：
+```
+$ mcps tools chrome-devtools -s
+click
+close_page
+drag
+emulate
+evaluate_script
+fill
+...
+take_screenshot
+take_snapshot
+
+Total: 26 tool(s)
 ```
 
 **调用工具：**
@@ -117,11 +224,17 @@ mcps call <server_name> <tool_name> [arguments...]
 # 简单的字符串参数
 mcps call fetch fetch url="https://example.com"
 
+# 带多个参数
+mcps call fetch fetch url="https://example.com" max_length=5000
+
 # JSON 对象参数
 mcps call my-server createUser user='{"name": "Alice", "age": 30}'
 
 # 布尔值/数字参数
-mcps call my-server config debug=true timeout=5000
+mcps call chrome-devtools take_screenshot fullPage=true quality=90
+
+# 混合参数
+mcps call my-server config debug=true timeout=5000 options='{"retries": 3}'
 ```
 
 ## 配置文件
@@ -129,7 +242,99 @@ mcps call my-server config debug=true timeout=5000
 默认情况下，配置文件存储在：
 `~/.mcps/mcp.json`
 
-您可以通过设置 `MCP_CONFIG_DIR` 环境变量来更改存储位置。
+您可以通过设置 `MCPS_CONFIG_DIR` 环境变量来更改存储位置。
+
+配置文件示例：
+```json
+{
+  "servers": [
+    {
+      "name": "fetch",
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["mcp-server-fetch"]
+    },
+    {
+      "name": "my-server",
+      "type": "stdio",
+      "command": "node",
+      "args": ["./build/index.js"],
+      "env": {
+        "API_KEY": "${API_KEY}"
+      },
+      "disabled": false
+    }
+  ]
+}
+```
+
+## 环境变量
+
+- `MCPS_CONFIG_DIR`: 配置文件目录（默认：`~/.mcps`）
+- `MCPS_PORT`: Daemon 端口（默认：`4100`）
+- `MCPS_VERBOSE`: 详细日志模式（默认：`false`）
+
+## 命令参考
+
+### 服务管理
+- `mcps ls` - 列出所有服务
+- `mcps add <name>` - 添加新服务
+- `mcps rm <name>` - 移除服务
+- `mcps update [name]` - 更新服务配置
+
+### 守护进程
+- `mcps start [-v]` - 启动守护进程（`-v` 显示详细日志）
+- `mcps stop` - 停止守护进程
+- `mcps status` - 查看守护进程状态
+- `mcps restart [server]` - 重启守护进程或特定服务
+
+### 工具交互
+- `mcps tools <server> [-s] [-t <name>...]` - 查看可用工具
+  - `-s, --simple`: 只显示工具名称
+  - `-t, --tool`: 按名称筛选工具（可重复使用）
+- `mcps call <server> <tool> [args...]` - 调用工具
+
+## 性能优化
+
+mcps 通过以下方式优化性能：
+
+1. **守护进程模式**：保持长连接，避免重复启动开销
+2. **工具缓存**：连接时缓存工具数量，避免重复查询
+3. **异步连接**：并行初始化多个服务器连接
+
+典型性能：
+- 启动守护进程：10-15 秒（首次，取决于服务数量）
+- 查看状态：~200ms
+- 调用工具：~50-100ms
+
+## 常见问题
+
+**Q: 如何查看所有服务器的运行状态？**
+```bash
+mcps status  # 查看活跃连接
+mcps ls      # 查看所有配置（包括禁用的）
+```
+
+**Q: 某个服务连接失败了怎么办？**
+```bash
+# 查看详细日志
+mcps start --verbose
+
+# 重启该服务
+mcps restart my-server
+```
+
+**Q: 如何临时禁用某个服务？**
+在配置文件中设置 `"disabled": true`，或使用 `mcps update` 修改配置。
+
+**Q: 工具太多怎么快速找到？**
+```bash
+# 筛选工具名称
+mcps tools my-server --tool keyword
+
+# 只显示名称
+mcps tools my-server --simple
+```
 
 ## 许可证
 

package/dist/commands/tools.js

@@ -29,7 +29,9 @@ function printTools(serverName, tools) {
 export const registerToolsCommand = (program) => {
     program.command('tools <server>')
         .description('List available tools on a server')
-        .action(async (serverName) => {
+        .option('-s, --simple', 'Show only tool names')
+        .option('-t, --tool <name...>', 'Filter tools by name(s)')
+        .action(async (serverName, options) => {
         // Check if server exists in config first
         const serverConfig = configManager.getServer(serverName);
         if (!serverConfig) {
@@ -40,8 +42,25 @@ export const registerToolsCommand = (program) => {
             // Auto-start daemon if needed
             await DaemonClient.ensureDaemon();
             // List via daemon
-            const tools = await DaemonClient.listTools(serverName);
-            printTools(serverName, tools);
+            let tools = await DaemonClient.listTools(serverName);
+            // Filter by tool names if specified
+            if (options.tool && options.tool.length > 0) {
+                const filters = Array.isArray(options.tool) ? options.tool : [options.tool];
+                tools = tools.filter((tool) => filters.some((filter) => tool.name.toLowerCase().includes(filter.toLowerCase())));
+            }
+            if (!tools || tools.length === 0) {
+                console.log(chalk.yellow('No tools found.'));
+                return;
+            }
+            if (options.simple) {
+                // Simple mode: only show tool names
+                tools.forEach((tool) => console.log(tool.name));
+                console.log(chalk.gray(`\nTotal: ${tools.length} tool(s)`));
+            }
+            else {
+                // Detailed mode: show full tool information
+                printTools(serverName, tools);
+            }
         }
         catch (error) {
             console.error(chalk.red(`Failed to list tools: ${error.message}`));

package/dist/core/client.js

@@ -70,7 +70,7 @@ export class McpClientService {
             await this.client.connect(this.transport);
         }
         catch (error) {
-            console.error(`Failed to connect to server ${config.name}:`, error);
+            // Error will be handled by the caller
             throw error;
         }
     }

package/dist/core/config.js

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { ServerConfigSchema } from '../types/config.js';
-const CONFIG_DIR = process.env.MCP_CONFIG_DIR || path.join(os.homedir(), '.mcps');
+const CONFIG_DIR = process.env.MCPS_CONFIG_DIR || path.join(os.homedir(), '.mcps');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'mcp.json');
 export class ConfigManager {
     ensureConfigDir() {

package/dist/core/daemon-client.js

@@ -61,7 +61,7 @@ export class DaemonClient {
             throw new Error(err.error || 'Daemon error');
         }
         const data = await response.json();
-        // The daemon returns { tools: { tools: [...] } } because of ListToolsResult wrapping
-        return data.tools.tools || [];
+        // The daemon returns { tools: [...] }
+        return data.tools || [];
     }
 }

package/dist/core/pool.js

@@ -2,6 +2,7 @@ import { McpClientService } from './client.js';
 import { configManager } from './config.js';
 export class ConnectionPool {
     clients = new Map();
+    toolsCache = new Map();
     initializing = false;
     initialized = false;
     async getClient(serverName, options) {
@@ -24,6 +25,15 @@ export class ConnectionPool {
             await connectPromise;
         }
         this.clients.set(serverName, client);
+        // Cache tools count after connection
+        try {
+            const result = await client.listTools();
+            this.toolsCache.set(serverName, result.tools.length);
+        }
+        catch (e) {
+            // Connection succeeded but listTools failed, cache as 0
+            this.toolsCache.set(serverName, 0);
+        }
         return client;
     }
     async closeClient(serverName) {
@@ -36,6 +46,7 @@ export class ConnectionPool {
                 console.error(`[Daemon] Error closing ${serverName}:`, e);
             }
             this.clients.delete(serverName);
+            this.toolsCache.delete(serverName);
             return true;
         }
         return false;
@@ -51,6 +62,7 @@ export class ConnectionPool {
             }
         }
         this.clients.clear();
+        this.toolsCache.clear();
     }
     async initializeAll() {
         const servers = configManager.listServers();
@@ -74,21 +86,29 @@ export class ConnectionPool {
         console.log(`[Daemon] Connecting to ${enabledServers.length} server(s)...`);
         const results = [];
         for (const server of enabledServers) {
-            if (verbose) {
-                process.stdout.write(`[Daemon] - ${server.name}... `);
-            }
+            process.stdout.write(`[Daemon] - ${server.name}... `);
             try {
                 await this.getClient(server.name, { timeoutMs: 8000 });
                 results.push({ name: server.name, success: true });
-                if (verbose) {
-                    console.log('✓');
-                }
+                console.log('Connected ✓');
             }
             catch (error) {
-                results.push({ name: server.name, success: false, error: error.message });
+                // Extract clean error message
+                let errorMsg = 'Unknown error';
+                if (error?.message) {
+                    // For spawn errors, the message usually contains the essential info
+                    errorMsg = error.message;
+                }
+                else if (typeof error === 'string') {
+                    errorMsg = error;
+                }
+                else if (error) {
+                    errorMsg = String(error);
+                }
+                results.push({ name: server.name, success: false, error: errorMsg });
+                console.log('Failed ✗');
                 if (verbose) {
-                    console.log('✗');
-                    console.error(`[Daemon] Error: ${error.message}`);
+                    console.error(`[Daemon] Error: ${errorMsg}`);
                 }
             }
         }
@@ -96,9 +116,10 @@ export class ConnectionPool {
         const successCount = results.filter(r => r.success).length;
         const failed = results.filter(r => !r.success);
         console.log(`[Daemon] Connected: ${successCount}/${enabledServers.length}`);
-        if (!verbose && failed.length > 0) {
+        if (failed.length > 0) {
+            console.log('[Daemon] Failed connections:');
             failed.forEach(f => {
-                console.error(`[Daemon] ✗ ${f.name}: ${f.error}`);
+                console.log(`  ✗ ${f.name}: ${f.error}`);
             });
         }
         this.initializing = false;
@@ -113,12 +134,20 @@ export class ConnectionPool {
             let toolsCount = null;
             let status = 'connected';
             if (includeTools) {
-                try {
-                    const result = await client.listTools();
-                    toolsCount = result.tools.length;
+                // Use cached tools count instead of calling listTools again
+                if (this.toolsCache.has(name)) {
+                    toolsCount = this.toolsCache.get(name);
                 }
-                catch (e) {
-                    status = 'error';
+                else {
+                    // Fallback: if not cached, fetch it now
+                    try {
+                        const result = await client.listTools();
+                        toolsCount = result.tools.length;
+                        this.toolsCache.set(name, toolsCount);
+                    }
+                    catch (e) {
+                        status = 'error';
+                    }
                 }
             }
             details.push({ name, toolsCount, status });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maplezzk/mcps",
-  "version": "1.0.24",
+  "version": "1.0.29",
   "description": "A CLI to manage and use MCP servers",
   "publishConfig": {
     "access": "public"