Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
This server presents 18 tools with explicit schemas and Chinese descriptions. However, critical quality gaps significantly limit production readiness: (1) All tool descriptions are in Chinese, not English, which prevents English-speaking LLMs from selecting tools appropriately. (2) Parameter descriptions lack depth, many are single-word translations ('会话 ID', '幻灯片索引') that don't explain WHEN or WHY to use the parameter. (3) Output schemas are completely undocumented, no tool shows what fields are returned or what structure the response has. (4) No error handling guidance, tools don't describe what errors are possible or how to recover. (5) Multiple tools lack critical validation constraint descriptions (e.g., pptx_add_shape uses EMU units for positioning but doesn't define the range or conversion; pptx_add_text allows 'custom' position but doesn't document what 'left', 'top' units are). (6) Session-based architecture with session_id parameters is present but no description of session lifecycle, timeout behavior, or cleanup. (7) No composition hints, tools don't guide agents on prerequisite calls (e.g., pptx_add_text requires a session be open, but this isn't stated). Per-tool analysis shows consistent patterns: good schema structure, missing description depth, no output documentation.
ALL tool descriptions and parameter descriptions are in Chinese, preventing English-speaking LLMs from understanding tool purpose and parameter semantics. MCP spec requires descriptions to be in the LLM's language.
NO tool documents its output schema. Clients cannot know what fields to expect in responses, breaking downstream tool chaining and forcing agents to guess field names.
CRITICAL: Translate all tool descriptions and parameter descriptions to English. Provide clear, specific descriptions (100-200 chars) explaining WHAT each tool does, WHEN to use it, and WHAT it returns. Example: 'pptx_create' should be 'Create a new blank PowerPoint presentation with the given name. Returns a session_id for use in subsequent tool calls. The file is created in the server's working directory.'
CRITICAL: Document the output schema for every tool. Specify all fields returned, their types, and meanings. Use a comments section in the source code or extend the MCP tool definition with an 'outputSchema' field if possible. Example: pptx_create returns {'session_id': string, 'file_path': string, 'slide_count': integer}.
Add a 'Session Management' section to the server documentation explaining: (1) How sessions are created (which tool returns session_id?), (2) Session timeout duration and cleanup policy, (3) What happens to unsaved changes when a session expires, (4) How to explicitly close a session (pptx_close).
Standardize positioning parameters across all tools: (1) Choose one unit system (recommend inches as per pptx_add_image), (2) Document min/max ranges for left, top, width, height, (3) For pptx_add_shape, clearly define EMU and provide a conversion formula (e.g., '1 inch = 914400 EMU'), (4) Update pptx_add_text and pptx_add_table descriptions to match the unit system.
Document error cases for all tools. For each tool, specify: (1) What errors can occur (e.g., 'file not found', 'invalid session_id', 'slide_index out of bounds'), (2) The HTTP status code and error response format, (3) Recovery guidance (e.g., 'If session not found, call pptx_open() to reload the file'). Follow the recovery-guide pattern.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Session lifecycle is undocumented. Parameters accept session_id but descriptions don't explain: how are sessions created (pptx_create? pptx_open?), what is the timeout policy, what happens to unsaved changes when a session expires, and how does the server clean up abandoned sessions?
Error handling is not documented. Tools don't specify what errors are possible (file not found, invalid session, permission denied, out of bounds) or how to recover. No recovery guidance per the MCP recovery-guide pattern.
pptx_add_shape uses EMU (English Metric Units) for positioning and sizing but provides no definition, conversion formula, or validation range. Agents cannot compute correct EMU values from user input.
pptx_add_text parameter 'position' enum includes 'custom' but description doesn't explain what 'custom' means or when to use it vs. 'title'/'body'. No guidance on how position enum interacts with left/top/width/height.
pptx_add_table parameter 'data' is optional and described as '表格数据（可选）' but the expected format (array of arrays? array of objects? how nested?) is not documented.
No tool provides pagination support. pptx_list_slides, pptx_list_images, and pptx_read_content may return unbounded results, risking context window exhaustion if a presentation has many slides/images.
pptx_read_contentpptx_list_slidespptx_list_images
For pptx_add_text, clarify the 'position' enum: (1) Document what 'title', 'body', and 'custom' mean (e.g., 'title' uses the slide's title placeholder, 'body' uses the content area, 'custom' uses explicit left/top/width/height), (2) State which position values ignore left/top/width/height, (3) Add an example: 'To add text at a specific location, use position="custom" and set left, top, width, height.'
For pptx_add_image, add parameter constraints: (1) Specify supported formats ('PNG, JPG, GIF, BMP'), (2) Define max file size (e.g., '10 MB'), (3) State whether image_path accepts URLs or only local file paths, (4) Document behavior if width/height are omitted (e.g., 'aspect ratio is preserved; width defaults to 3 inches').
For pptx_add_table, document the 'data' parameter format: (1) Specify the exact JSON structure (e.g., array of arrays: [['cell11', 'cell12'], ['cell21', 'cell22']]), (2) Note whether data is optional and what happens if omitted (e.g., 'if omitted, creates an empty table; use pptx_add_text to populate cells'), (3) Add validation: (e.g., 'data row length must match cols parameter').
Add pagination support to pptx_list_slides and pptx_list_images: (1) Introduce optional 'limit' (default 20) and 'offset' or 'page' parameters, (2) Return a total_count and next_page_token in the response, (3) Document in the description: 'Results are limited to 20 per call; use offset to retrieve more.'
For pptx_add_shape, document the fill_color and line_color parameters: (1) Specify the hex format ('6-digit hex RGB, e.g., FF0000 for red'), (2) State whether alpha/transparency is supported, (3) Add validation ranges or examples, (4) Document default fill/line colors if not specified.
Add tool annotations (per 2026-07-28 spec) to indicate side effects: (1) Mark destructive tools (pptx_save, pptx_close, pptx_export_images) with 'destructiveHint: true', (2) Mark read-only tools (pptx_info, pptx_read_content, pptx_list_slides, pptx_validate) with 'readOnlyHint: true', (3) Mark idempotent tools (most read operations) with 'idempotentHint: true' if applicable.
Add per-tool examples in descriptions to show common usage patterns. For example, pptx_add_text could include: 'Example: Add a title to slide 0 using position="title". To add custom text at coordinates, use position="custom" with left=1.0, top=1.0, width=8.0, height=1.0 (in inches).'
Document any file path safety validations in pptx_open and pptx_validate: (1) State what security checks are performed (ZIP bomb detection, macro scanning, path traversal prevention), (2) Specify what file extensions are allowed (.pptx only?), (3) Define allowed directories or path restrictions, (4) Document what happens if a file fails validation (e.g., 'Returns error: "File failed security validation: macro detected"').