MCP Tool Auditor

MCP Tool Auditor

Audit builtin MCP tool implementations in LibrAgent for compliance with the Tool Design Manifesto.

Audit Checklist

1. context_prompt vs structured_state

• context_prompt contains all information the AI needs (readable text, short IDs ok)
• structured_state is NOT relied upon for AI decision-making (AI never sees it)
• Critical IDs (full session IDs, process IDs, file paths) are in context_prompt text

2. MCPResult Text-First Design

• Critical data appears in content (text), not just structured_content
• Process IDs, file paths, status messages are copy-pasteable from text
• Error details are in text output
• structured_content is supplementary for UI rendering only

3. Canonical Naming

• Tool names follow project conventions (no alias proliferation)
• No redundant tools that could be consolidated

4. Session Isolation

• No global state in builtin server implementations
• Per-session state is scoped to session ID
• MCPServiceProxy instances are session-specific

5. Error Handling

• Errors return Result<MCPResult, String> consistently
• Error messages are actionable with next steps
• No unwrap() in production code paths

Usage

Run audits against:

• src-tauri/src/mcp/builtin/ - All builtin MCP servers
• src-tauri/src/mcp/ - MCP integration layer
• docs/guides/builtin_tool_bp.md - Design standard reference

Anti-Patterns to Flag

// ❌ WRONG: Critical ID only in structured_content
let result = MCPResult {
    content: vec![text("Background process started")],
    structured_content: Some(json!({
        "process_id": "7573a69b",  // AI can't see this!
    })),
    is_error: Some(false),
};

// ✅ CORRECT: ID visible in text output
let result = MCPResult {
    content: vec![text("Background process started (ID: 7573a69b)\nUse pollProcess(\"7573a69b\") to check status")],
    structured_content: Some(json!({
        "process_id": "7573a69b",  // Redundant but useful for UI
    })),
    is_error: Some(false),
};