FastMCP stdio server exposing Claude Agent Skills as MCP tools
The server exposes 7 tools for skill discovery and asset management with well-structured descriptions and partial schema coverage. Tools follow a consistent verb_noun naming pattern (list_, get_, search_, read_, trash_). However, several critical gaps limit quality: (1) Output schemas are not documented anywhere in the code, LLMs cannot predict what fields are returned; (2) Input parameter descriptions exist but lack format constraints, ranges, or validation rules; (3) Destructive operations (trash_skill, trash_skill_asset) provide audit logging but lack confirmation/dry-run patterns; (4) No per-tool error handling documentation or recovery guidance; (5) Permission/authorization model is implicit, not declared. Tool descriptions average ~80 chars and are clear but brief. Parameter types are properly declared (string, object). The codebase shows thoughtful design (path traversal prevention, text/binary detection, rolling logs, git sync) but the MCP interface itself lacks the structured output and error recovery patterns expected in production tools.
Fetch a specific skill by name, including its full markdown document and any user-created notes
Enumerate all assets (files) in a skill's assets directory
List all available skills with their metadata
Read and return the content of a specific asset file from a skill's assets directory
Search across all skills by keyword, returning matching skills with their metadata
Move a skill directory to trash (soft delete) with audit logging
Move a specific asset file from a skill to trash with audit logging
Output schemas are not documented. Tools return data but LLMs cannot predict field names, types, or structure. E.g., list_skills returns skill metadata, but no schema specifies which fields are present (name, description, tags, version, etc.). This forces LLMs to guess and blocks downstream tool chaining.
Destructive operations (trash_skill, trash_skill_asset) have no confirmation or dry-run pattern. Agents can accidentally delete skills with one invocation. Best practice: either require explicit confirm_* step or implement a soft-delete with time-window recovery.
No error handling guidance in tool descriptions. Tools document what they do but not what errors can occur, whether they are retryable, or how to recover. E.g., get_skill does not document: 'Skill not found: try search_skills() with a partial name.'
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 47 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 17 | - | v1 |
Input parameter descriptions lack format constraints and validation rules. E.g., 'name' and 'skill_name' are described as 'The skill name (hyphen-case)' but do not state: minimum length, allowed characters, or what happens if the format is violated. LLMs cannot validate input and may pass invalid values.
No pagination support on list_skills and search_skills. If the skills directory grows large, these tools may return hundreds of results, bloating context. Best practice: add limit and offset/next_cursor parameters and document the default limit.
Permission model is implicit. No tool declares what permissions are required (e.g., 'read:skills', 'write:skills', 'admin:trash'). This makes least-privilege configuration and audit trails difficult.