A Python-based utility for processing and organizing MCP server project metadata, including deduplication and categorization of projects
This MCP server exhibits significant quality gaps across naming, descriptions, schemas, and error handling. While tool names follow verb-noun convention (categorize_, deduplicate_, normalize_), they lack clarity about their distinct responsibilities and composition flow. Descriptions are present but extremely brief (34-67 chars), below the 50-200 char target for LLM optimization. Input schemas exist but are minimal, all three tools accept only string or simple scalar parameters with no validation, enum constraints, or range specifications. Output schemas are completely undocumented. No error handling guidance, no recovery paths, no permission checks, and no indication of idempotency. The server appears to be STDIO-based (file I/O in the example code), which caps protocol readiness severely. Tool composition is unclear: there is no obvious chaining between deduplicate_projects → categorize_projects, and the role of normalize_url as a separate exposed tool (rather than internal utility) is questionable.
Categorizes projects based on their category field, grouping them by category and handling missing categories as 'Unknown'. Sanitizes tags to ensure string format and returns categorized projects as JSON.
Deduplicates projects based on normalized URLs, merges categories and tags from duplicate entries, and returns a consolidated list of unique projects
Normalizes URLs by removing trailing slashes for consistent comparison and deduplication
Descriptions are critically short (15 - 67 chars) and lack actionable detail. 'Normalizes URLs by removing trailing slashes' tells the LLM WHAT but not WHEN to call it or WHY. Minimum target is 50 - 200 chars with context about dependencies and use cases.
Input schemas are minimal and lack validation constraints. All three tools accept free-form JSON strings with no examples, patterns, or format guidance. categorize_projects and deduplicate_projects expect specific JSON structures but do not document required fields, allowed category values, tag format, or URL format. LLMs cannot infer these constraints and will pass malformed JSON.
Output schemas are completely undocumented. Callers cannot know what fields categorize_projects() returns (is the output a dict with category keys? A list? A dict with metadata?). Same for deduplicate_projects(), is the return a flat list or nested structure? LLMs cannot plan downstream tool calls or extract fields without this information.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 33 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 0 | - | v1 |
No error handling or recovery guidance. The code silently calls json.loads() and file operations that can throw JSONDecodeError, FileNotFoundError, etc. No try-catch blocks in the tool functions themselves (only in the script execution). LLM has no way to know what went wrong or how to recover.
Tool composition is unclear and potentially problematic. deduplicate_projects and categorize_projects appear to operate in a fixed pipeline sequence (deduplicate → categorize), but neither tool description indicates this dependency or what data format the prior step outputs. LLM cannot infer when to call which tool or in what order.
normalize_url is exposed as a public tool but appears to be a utility function. It is not idempotent on the LLM's expected use (calling it multiple times with different inputs works, but it does not idempotently handle already-normalized URLs well). The tool should either be internal to deduplicate_projects or have explicit documentation of its role as a utility vs. primary operation.
No parameter descriptions. categorize_projects and deduplicate_projects accept 'projects_json_string' but do not describe the expected JSON structure (required fields, data types, encoding, size limits, examples). normalize_url accepts 'url' with no guidance on format (HTTP/HTTPS only? Relative URLs? IDNs?).
No input validation. deduplicate_projects converts category from string to list and back without documenting this transformation. If an LLM passes a project with a category that is already a list, or a missing category, the code handles it but the LLM is not informed what happens or whether the input is valid.
No documentation of what constitutes duplicate projects or how deduplication affects data. deduplicate_projects uses normalized URLs as the key, two projects with different cases or trailing slashes are treated as duplicates and merged. This is a significant data-modifying operation that should be explicitly warned in the tool description.