Droid Mode

Access MCP tools without loading them into context. Progressive discovery → schema hydration → procedural execution.

When to Use

• MCP servers with many tools (avoid context bloat)
• Token efficiency (don't dump schemas into prompts)
• Procedural workflows (filter/join/iterate between tool calls)
• Auditability (explicit scripts + saved artifacts)

Requirements

Requirement	Details
Node.js	>= 18.0.0
Permissions	bin/dm must be executable (chmod +x)
MCP Config	Valid mcp.json with at least one server

Commands

IMPORTANT: The dm script must be called with full path. Try workspace first:

1. Workspace (try first): ./.factory/skills/droid-mode/bin/dm
2. Personal (fallback): ~/.factory/skills/droid-mode/bin/dm

If workspace path fails with "not found", use personal path.

Level	Command	Purpose
1	dm servers	Discover available MCP servers
2	dm index --server X	List tools (name, description, required params)
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:

• disabled: true = "don't inject tools into Droid's context"
• droid-mode connects directly, bypassing context injection
• Result: token-efficient, on-demand MCP access

This is the entire point of the skill.

Idempotency

All droid-mode commands are safe to rerun:

• dm servers / dm index: read-only discovery
• dm hydrate: overwrites previous hydration (timestamped)
• dm run: each run creates a new timestamped trace

No cleanup required between invocations.

Tool Execution

Primary: Direct Call (dm call)

For single tool calls (most common use case):

# Hydrate once (caches schema)
dm hydrate list_collections --server context-repo

# Call directly - no workflow file needed
dm call list_collections --server context-repo
dm call list_collections --server context-repo --args '{"limit": 5}'

Results returned directly as JSON. This is the preferred method for interactive use.

Advanced: Workflows (dm run)

For multi-tool orchestration with loops, conditionals, or pre-programmed patterns:

dm run --server context-repo --tools a,b,c --workflow script.js

Input	Flag	Required	Example
Workflow file	--workflow	Yes	workflow.js
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:

Context	Format	Example
CLI --tools flag	snake_case	--tools list_collections
Workflow t. accessor	camelCase	t.listCollections({})

Conversion rule: Remove underscores, capitalize each word after first.

• list_collections → listCollections
• search_documents → searchDocuments
• get_file_content → getFileContent

Workflow Example

// workflow.js
// Note: Tool name converts from snake_case to camelCase
// search_documents → t.searchDocuments()
workflow = async () => {
  const docs = await t.searchDocuments({ query: "PRD", limit: 5 })
  return docs.results.map(d => d.id)
}

# Workspace skill
./.factory/skills/droid-mode/bin/dm run --server contextrepo --tools search_documents --workflow workflow.js

# Personal skill
~/.factory/skills/droid-mode/bin/dm run --server contextrepo --tools search_documents --workflow workflow.js

Verification

After using droid-mode, verify (using full path to dm for your installation):

# Workspace skill
./.factory/skills/droid-mode/bin/dm doctor --server X

# Personal skill
~/.factory/skills/droid-mode/bin/dm doctor --server X

• dm doctor --server X passes (connection works)
• Artifacts exist in .factory/droid-mode/ (cache, hydrated, runs)
• Workflow trace shows no errors (runs/<server>/<ts>/run.json)

Proof Artifacts

After completing a workflow, produce evidence:

• Discovery proof: Screenshot or paste of dm index --server X output
• Hydration proof: Confirm types.d.ts exists and compiles (tsc --noEmit)
• Execution proof: Link to run.json trace showing error: false
• For PRs: Include trace file or summary in PR description

Success Criteria

The skill completes successfully when these artifacts exist:

Artifact	Path	Content
Tool cache	.factory/droid-mode/cache/<server>/tools.json	Array of tool objects
Hydrated schemas	.factory/droid-mode/hydrated/<server>/<ts>/schemas.json	Full JSON schemas
TypeScript types	.factory/droid-mode/hydrated/<server>/<ts>/types.d.ts	Generated type definitions
Execution trace	.factory/droid-mode/runs/<server>/<ts>/run.json	{ error: false, result: ... }

Verify with the appropriate full path for your installation:

• Workspace: ./.factory/skills/droid-mode/bin/dm doctor --server X
• Personal: ~/.factory/skills/droid-mode/bin/dm doctor --server X

Command should exit 0.

Fallbacks

Issue	Resolution
Node.js version error	Upgrade to Node.js >= 18.0.0
Permission denied on dm	Run chmod +x bin/dm in skill directory
Server not found	Run dm servers to list available servers
Connection timeout	Check mcp.json config, run dm doctor
Tool not found	Run dm index --server X to refresh cache
Workflow sandbox error	Check for disallowed require/import/fetch

Never Do

• Don't hardcode credentials in workflows (use mcp.json env)
• Don't skip --server flag when multiple servers exist
• Don't use fetch/require/import in workflow files (sandbox blocks them)

Artifacts

All outputs written to .factory/droid-mode/:

• cache/<server>/tools.json: tool inventory
• hydrated/<server>/<ts>/: schemas + types
• runs/<server>/<ts>/run.json: execution trace

All JSON artifacts are machine-parseable for downstream skill chaining. Workflows can read tools.json or run.json to inform subsequent steps.

Supporting Files

• bin/dm: CLI entry point
• lib/: implementation modules
• examples/workflows/: sample workflow files
• examples/hooks/: PreToolUse hook examples
• README.md: full documentation

Quick Reference

Find dm: Always at ./.factory/skills/droid-mode/bin/dm (workspace) or ~/.factory/skills/droid-mode/bin/dm (personal)

Minimal workflow (using workspace path):

# 1. Discover tools (snake_case names)
./.factory/skills/droid-mode/bin/dm index --server X

# 2. Hydrate (use snake_case)
./.factory/skills/droid-mode/bin/dm hydrate tool_name --server X

# 3. Execute (use camelCase in workflow)
echo 'workflow = async () => await t.toolName({})' > /tmp/wf.js
./.factory/skills/droid-mode/bin/dm run --server X --tools tool_name --workflow /tmp/wf.js

For personal skill, replace ./.factory/ with ~/.factory/.

Common mistake: Using t.tool_name() instead of t.toolName() in workflows.

References

For project-specific conventions, see:

• AGENTS.md: project-wide agent guidance (if present)
• mcp.json: MCP server configuration
• .factory/skills/*/SKILL.md: related skills that may chain with droid-mode

For droid-mode internals:

• README.md: full CLI documentation
• examples/: sample workflows and hooks