Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
21 tools total. Naming is generally verb-first and action-oriented (read_file, write_file, list_files, etc.), following the verb_noun convention well. However, descriptions are problematic: all 21 are in Chinese (not English), limiting LLM utility in English-speaking contexts. More critically, descriptions are extremely terse (6-20 characters in most cases), violating the 10-1024 character guideline and providing almost no context for LLM selection. Parameter schemas ARE present and typed (string, number, boolean, object), but many parameters lack descriptions or have minimal ones. Output schemas are not documented anywhere in the provided code, tool implementations exist but return structures are not specified in the tool registration. Error handling is basic. File operations lack security annotations (readOnlyHint/destructiveHint). Overall, the server has structure but fails on crucial LLM-facing metadata.
All 21 tool descriptions are in Chinese (e.g., '读取文件内容', '写入文件内容'), not English. This severely limits utility for English-speaking LLM agents and violates MCP conventions which expect English metadata for cross-ecosystem compatibility.
Description lengths are critically short (6-20 characters). Guideline requires 10-1024 chars; these descriptions fail to explain WHEN to use the tool, WHAT it returns, or any prerequisites. Examples: '读取文件内容' (6 chars), '检查文件是否存在' (8 chars). LLMs cannot distinguish similar tools or plan multi-step operations with such minimal context.
Recommendations
CRITICAL: Translate all 21 tool descriptions and parameter descriptions to English. Use clear, action-oriented language (50-200 chars per tool description) explaining WHAT the tool does, WHEN to use it, and any side effects. Example: 'read_file: Reads the full content of a text file. Use to retrieve file data before processing. Returns file content as a string or error if file not found or unreadable.'
CRITICAL: Document output schemas for all 21 tools. Define the exact response structure (e.g., { success: boolean, content?: string, error?: string, code?: string }) so LLMs know what fields to extract and can chain calls correctly.
HIGH: Add tool annotations to every tool. Mark delete_* tools with destructiveHint: true. Mark read-only tools (list_*, get_*, read_*, file_exists, etc.) with readOnlyHint: true. Mark idempotent operations (copy with overwrite, write) with idempotentHint: true.
HIGH: Document all parameter descriptions in English and with full context. Example: 'recursive (boolean, optional, default false): If true, recursively list subdirectories; if false, list only immediate children.'
HIGH: Add error handling guidance to tool descriptions. Example: 'Returns { success: true, data: ... } on success, or { success: false, code: "NOT_FOUND"|"PERMISSION_DENIED"|"INVALID_PATH", message: string } on failure. If code is NOT_FOUND, try search_file_content or list_files to locate the file.'
MEDIUM: Document watch_path output structure explicitly. Include that it returns a watcherId (number) which must be passed to stop_watch. Example: '{ success: true, watcherId: number, events: string[] }' to enable tool chaining.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Output schemas are not documented. Tool definitions specify inputs (parameters with types and descriptions), but NO output structure is defined. LLMs cannot plan downstream calls or extract required fields when output schemas are missing. Example: read_file returns file content, but the exact response structure (success: boolean, content: string, error: string?) is not specified.
Destructive operations (delete_file, delete_directory) lack tool annotations. MCP spec supports destructiveHint annotation; these tools should declare their destructive nature so agents and client UIs can add confirmation or warnings. Currently, no annotations are visible in the tool definitions.
Read-only operations (list_files, read_file, get_file_info, etc.) lack readOnlyHint annotations. These should be marked to help clients optimize caching and distinguish them from write operations. MCP supports this annotation; it is not used.
Parameter descriptions are in Chinese or minimal. 'path' param is described as '文件路径' (file path), but in English. Many params like 'recursive', 'overwrite', 'regex' lack context about their effects. Guideline requires descriptions for every param; compliance is inconsistent.
Error handling is not documented. No tool description mentions what errors are possible, how they are classified (retryable vs fatal), or what the LLM should do next. Looking at src/tools/dir-tools.js, errors return { success: false, message, code, error }, but this response structure is not part of the tool's output schema documentation.
watch_path tool uses a 'watcherId' return value (inferred from stop_watch param), but this is not documented in watch_path's output schema. Agents cannot know they should save the watcherId for later or that it is a number. Broken tool chains.
No idempotent hints. Tools like copy_file with 'overwrite' flag are idempotent if called twice with the same inputs, but this is not declared. Agents need to know whether retrying a failed call is safe. MCP supports idempotentHint; it is not used.
copy_filemove_filewrite_file
MEDIUM: Add a 'Get Started' guide in the server README explaining the tool categories (file ops, directory ops, office docs, watchers) and a typical workflow (e.g., 'list_files → read_file → write_file').
MEDIUM: For tools accepting 'path' parameters, add a note about path format: 'Relative paths are resolved from the server's working directory. Use absolute paths for full control. Paths are sanitized against traversal attacks.'
LOW: Consider adding pagination support to list_files and list_watchers if they can return many results. Accept optional 'limit' (default 50) and 'offset' parameters, and return { items: [...], total: number, hasMore: boolean }.