This MCP server exhibits significant definition quality issues. While all 5 tools are explicitly registered and have basic descriptions in Chinese, the quality falls short of production standards. Tool names lack clear English verb prefixes (e.g., 'pingcode_get_datetime' vs industry standard 'get_datetime'). Descriptions are present but written in Chinese, limiting accessibility and clarity for English-speaking LLM agents. Input schemas exist for all tools but lack proper constraint declarations (no enums, format specifications, or clear validation rules). Parameter descriptions are minimal and often missing context about valid ranges, formats, or dependencies. Output schemas are not documented anywhere in the codebase. Error handling appears to be implicit (via HTTP status codes from the Pingcode API) with no evidence of recovery guidance in tool responses.
All descriptions are in Chinese, not English. LLM agents trained on English will struggle to understand when/why to select these tools. This violates the fundamental assumption that tool descriptions are prompt-engineered for LLM consumption.
Tool names do not follow standard verb_noun convention. Names like 'pingcode_get_datetime' are verbose; industry standard is 'get_datetime'. The 'pingcode_' prefix adds noise without clarity. Each tool's action verb is buried behind namespace prefixing.
No output schemas are documented. Tools return data from the Pingcode API (as seen in src/clients/pingcode.ts), but the response structure is never defined in the MCP tool registration. LLMs cannot predict what fields to expect or plan downstream tool calls.
Recommendations
Translate all tool descriptions and parameter descriptions to English. Use clear, LLM-optimized prose: 'Call this tool to retrieve the current date and time in the user's timezone. Returns ISO 8601 timestamp and Unix seconds for downstream calculations.'
Simplify tool names to remove the 'pingcode_' prefix. Rename: 'get_datetime', 'get_myself', 'get_projects', 'get_workitems', 'get_workitem_types'. The 'get_' verb is sufficient to disambiguate from other MCP servers.
Document complete output schemas for each tool. For example, pingcode_get_projects should return: { projects: [ { id: string, identifier: string, name: string, type: 'scrum'|'kanban'|'waterfall'|'hybrid' }, ... ], total: number }. Include this in the tool registration via an 'outputSchema' field or explicit description.
Convert all constrained string parameters to JSON Schema enums. For pingcode_get_projects, change 'type' to include 'enum': ['scrum', 'kanban', 'waterfall', 'hybrid'] instead of describing them in prose.
Add explicit min/max constraints to numeric parameters. For page_index: 'minimum': 0, 'maximum': 2. For page_size: 'minimum': 1, 'maximum': 100. Include defaults in the schema, not just description text.
Rewrite time-range parameter descriptions with concrete examples. For start_between and end_between: 'Format: comma-separated Unix seconds (UTC). Examples: "1580000000" (after Jan 26 2020), "1580000000,1590000000" (between Jan 26 and May 26 2020), ",1590000000" (before May 26 2020).'
Add error handling and recovery guidance to all tools. Wrap API calls to catch axios errors and return: { error: 'Invalid project identifier. Did you mean: PROJ, PROJECT, PROJ-DEV? Call search_projects() to list all.' }. Pattern: recovery-guide.
Parameter descriptions lack constraint documentation. Example: 'page_index' in pingcode_get_workitems says 'from 0 to max 2 pages, default 0' but this is in the description string, not as min/max constraints in the schema. Parameters lack enum declarations for constrained values like 'type' in pingcode_get_projects (accepts scrum|kanban|waterfall|hybrid), these should be JSON Schema enums, not prose.
pingcode_get_workitems has complex time-range parameters (start_between, end_between) with poorly documented semantics. The description says '通过','分割起始时间' (split start/end time with comma) but does not explain the format clearly for an English LLM. Example: '1580000000,1590000000', are these Unix seconds? Milliseconds? The format is ambiguous.
No error handling guidance is visible. The PingCodeClient in src/clients/pingcode.ts throws raw axios errors. When an API call fails (e.g., invalid project_id, authentication error), the tool does not return recovery guidance to the LLM. This violates the recovery-guide pattern.
Secrets are hardcoded in the client. In src/clients/pingcode.ts, line: 'const token = process.env.PINGCODE_ACCESS_TOKEN || 'f9ae8892-f76a-48de-a07b-424180636c5f';', a default token is embedded in the code. This is a credential leak. Environment variables should be mandatory with no fallback.
Parameter names do not consistently map to valid input types. Example: 'identifier' is used in both pingcode_get_projects and pingcode_get_workitems but accepts different formats (project identifier vs work item identifier). There is no type suffix (project_identifier vs workitem_identifier) to disambiguate.
Descriptions for pingcode_get_datetime and pingcode_get_myself are extremely minimal (35 chars each). They barely exceed the 'describe what the tool does' bar. No mention of when to call them, what they return, or how they fit into the larger workflow.
pingcode_get_datetimepingcode_get_myself
Remove hardcoded token from src/clients/pingcode.ts. Change: const token = process.env.PINGCODE_ACCESS_TOKEN; if (!token) throw new Error('PINGCODE_ACCESS_TOKEN env var is required and missing.');
Disambiguate 'identifier' parameters by renaming: 'project_identifier' vs 'workitem_identifier'. Or add type suffixes to descriptions: 'identifier: The project identifier (e.g., PROJ), not the project ID.'
Expand tool descriptions to 80-150 characters each. Include: (1) what the tool does, (2) when to call it, (3) what it returns, (4) any prerequisites. Example for get_myself: 'Fetch the current user's profile, including userId, name, email, and team membership. Call this first to identify the user, then use userId in other tool calls like get_projects() or assign_workitem().'
Implement idempotency hints for all read-only tools (already marked as READ_ONLY risk). Add 'idempotentHint: true' to tool annotations so agents know they can safely retry without side effects.
Validate input parameters before making API calls. If project_ids is a comma-separated string with >20 items, return a clear error: 'Too many project IDs (21 provided). Maximum is 20. Please split into separate calls or filter your list.'
Document pagination behavior. For workitems, describe: 'Results are paginated. Use page_index (0-2 max) and page_size (1-100) to control the window. The response includes a total_count so you can estimate how many pages exist. If you need all items, iterate page_index from 0 until you reach the last page.'