MCP Script Rules

When working with files in scripts/:

DO

• Use CLI arguments for all parameters (argparse)
• Include USAGE docstring at top of file
• Use call_mcp_tool("server__tool", params) pattern
• Handle errors gracefully with informative messages
• Print results to stdout for Claude to process

DON'T

• Hardcode parameters in the script
• Edit scripts to change parameters (use CLI args instead)
• Import from servers/ directly (use runtime.mcp_client)

Tool Naming

Tool IDs use double underscore: serverName__toolName

Examples:

• morph__warpgrep_codebase_search
• ast-grep__ast_grep
• perplexity__perplexity_ask

Testing

Test with: uv run python -m runtime.harness scripts/<script>.py --help