droid-mode 0.1.2 → 0.1.4

package/README.md

@@ -131,8 +131,8 @@ npx droid-mode init
 
 QUICK START
 1. Discover MCP servers        dm servers
-2. Index tools from server     dm index --server <name>
-3. Run a workflow              dm run --server <name> --tools a,b --workflow file.js
+2. Hydrate a tool              dm hydrate <tool> --server <name>
+3. Call the tool               dm call <tool> --server <name>
 ```
 
 ```bash
@@ -181,9 +181,9 @@ dm daemon stop     # Stop daemon
 | 1 | `dm servers` | List of configured MCP servers | ~10 |
 | 2 | `dm index --server X` | Tool names, descriptions, required params | ~50 |
 | 3 | `dm search "query" --server X` | Filtered tools matching keyword | ~20 |
-| 4 | `dm hydrate tool1 tool2 --server X` | Full JSON schemas + TypeScript types | on-demand |
-| 5 | `dm call tool --server X` | Execute tool, get result | 0 |
-| 6 | `dm run --workflow file.js --server X` | Procedural multi-tool workflow | 0 |
+| 4 | `dm hydrate tool --server X` | Full JSON schema + TypeScript types | on-demand |
+| **5** | **`dm call tool --server X`** | **Execute tool directly (primary)** | **0** |
+| 6 | `dm run --workflow file.js --server X` | Multi-tool workflow (advanced) | 0 |
 
 ---
 
@@ -202,8 +202,8 @@ dm daemon stop     # Stop daemon
 
 | Command | Description |
 |---------|-------------|
-| `dm call <tool> --server <name>` | Call a single tool |
-| `dm run --workflow <file> --tools <a,b> --server <name>` | Execute procedural workflow |
+| `dm call <tool> --server <name>` | **Primary**: Call a single tool (interactive use) |
+| `dm run --workflow <file> --tools <a,b> --server <name>` | Advanced: Multi-tool workflow automation |
 
 ### Daemon
 
@@ -224,7 +224,26 @@ dm daemon stop     # Stop daemon
 
 ---
 
-## Workflows
+## Direct Tool Calls (Primary)
+
+For most use cases, use `dm call` to execute tools directly:
+
+```bash
+# Hydrate once (caches schema)
+dm hydrate list_collections --server context-repo
+
+# Call directly - results returned as JSON
+dm call list_collections --server context-repo
+dm call list_collections --server context-repo --args '{"limit": 5}'
+```
+
+No workflow file needed. This is the **preferred method** for interactive use and single-tool operations.
+
+---
+
+## Workflows (Advanced)
+
+> **Note**: Workflows are for **multi-tool orchestration** with loops, conditionals, or pre-programmed patterns. For simple single-tool calls, use `dm call` instead.
 
 Workflows let you run procedural logic across multiple MCP tools in a sandboxed environment.
 
@@ -342,33 +361,39 @@ For best results with AI agents, add this snippet to your project's `AGENTS.md`
 ```markdown
 ## Droid Mode (MCP Tool Access)
 
-Access MCP tools without context bloat. Load schemas on-demand, execute via code.
+Access MCP tools without context bloat. Hydrate schemas on-demand, call tools directly.
 
 ### Commands
 
-- Discover servers: `./.factory/skills/droid-mode/bin/dm servers`
-- List tools: `./.factory/skills/droid-mode/bin/dm index --server <name>`
-- Hydrate schema: `./.factory/skills/droid-mode/bin/dm hydrate <tool> --server <name>`
-- Execute workflow: `./.factory/skills/droid-mode/bin/dm run --server <name> --tools a,b --workflow file.js`
+```bash
+# 1. Discover
+dm servers
+dm index --server <name>
+
+# 2. Prepare (one-time per tool)
+dm hydrate <tool> --server <name>
 
-### Critical Conventions
+# 3. Execute (primary - direct call)
+dm call <tool> --server <name>
+dm call <tool> --server <name> --args '{"key": "value"}'
 
-- **CLI flags use snake_case**: `--tools list_collections`
-- **Workflow `t.` accessors use camelCase**: `t.listCollections({})`
-- **Path resolution**: Try workspace path first (`./.factory/`), then personal (`~/.factory/`)
+# 4. Advanced: Multi-tool workflows (for complex automation only)
+dm run --server <name> --tools a,b --workflow file.js
+```
 
-### Sandbox Restrictions
+**Use `dm call` for everyday tool calls. Use `dm run` only for multi-tool orchestration.**
 
-Workflows run in a sandboxed VM. **Blocked**: `require()`, `import()`, `fetch`, `process`, `node:fs`, `node:http`
+### Path Resolution
 
-**Allowed**: `t.*` (tool calls), `log()`, `sleep()`, `assert()`
+Try workspace first: `./.factory/skills/droid-mode/bin/dm`
+Fallback to personal: `~/.factory/skills/droid-mode/bin/dm`
 
 ### Gotchas
 
-- **Keep commands minimal**: Don't add timing, progress bars, or diagnostics unless requested
-- **macOS compatibility**: Avoid GNU-specific flags (`date +%s%3N`, `sed -i`, `grep -P`)
-- **Surgical execution**: Execute exactly what's needed, nothing more
-- **Disabled servers work**: `"disabled": true` prevents context bloat but servers remain accessible via dm
+- **Use `dm call` for single tools** - Don't create workflow files for simple calls
+- **Keep commands minimal** - No timing, progress bars, or diagnostics unless requested
+- **macOS compatibility** - Avoid GNU-specific flags (`date +%s%3N`, `sed -i`, `grep -P`)
+- **Disabled servers work** - `"disabled": true` prevents context bloat but servers remain accessible
 ```
 
 </details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-mode",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Progressive Code-Mode MCP integration for Factory.ai Droid - access MCP tools without context bloat",
   "type": "module",
   "main": "dist/cli.js",

package/templates/skills/droid-mode/SKILL.md

@@ -35,11 +35,14 @@ If workspace path fails with "not found", use personal path.
 |-------|---------|---------|
 | 1 | `dm servers` | Discover available MCP servers |
 | 2 | `dm index --server X` | List tools (name, description, required params) |
-| 3 | `dm hydrate tool1 tool2 --server X` | Get full schemas + TypeScript types |
-| 4 | `dm run --workflow file.js --tools a,b --server X` | Execute procedural workflow |
+| 3 | `dm hydrate tool --server X` | Get full schema + TypeScript types |
+| **4** | **`dm call tool --server X`** | **Execute tool directly (primary)** |
+| 5 | `dm run --workflow file.js --server X` | Multi-tool workflow (advanced) |
 
 All commands accept `--server <name>`. If only one server exists, it's auto-selected.
 
+**Use `dm call` for single tool calls. Use `dm run` only for multi-tool workflows.**
+
 ## Key Insight
 
 Servers with `disabled: true` in `mcp.json` are **fully available** to droid-mode:
@@ -59,22 +62,30 @@ All droid-mode commands are safe to rerun:
 
 No cleanup required between invocations.
 
-## Tool Execution Options
+## Tool Execution
+
+**Primary: Direct Call (`dm call`)**
 
-**Option 1: Direct MCP Call (Single Tool)**
+For single tool calls (most common use case):
 
 ```bash
-# 1. Hydrate the tool schema
-dm hydrate search_documents --server contextrepo
+# Hydrate once (caches schema)
+dm hydrate list_collections --server context-repo
 
-# 2. Call via MCP server directly (tool now available in context)
+# Call directly - no workflow file needed
+dm call list_collections --server context-repo
+dm call list_collections --server context-repo --args '{"limit": 5}'
 ```
 
-No workflow file needed for single tool calls.
+Results returned directly as JSON. This is the **preferred method** for interactive use.
+
+**Advanced: Workflows (`dm run`)**
 
-**Option 2: Procedural Workflow (Multiple Tools)**
+For multi-tool orchestration with loops, conditionals, or pre-programmed patterns:
 
-For loops, conditionals, or chaining multiple calls, use `dm run`:
+```bash
+dm run --server context-repo --tools a,b,c --workflow script.js
+```
 
 | Input | Flag | Required | Example |
 |-------|------|----------|---------|
@@ -82,6 +93,8 @@ For loops, conditionals, or chaining multiple calls, use `dm run`:
 | Tool list | `--tools` | Yes | `search,query` |
 | Server name | `--server` | If multiple servers | `contextrepo` |
 
+Use workflows for complex automation, not everyday single-tool calls.
+
 ## Naming Convention
 
 Tool names use **snake_case** in CLI flags but **camelCase** in workflow code:

package/templates/skills/droid-mode/lib/run.mjs

@@ -81,7 +81,17 @@ export function createToolApi(opts) {
           hasStructured: !!res?.structured,
           textLength: (res?.text || "").length,
         };
-        return res.structured ?? (res.text ? { text: res.text } : res.raw);
+        // Return structured data if available
+        if (res.structured) return res.structured;
+        // Auto-parse JSON text responses for better workflow UX
+        if (res.text) {
+          try {
+            return JSON.parse(res.text);
+          } catch {
+            return { text: res.text };
+          }
+        }
+        return res.raw;
       } catch (err) {
         lastError = err;
         traceItem.retries = attempt;