| name | te-doctor |
| description | Use this skill when users say "tool executor not working", "diagnose tool executor", "check MCP health", "run tool executor tests", "debug search_tools", "execute_code failing", or need to troubleshoot issues with the Tool Executor. |
Tool Executor Diagnostics
Diagnose and fix issues with the Claudikins Tool Executor.
Quick Health Check
Run the test suite to verify everything works:
cd ${CLAUDE_PLUGIN_ROOT}
npm test
Expected output: 43 tests passing across 4 test files.
Diagnostic Checklist
1. Build Status
Check the build is current:
cd ${CLAUDE_PLUGIN_ROOT}
npm run build
If build fails:
- Check
tsconfig.json for TypeScript errors
- Run
npm install to ensure dependencies are installed
- Check Node.js version (requires 18+)
2. MCP Server Connectivity
Test that MCP servers can connect. In execute_code:
console.log("Available:", Object.keys({ serena, gemini, context7 }));
try {
const result = await serena.get_active_project({});
console.log("Serena OK:", result ? "connected" : "no project");
} catch (e) {
console.log("Serena error:", e.message);
}
Common connectivity issues:
- uvx not installed: Install with
pip install uvx or pipx install uvx
- npx timeout: Network issues or npm registry problems
- API key missing: Check environment variables are set
3. Registry Integrity
Verify YAML files are valid:
cd ${CLAUDE_PLUGIN_ROOT}
find registry -name "*.yaml" | wc -l
npm run extract 2>&1 | grep -i error
If registry is corrupted:
rm -rf registry/
npm run extract
4. Workspace State
Check workspace directory:
cd ${CLAUDE_PLUGIN_ROOT}
ls -la workspace/
du -sh workspace/
Clean up old MCP results:
const deleted = await workspace.cleanupMcpResults(3600000);
console.log("Cleaned up", deleted, "old result files");
5. Serena Health (Critical)
Both Serena instances must be working:
Registry Serena (powers search_tools):
search_tools({ query: "diagram", limit: 3 })
Sandbox Serena (available in execute_code):
const symbols = await serena.find_symbol({ name_path: "workspace" });
console.log("Found symbols:", symbols.content?.length || 0);
If Serena fails:
- Check uvx is installed:
which uvx
- Check Python 3.10+:
python3 --version
- Try manual start:
uvx --from git+https://github.com/oraios/serena serena start-mcp-server
Common Issues
Issue: "search_tools returns no results"
Causes:
- Registry YAML files missing or corrupted
- Serena not indexing registry directory
- Query terms don't match any tool descriptions
Fix:
npm run extract
npm run build
Issue: "execute_code times out"
Causes:
- MCP server slow to connect (first use)
- Long-running operation exceeds timeout
- Infinite loop in code
Fix:
- Increase timeout:
execute_code({ code: "...", timeout: 60000 })
- Split into smaller operations
- Check for infinite loops
Issue: "MCP client returns null"
Causes:
- Server failed to start
- Environment variable missing
- Package not found (npx/uvx issue)
Fix:
echo $GEMINI_API_KEY
echo $APIFY_TOKEN
npx -y @rlabs-inc/gemini-mcp
Issue: "Path traversal blocked"
Cause: Attempting to access files outside workspace.
Fix: All workspace paths must be relative and within ./workspace/:
await workspace.read("/etc/passwd");
await workspace.read("../package.json");
await workspace.read("data/file.txt");
Issue: "Console output truncated"
Cause: Output exceeds 500 character limit.
Fix: Keep logs concise or save verbose output to workspace:
console.log(JSON.stringify(largeData, null, 2));
await workspace.writeJSON("output.json", largeData);
console.log("Saved to output.json");
Log Locations
MCP Server Stderr:
claude --debug
Audit Log:
Test Suite Details
| Test File | Tests | Coverage |
|---|
tests/unit/workspace.test.ts | 13 | Path traversal, read/write, JSON, directories |
tests/unit/clients.test.ts | 6 | Server configs, client management |
tests/unit/search.test.ts | 10 | Tool loading, search, pagination |
tests/integration/execute-code.test.ts | 14 | Execution, workspace access, MCP proxies |
Run specific test file:
npm test -- tests/unit/workspace.test.ts
Run with verbose output:
npm test -- --verbose
Nuclear Option: Full Reset
If nothing else works:
cd ${CLAUDE_PLUGIN_ROOT}
rm -rf node_modules dist registry workspace/mcp-results
npm install
npm run extract
npm run build
Source Code Reference
${CLAUDE_PLUGIN_ROOT}/tests/ - All test files
${CLAUDE_PLUGIN_ROOT}/src/sandbox/clients.ts - Client lifecycle
${CLAUDE_PLUGIN_ROOT}/src/search.ts - Search implementation
${CLAUDE_PLUGIN_ROOT}/src/sandbox/runtime.ts - Execution engine