Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 22 additions & 7 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,11 +61,23 @@ node dist/index.js <command>

## 测试

**运行测试:**
**⚠️ 重要:完整检查流程**
```bash
# 运行所有测试
npm test
# 推荐方式:一次性运行构建和测试
npm run check

# 或分步执行(确保两步都通过!)
npm run build # TypeScript 类型检查
npm test # 运行测试套件
```

**为什么需要 `npm run build`?**
- `npm test` 只运行 vitest,不会进行完整的 TypeScript 类型检查
- `npm run build` 执行 `tsc` 进行严格的类型检查
- **必须两者都通过才能提交代码**

**其他测试命令:**
```bash
# 监听模式(开发时推荐)
npm run test:watch

Expand All @@ -80,6 +92,7 @@ npm run test:coverage
- 所有测试必须通过
- 新功能需要添加相应的测试
- 保持测试覆盖率在合理水平
- **TypeScript 编译必须无错误**

---

Expand Down Expand Up @@ -198,16 +211,19 @@ gh pr create --title "feat: 功能标题" --body "PR 描述"
- ✅ 代码已提交到功能分支(非 main 分支)
- ✅ **新功能包含对应的单元测试**
- ✅ **版本号已使用 `npm version` 更新(如需要发布)**
- ✅ `npm run build` 构建成功
- ✅ **`npm run build` TypeScript 编译成功**
- ✅ `npm test` 所有测试通过
- ✅ 提交信息符合规范
- ✅ PR 描述清晰说明了变更内容

**⚠️ 重要提示:** 推荐使用 `npm run check` 一次性验证构建和测试!

### ⚠️ 常见错误(真实案例)

| 错误 | 后果 | 正确做法 |
|------|------|----------|
| 直接在 `main` 分支开发 | 污染主分支,无法创建干净的 PR | 始终创建 `feature/` 或 `fix/` 分支 |
| 只运行 `npm test` 不运行 `npm run build` | TypeScript 类型检查错误被遗漏到 CI | **必须运行** `npm run check` 或 `npm run build && npm test` |
| PR 创建后才更新版本号 | 版本提交不在 PR 中,合并后版本不一致 | **提 PR 前**执行 `npm version` |
| PR 合并后继续往旧分支提交 | 提交无法进入新的 PR,需要 cherry-pick | PR 合并后,从最新的 `main` 创建新分支 |
| 新功能不写测试 | 代码质量无法保证,容易回归 | 功能代码和测试代码一起提交 |
Expand Down Expand Up @@ -240,9 +256,8 @@ git checkout -b feature/my-feature
# - 编写单元测试
# - 确保测试覆盖新功能

# 4. 构建和测试
npm run build
npm test
# 4. ⚠️ 完整检查(必须两步都通过!)
npm run check # 等同于:npm run build && npm test

# 5. 提交代码(包括功能代码和测试代码)
git add .
Expand Down
14 changes: 8 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,36 +160,37 @@ mcps update my-server --command node --args ./new-build/index.js

**List available tools on a server:**
```bash
# Detailed mode (show all information)
# Detailed mode (show all information including nested object properties)
mcps tools chrome-devtools

# Simple mode (show only tool names)
mcps tools chrome-devtools --simple

# JSON output (raw tool schema)
mcps tools chrome-devtools --json

# Filter tools by keyword
mcps tools chrome-devtools --tool screenshot

# Multiple keywords + simple mode
mcps tools gitlab-mr-creator --tool file --tool wiki --simple
```

Detailed mode output example:
Detailed mode output example (with nested objects):
```
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...)
format*: string ["jpeg", "png", "webp"] (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...)
...
```

Simple mode output example:
Expand Down Expand Up @@ -324,8 +325,9 @@ Configuration file example:
- `mcps restart [server]` - Restart daemon or specific server

### Tool Interaction
- `mcps tools <server> [-s] [-t <name>...]` - List available tools
- `mcps tools <server> [-s] [-j] [-t <name>...]` - List available tools
- `-s, --simple`: Show only tool names
- `-j, --json`: Output raw JSON (for debugging)
- `-t, --tool`: Filter tools by name (can be used multiple times)
- `mcps call <server> <tool> [args...]` - Call a tool

Expand Down
14 changes: 8 additions & 6 deletions README.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,36 +161,37 @@ mcps update my-server --command node --args ./new-build/index.js

**查看服务下的可用工具:**
```bash
# 详细模式(显示所有信息)
# 详细模式(显示所有信息,包括嵌套对象属性)
mcps tools chrome-devtools

# 简洁模式(只显示工具名称)
mcps tools chrome-devtools --simple

# JSON 输出(原始工具 schema)
mcps tools chrome-devtools --json

# 筛选工具(按关键词)
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...)
format*: string ["jpeg", "png", "webp"] (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...)
...
```

简洁模式输出示例:
Expand Down Expand Up @@ -325,8 +326,9 @@ mcps call my-server createUser --json params.json
- `mcps restart [server]` - 重启守护进程或特定服务

### 工具交互
- `mcps tools <server> [-s] [-t <name>...]` - 查看可用工具
- `mcps tools <server> [-s] [-j] [-t <name>...]` - 查看可用工具
- `-s, --simple`: 只显示工具名称
- `-j, --json`: 输出原始 JSON(用于调试)
- `-t, --tool`: 按名称筛选工具(可重复使用)
- `mcps call <server> <tool> [args...]` - 调用工具

Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@maplezzk/mcps",
"version": "1.4.1",
"version": "1.5.0",
"description": "A CLI to manage and use MCP servers",
"publishConfig": {
"access": "public"
Expand Down Expand Up @@ -30,6 +30,7 @@
"prepublishOnly": "npm run build && npm run test",
"start": "node dist/index.js",
"dev": "ts-node src/index.ts",
"check": "npm run build && npm test",
"test": "vitest run",
"test:watch": "vitest",
"test:ui": "vitest --ui",
Expand Down
36 changes: 34 additions & 2 deletions src/commands/tools.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,31 @@ import chalk from 'chalk';
import { configManager } from '../core/config.js';
import { DaemonClient } from '../core/daemon-client.js';

function printProperty(key: string, value: any, required: boolean, indent: number) {
const indentStr = ' '.repeat(indent);
const requiredMark = required ? chalk.red('*') : '';
const desc = value.description ? ` (${value.description})` : '';

if (value.type === 'object' && value.properties) {
console.log(`${indentStr}${key}${requiredMark}: object${desc}`);
const nestedRequired = value.required || [];
Object.entries(value.properties).forEach(([nestedKey, nestedValue]: [string, any]) => {
printProperty(nestedKey, nestedValue as any, nestedRequired.includes(nestedKey), indent + 1);
});
} else {
let typeInfo = value.type || 'any';
if (value.type === 'array' && value.items) {
const itemType = value.items.type || 'any';
typeInfo = `array of ${itemType}`;
}
if (value.enum) {
const enumValues = value.enum.map((v: any) => typeof v === 'string' ? `"${v}"` : String(v)).join(', ');
typeInfo += ` [${enumValues}]`;
}
console.log(`${indentStr}${key}${requiredMark}: ${typeInfo}${desc}`);
}
}

function printTools(serverName: string, tools: any) {
console.log(chalk.bold(`\nAvailable Tools for ${serverName}:`));
if (!tools || tools.length === 0) {
Expand All @@ -16,9 +41,9 @@ function printTools(serverName: string, tools: any) {
console.log(chalk.gray(' Arguments:'));
const schema = tool.inputSchema as any;
if (schema.properties) {
const required = schema.required || [];
Object.entries(schema.properties).forEach(([key, value]: [string, any]) => {
const required = schema.required?.includes(key) ? chalk.red('*') : '';
console.log(` ${key}${required}: ${value.type || 'any'} ${value.description ? `(${value.description})` : ''}`);
printProperty(key, value, required.includes(key), 2);
});
} else {
console.log(' None');
Expand All @@ -31,6 +56,7 @@ export const registerToolsCommand = (program: Command) => {
program.command('tools <server>')
.description('List available tools on a server')
.option('-s, --simple', 'Show only tool names')
.option('-j, --json', 'Output raw JSON')
.option('-t, --tool <name...>', 'Filter tools by name(s)')
.action(async (serverName, options) => {
// Check if server exists in config first
Expand Down Expand Up @@ -62,6 +88,12 @@ export const registerToolsCommand = (program: Command) => {
return;
}

if (options.json) {
// Raw JSON output
console.log(JSON.stringify(tools, null, 2));
return;
}

if (options.simple) {
// Simple mode: only show tool names
tools.forEach((tool: any) => console.log(tool.name));
Expand Down
Loading