From 5be865eb7d1993b10d48e7e02ed1b1d330700f61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=AC=E6=98=8E?= <83812544+Ed1s0nZ@users.noreply.github.com> Date: Fri, 14 Nov 2025 00:30:33 +0800 Subject: [PATCH] Add files via upload --- tools/README.md | 24 ++-- tools/README_EN.md | 319 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 331 insertions(+), 12 deletions(-) create mode 100644 tools/README_EN.md diff --git a/tools/README.md b/tools/README.md index 5af8f4a6..776e0e3e 100644 --- a/tools/README.md +++ b/tools/README.md @@ -6,20 +6,20 @@ ## 配置文件格式 -每个工具配置文件是一个 YAML 文件，包含以下字段： +每个工具配置文件是一个 YAML 文件。下表列出了当前支持的顶层字段及其必填情况，建议逐项核对后再提交： -### 必需字段 +| 字段 | 必填 | 类型 | 说明 | +|------|------|------|------| +| `name` | ✅ | string | 工具唯一标识，建议使用小写字母、数字、短横线组合。 | +| `command` | ✅ | string | 实际执行的命令或脚本名称，需位于系统 PATH 或写入绝对路径。 | +| `enabled` | ✅ | bool | 是否注册到 MCP；设为 `false` 时该工具会被忽略。 | +| `description` | ✅ | string | 详细描述，支持多行 Markdown，供 AI 深度理解及 `resources/read` 查询。 | +| `short_description` | 可选 | string | 20-50 字摘要，用于工具列表、减少 token 消耗；缺失时会自动截取 `description` 开头。 | +| `args` | 可选 | string[] | 固定参数，按顺序 prepend 到命令行，常用于定义默认扫描模式。 | +| `parameters` | 可选 | array | 运行时可配置参数列表，详见「参数定义」章节。 | +| `arg_mapping` | 可选 | string | 参数映射模式（`auto`/`manual`/`template`），默认 `auto`；除非有特殊需求，无需填写。 | -- `name`: 工具名称（唯一标识符） -- `command`: 要执行的命令 -- `enabled`: 是否启用（true/false） - -### 可选字段 - -- `args`: 固定参数列表（数组） -- `short_description`: 简短描述（一句话说明工具用途，用于工具列表，减少token消耗） -- `description`: 工具详细描述（支持多行文本，用于工具文档和详细说明） -- `parameters`: 参数定义列表 +> 若某字段填写错误或漏填必填项，系统会在加载时跳过该工具并在日志中输出警告，但不会影响其他工具。 ## 工具描述 diff --git a/tools/README_EN.md b/tools/README_EN.md new file mode 100644 index 00000000..53aa930e --- /dev/null +++ b/tools/README_EN.md @@ -0,0 +1,319 @@ +# Tool Configuration Guide + +## Overview + +Each tool ships with its own YAML configuration placed in the `tools/` directory. This keeps definitions modular, easier to review, and simple to extend. The runtime automatically loads every `.yaml` / `.yml` file in that directory. + +## File Structure + +The table below enumerates every supported top-level field. Double-check each entry before adding a new tool: + +| Field | Required | Type | Description | +|-------|----------|------|-------------| +| `name` | ✅ | string | Unique identifier. Prefer lowercase letters, digits, and hyphens. | +| `command` | ✅ | string | Executable or script name. Must exist in `$PATH` or be an absolute path. | +| `enabled` | ✅ | bool | Controls MCP registration. Disabled tools are ignored by the loader. | +| `description` | ✅ | string | Full Markdown description for MCP `resources/read` and AI comprehension. | +| `short_description` | Optional | string | 20–50 character summary shown in tool lists. When omitted, the loader extracts the start of `description`. | +| `args` | Optional | string[] | Static arguments prepended to every invocation—useful for default scan profiles. | +| `parameters` | Optional | array | Runtime parameter definitions. See **Parameter Definition** for details. | +| `arg_mapping` | Optional | string | Mapping strategy (`auto`/`manual`/`template`). Defaults to `auto`; override only for legacy tooling. | + +> If a required field is missing or malformed, the loader skips that tool and logs a warning without blocking the service. + +## Tool Descriptions + +### Short Description (`short_description`) + +- **Purpose**: compact summary for tool listings and to minimise language model context usage. +- **Guideline**: one concise sentence (20–50 Chinese characters or English equivalents). +- **Example**: `"Network scanner for discovering hosts, open ports, and services"` + +### Detailed Description (`description`) + +Supports multi-line Markdown. Recommended contents: + +1. **Capabilities** – what the tool does. +2. **Usage scenarios** – when to prefer this tool. +3. **Warnings** – permissions, runtime risks, side-effects. +4. **Examples** – optional walkthroughs or sample commands. + +**Important**: +- Tool menus and MCP summaries use `short_description` when available. +- Without `short_description`, the loader trims the first line or first 100 characters of `description`. +- Full descriptions are accessible through the MCP `resources/read` endpoint (`tool://`). + +## Parameter Definition + +Each parameter object accepts the fields below: + +- `name` *(required)* – parameter key used in CLI construction and MCP schema. +- `type` *(required)* – `string`, `int`/`integer`, `bool`/`boolean`, `array`, etc. +- `description` *(required)* – Markdown-friendly explanation including purpose, format rules, example values, and safety notes. +- `required` – boolean; when `true`, missing values cause the executor to return an error. +- `default` – fallback value applied if the caller omits the argument. +- `flag` – CLI switch such as `-u` or `--url`. +- `position` – zero-based index for positional arguments. +- `format` – rendering strategy: + - `flag` *(default)* → `--flag value` / `-f value` + - `combined` → `--flag=value` + - `positional` → appended according to `position` + - `template` → uses the `template` string +- `template` – placeholder string (supports `{flag}`, `{value}`, `{name}`) when `format: "template"`. +- `options` – array of allowed values; surfaced as `enum` entries in the MCP schema. + +### Format Reference + +- **`flag`**: pass the flag and the value separately. + Example: `flag: "-u"` → `-u https://example.com` + +- **`positional`**: insert according to `position`. + Example: `position: 0` → becomes the first positional argument. + +- **`combined`**: join flag and value in one token. + Example: `flag: "--level"`, `format: "combined"` → `--level=3` + +- **`template`**: custom rendering. + Example: `template: "{flag} {value}"` → fully manual control. + +### Reserved Parameters + +- `additional_args` – allows users to append arbitrary CLI fragments. The executor tokenises the string (preserving quoted groups) and appends the resulting list to the command. +- `scan_type` – for scanners like `nmap`, replacing default scan switches (e.g., `-sV -sC`). +- `action` – consumed by server-side branching logic and intentionally not forwarded to the command line. + +## Parameter Description Checklist + +When documenting a parameter, include: + +1. **Purpose** – what the value controls. +2. **Format rules** – accepted patterns (URL, CIDR, path, etc.). +3. **Example values** – list several realistic samples. +4. **Notes** – permissions, performance impact, or other caveats. + +Suggested style: Markdown lists, bold emphasis for key cautions, and code blocks for complex examples. + +### Example + +```yaml +description: | + Target IP address or domain. Accepts single IPs, ranges, CIDR blocks, or hostnames. + + **Example values** + - Single IP: "192.168.1.1" + - Range: "192.168.1.1-100" + - CIDR: "192.168.1.0/24" + - Domain: "example.com" + + **Notes** + - Required; cannot be empty. + - Validate address format before running to avoid false positives. +``` + +## Parameter Types + +### Boolean +- `true` → adds only the flag (no value). +- `false` → suppresses the flag. +- Accepts `true`/`false`, `1`/`0`, and `"true"`/`"false"`. + +```yaml +- name: "verbose" + type: "bool" + description: "Enable verbose output" + required: false + default: false + flag: "-v" + format: "flag" +``` + +### String +Most common parameter type; accepts any string value. + +### Integer +Use for numeric inputs (ports, levels, limits). + +```yaml +- name: "level" + type: "int" + description: "Level of detail, 1-5" + required: false + default: 3 + flag: "--level" + format: "combined" # --level=3 +``` + +### Array +Automatically converted to a comma-separated string. + +```yaml +- name: "ports" + type: "array" + description: "List of ports to scan" + required: false + # Input: [80, 443, 8080] + # Output: "80,443,8080" +``` + +## Special Parameters + +### `additional_args` + +```yaml +- name: "additional_args" + type: "string" + description: "Extra CLI arguments; separate multiple options with spaces" + required: false + format: "positional" +``` + +Examples: +- `additional_args: "--script vuln -O"` → `["--script", "vuln", "-O"]` +- `additional_args: "-T4 --max-retries 3"` → `["-T4", "--max-retries", "3"]` + +Notes: +- Quoted strings are preserved. +- Validate user input to avoid command injection. +- Appended at the end of the final command. + +### `scan_type` + +```yaml +- name: "scan_type" + type: "string" + description: "Overrides default scan switches" + required: false + format: "positional" +``` + +Examples: +- `scan_type: "-sV -sC"` +- `scan_type: "-A"` + +Notes: +- Replaces default entries in the tool’s `args` list. +- Separate multiple flags with spaces. + +## Complete Example (`nmap`) + +```yaml +name: "nmap" +command: "nmap" +args: ["-sT", "-sV", "-sC"] +enabled: true + +short_description: "Network scanner for discovering hosts, open ports, and services" + +description: | + Network mapping and port scanning utility. + + **Highlights** + - Host discovery + - Port scanning + - Service identification + - OS fingerprinting + - NSE-based vulnerability checks + +parameters: + - name: "target" + type: "string" + description: "Target IP or domain" + required: true + position: 0 + format: "positional" + + - name: "ports" + type: "string" + description: "Port range, e.g., 1-1000" + required: false + flag: "-p" + format: "flag" + + - name: "scan_type" + type: "string" + description: "Override scan switches, e.g., '-sV -sC'" + required: false + format: "positional" + + - name: "additional_args" + type: "string" + description: "Extra nmap arguments, e.g., '--script vuln -O'" + required: false + format: "positional" +``` + +## Adding a New Tool + +1. Create a YAML file in `tools/` (e.g., `tools/mytool.yaml`). +2. Fill out the top-level fields and parameter list. +3. Provide defaults and rich descriptions wherever possible. +4. Run `go run cmd/test-config/main.go` to validate the configuration. +5. Restart the service (or trigger a reload) so the UI and MCP registry pick up the change. + +### Template + +```yaml +name: "tool_name" +command: "command" +enabled: true + +short_description: "One-line summary" + +description: | + Detailed description with Markdown formatting. + +parameters: + - name: "target" + type: "string" + description: "Explain the expected value, format, examples, and caveats" + required: true + position: 0 + format: "positional" + + - name: "option" + type: "string" + description: "Optional flag parameter" + required: false + flag: "--option" + format: "flag" + + - name: "verbose" + type: "bool" + description: "Enable verbose mode" + required: false + default: false + flag: "-v" + format: "flag" + + - name: "additional_args" + type: "string" + description: "Extra CLI options separated by spaces" + required: false + format: "positional" +``` + +## Validation & Troubleshooting + +- ✅ Verify required fields: `name`, `command`, `enabled`, `description`. +- ✅ Ensure parameter definitions use supported types and formats. +- ✅ Watch server logs for warnings when a tool fails to load. +- ✅ Use `go run cmd/test-config/main.go` to inspect parsed tool metadata. + +## Best Practices + +1. **Parameter design** – expose common flags individually; leverage `additional_args` for advanced scenarios. +2. **Documentation** – combine `short_description` with thorough `description` to balance brevity and clarity. +3. **Defaults** – provide sensible `default` values, especially for frequently used options. +4. **Validation prompts** – describe expected formats and highlight constraints to help the AI and users avoid mistakes. +5. **Safety** – warn about privileged commands, destructive actions, or high-impact scans. + +## Disabling a Tool + +Set `enabled: false` or remove/rename the YAML file. Disabled tools disappear from the UI and MCP inventory. + +## Related Documents + +- Main project README: `../README.md` +- Tool list samples: `tools/*.yaml` +- API overview: see the main README +