MCP server that lets AI agents vent friction into .vents/ markdown files in your repo
Single tool 'vent' has a well-written, detailed description (500+ chars) that clearly explains WHEN and WHY to use it, with explicit DO/DO NOT guidance. Input schema is present with proper type and description. However, the tool lacks output schema documentation, the response structure (id, path, fallback, commitStatus, etc.) is inferred from code but not formally declared. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite the tool being write-heavy. Tool naming is simple but adequate ('vent' is a verb reflecting the action). Error handling returns actionable messages but lacks recovery guidance patterns.
Submit a free-text frustration when you are repeatedly blocked or have discovered a recurring friction. The message is written to a markdown file in this repo's .vents/ directory so the human (or a triage agent) can investigate later. DO vent when: - You've tried the same fix multiple times and the underlying tool/library/API keeps misbehaving. - You've found a months-old bug, a missing capability, or a confusing error message that wasted significant time. - A documented feature appears to not work as documented. DO NOT vent for: - A single failed attempt that you could retry. - "I had to think for a moment." - Routine errors you successfully recovered from. Keep it to one vent per turn. Be specific: include the exact command, file, error message, or behaviour. Future-you (or another agent) will read this with no memory of the session.
Output schema not documented. Response structure (id, path, fallback, commitStatus, commitReason) is inferred from code but not formally declared in tool definition. LLMs cannot plan downstream operations or extract fields reliably.
Missing tool annotations. Tool performs destructive/write operations (creates files, may commit to git) but lacks destructiveHint annotation. LLMs cannot reason about side effects or idempotency.
No confirmation/dry-run pattern for irreversible operations. Tool writes to disk and optionally commits to git, but offers no way for agents to preview or confirm before execution.
Error messages lack recovery guidance. Errors like 'primary vent dir was unwritable' or 'git operation failed' are reported but do not suggest next steps (e.g., 'Check directory permissions' or 'Verify git config').
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 55 | 2026-07-28+ | v2 |
Message parameter lacks format/length constraints. Description says 'Free-text vent body' but does not specify minimum length, maximum length, or character restrictions. LLMs may pass empty or excessively long strings.