droid-mode 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 GitMaxd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# Droid Mode
+
+Progressive Code-Mode MCP integration for Factory.ai Droid.
+
+Access MCP tools **without** loading them into your context window.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## The Problem
+
+When you configure MCP servers in Factory.ai Droid, all their tools get injected into the model's context window. This causes:
+
+- **Token bloat** - Large tool inventories eat your context
+- **Cognitive overload** - Too many tools confuse the model
+- **No selectivity** - Can't use just the tools you need
+
+## The Solution
+
+Droid Mode lets you:
+
+1. Keep MCP servers `disabled: true` in `mcp.json` (they won't bloat context)
+2. Access them **on-demand** through progressive discovery
+3. Run procedural workflows that call MCP tools **outside** the LLM loop
+
+## Installation
+
+```bash
+npx droid-mode init
+```
+
+This scaffolds the skill into `.factory/skills/droid-mode/`
+
+## Quick Start
+
+```bash
+# 1. Discover available MCP servers
+dm servers
+
+# 2. List tools on a server
+dm index --server context-repo
+
+# 3. Search for relevant tools
+dm search "collections" --server context-repo
+
+# 4. Call a tool directly
+dm call list_collections --server context-repo
+
+# 5. Run a workflow
+dm run --server context-repo \
+  --tools list_collections,get_document \
+  --workflow my-workflow.js
+```
+
+## Progressive Disclosure Model
+
+| Level | Command | Purpose |
+|-------|---------|---------|
+| 1 | `dm servers` | Discover available MCP servers |
+| 2 | `dm index --server X` | List tools on a server |
+| 3 | `dm search "..." --server X` | Find relevant tools |
+| 4 | `dm hydrate tool1 --server X` | Get full schemas |
+| 5 | `dm run --server X ...` | Execute workflow |
+
+## Working with "Disabled" Servers
+
+The key insight: `disabled: true` in `mcp.json` tells Droid "don't load these tools into context" - but Droid Mode can still access them directly!
+
+```json
+// ~/.factory/mcp.json - Recommended setup
+{
+  "mcpServers": {
+    "context-repo": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "context-repo-mcp"],
+      "disabled": true  // ← Good! Keeps context clean
+    }
+  }
+}
+```
+
+## Workflow Example
+
+Create a workflow file:
+
+```javascript
+// my-workflow.js
+workflow = async () => {
+  const collections = await t.listCollections({})
+  log("Found", collections.length, "collections")
+  
+  const docs = await t.listDocuments({})
+  return { collections, docs }
+}
+```
+
+Run it:
+
+```bash
+dm run --server context-repo \
+  --tools list_collections,list_documents \
+  --workflow my-workflow.js
+```
+
+## Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `dm servers` | List all available MCP servers |
+| `dm index --server <name>` | List tools with required parameters |
+| `dm search "<query>" --server <name>` | Search tools by keyword |
+| `dm hydrate <tools...> --server <name>` | Get full schemas |
+| `dm call <tool> --server <name>` | Call a tool directly |
+| `dm run --workflow <file> --tools <a,b> --server <name>` | Execute workflow |
+| `dm doctor --server <name>` | Diagnose connection |
+
+## Design Philosophy
+
+> **Treat MCP as infrastructure, Skills as capability boundaries, and code as a reasoning amplifier — not as an authority.**
+
+Inspired by [Cloudflare's Code Mode](https://blog.cloudflare.com/code-mode/) concept, adapted for Factory.ai's Skill architecture.
+
+## Requirements
+
+- Node.js >= 18
+- Factory.ai Droid CLI
+- MCP servers configured in `~/.factory/mcp.json`
+
+## License
+
+MIT
+
+## Author
+
+[GitMaxd](https://github.com/Gitmaxd) · [@gitmaxd](https://x.com/gitmaxd)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { defineCommand, runMain } from "citty";
+import { copy, pathExists, ensureDir } from "fs-extra";
+import { resolve, join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { stat } from "fs/promises";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var init = defineCommand({
+  meta: {
+    name: "init",
+    description: "Initialize Droid Mode skill in your project"
+  },
+  args: {
+    force: {
+      type: "boolean",
+      description: "Skip existing file checks (still never overwrites)",
+      default: false
+    },
+    path: {
+      type: "string",
+      description: "Target directory (defaults to current directory)",
+      default: "."
+    }
+  },
+  async run({ args }) {
+    const targetDir = resolve(args.path);
+    const skillDir = join(targetDir, ".factory", "skills", "droid-mode");
+    const templatesDir = resolve(__dirname, "..", "templates", "skills", "droid-mode");
+    console.log("\n\u{1F916} Droid Mode Initializer\n");
+    if (!await pathExists(templatesDir)) {
+      console.error("\u274C Templates directory not found. Package may be corrupted.");
+      process.exit(1);
+    }
+    if (await pathExists(skillDir)) {
+      console.log("\u26A0\uFE0F  .factory/skills/droid-mode already exists");
+      console.log("   Scaffolding new files only (existing files will NOT be overwritten)\n");
+    }
+    await ensureDir(skillDir);
+    let copied = 0;
+    let skipped = 0;
+    try {
+      await copy(templatesDir, skillDir, {
+        overwrite: false,
+        errorOnExist: false,
+        filter: async (src, dest) => {
+          const srcStat = await stat(src);
+          if (srcStat.isDirectory()) {
+            return true;
+          }
+          if (await pathExists(dest)) {
+            const relativePath2 = dest.replace(targetDir, ".");
+            console.log(`\u23ED\uFE0F  Skipped: ${relativePath2} (already exists)`);
+            skipped++;
+            return false;
+          }
+          const relativePath = dest.replace(targetDir, ".");
+          console.log(`\u2705 Created: ${relativePath}`);
+          copied++;
+          return true;
+        }
+      });
+    } catch (error) {
+      console.error("\u274C Error during scaffolding:", error);
+      process.exit(1);
+    }
+    console.log("\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    console.log("\u2705 Droid Mode initialized successfully!");
+    console.log(`   \u{1F4C1} Files created: ${copied}`);
+    console.log(`   \u23ED\uFE0F  Files skipped: ${skipped}`);
+    console.log("\n\u{1F4D6} Quick Start:");
+    console.log("   dm servers                    # Discover MCP servers");
+    console.log("   dm index --server <name>      # List tools");
+    console.log('   dm search "query" --server <name>');
+    console.log("   dm run --server <name> --tools <a,b> --workflow file.js");
+    console.log('\n\u{1F4A1} Tip: Keep MCP servers "disabled: true" in mcp.json');
+    console.log("   Droid Mode accesses them directly without context bloat!\n");
+  }
+});
+var main = defineCommand({
+  meta: {
+    name: "droid-mode",
+    version: "0.1.0",
+    description: "Progressive Code-Mode MCP integration for Factory.ai Droid"
+  },
+  subCommands: {
+    init
+  },
+  async run() {
+    console.log("\n\u{1F916} Droid Mode - Progressive MCP for AI Agents\n");
+    console.log("Usage:");
+    console.log("  droid-mode init [options]    Initialize Droid Mode in your project");
+    console.log("  droid-mode --help            Show help");
+    console.log("  droid-mode --version         Show version\n");
+    console.log("Quick start:");
+    console.log("  npx droid-mode init\n");
+    console.log("What is Droid Mode?");
+    console.log("  Access MCP tools without loading them into context.");
+    console.log("  Progressive discovery: servers \u2192 tools \u2192 schemas \u2192 execute\n");
+  }
+});
+runMain(main);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "droid-mode",
+  "version": "0.0.1",
+  "description": "Progressive Code-Mode MCP integration for Factory.ai Droid - access MCP tools without context bloat",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "droid-mode": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "droid-mode",
+    "factory.ai",
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "ai-agents",
+    "progressive-disclosure"
+  ],
+  "author": {
+    "name": "GitMaxd",
+    "url": "https://github.com/Gitmaxd"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gitmaxd/droid-mode.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "citty": "^0.1.6",
+    "fs-extra": "^11.3.3"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0"
+  }
+}

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

@@ -0,0 +1,237 @@
+---
+name: droid-mode
+description: Progressive Code‑Mode MCP integration for Factory Droid. Discover tools incrementally, hydrate schemas on demand, and run procedural workflows that call MCP tools outside the LLM loop.
+---
+
+# Droid Mode (Progressive Code‑Mode MCP Skill)
+
+This skill implements the **PRD “Droid Mode”** pattern: treat MCP as backend infrastructure and use **local scripts** to perform **progressive tool discovery + schema hydration + procedural orchestration**.
+
+Instead of injecting a full MCP tool inventory into the model context, Droid uses these scripts to:
+
+1. **Index** tools (compact list)
+2. **Search** tools (narrow candidates)
+3. **Hydrate** schemas (only for selected tools)
+4. **Run** a procedural workflow that calls MCP tools **outside** the LLM loop
+
+Everything is **auditable**: caches, hydrated schemas, and workflow traces are written to `.factory/droid-mode/` (project) or `~/.factory/droid-mode/` (fallback).
+
+---
+
+## When to use this skill
+
+Use this skill when you want any of the following:
+
+- MCP servers with **many tools**, or rapidly changing inventories
+- **Token efficiency** (avoid dumping schemas into prompt context)
+- **Procedural** workflows (filter/join/iterate locally between tool calls)
+- **Auditability** (explicit scripts + saved artifacts)
+
+---
+
+## Installation
+
+### Option A — Project skill (recommended for teams)
+
+Copy this directory to:
+
+- `<repo>/.factory/skills/droid-mode/`
+
+Then call it from the repo root:
+
+```bash
+./.factory/skills/droid-mode/bin/dm --help
+```
+
+### Option B — User skill (personal)
+
+Copy to:
+
+- `~/.factory/skills/droid-mode/`
+
+Then call it via absolute path:
+
+```bash
+~/.factory/skills/droid-mode/bin/dm --help
+```
+
+---
+
+## MCP server configuration
+
+This skill can connect to an MCP server in two ways:
+
+1. **Auto-detect from Droid’s `mcp.json`** (preferred)
+   - Project: `.factory/mcp.json`
+   - User: `~/.factory/mcp.json` (overrides project server entries)
+
+2. **Explicit CLI flags** (useful in CI or quick experiments)
+
+   Supported overrides:
+   - `--http-url <url>` with optional `--headers-json '{"Authorization":"Bearer ..."}'`
+   - `--stdio-command <cmd>` with optional `--stdio-args "a,b,c"` and `--env-json '{"KEY":"VALUE"}'`
+
+### Recommended: configure ContextRepo as a stdio MCP server
+
+If you use ContextRepo, the common approach is to run its MCP server locally (stdio) and let it talk to ContextRepo’s API using an API key.
+
+Example (user-level config is preferred for secrets):
+
+```bash
+droid mcp add contextrepo "npx -y context-repo-mcp" --env CONTEXTREPO_API_KEY=YOUR_KEY
+```
+
+Notes:
+- This skill intentionally **does not print** env values.
+- It will also recognize `CONTEXT_REPO_API_KEY` and `CONTEXTREPO_TOKEN` if present.
+
+---
+
+## Progressive Disclosure Model
+
+Droid-mode implements a four-level progressive disclosure model:
+
+| Level | Command | Purpose |
+|-------|---------|---------|
+| 1 | `dm servers` | Discover available MCP servers |
+| 2 | `dm index --server X` | List tools on a server |
+| 3 | `dm hydrate tool1 tool2 --server X` | Get full schemas |
+| 4 | `dm run --server X ...` | Execute workflow |
+
+### Working with "Disabled" Servers
+
+Servers marked `disabled: true` in `mcp.json` are **fully available** to droid-mode. In fact, this is the recommended configuration:
+
+- `disabled: true` tells Droid: "Don't load this server's tools into context"
+- droid-mode connects directly, bypassing context injection
+- Result: Token-efficient, on-demand MCP access
+
+```json
+// ~/.factory/mcp.json - Recommended setup
+{
+  "mcpServers": {
+    "context-repo": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "context-repo-mcp"],
+      "disabled": true
+    }
+  }
+}
+```
+
+This is the **entire point** of droid-mode: access MCP servers without bloating the context window.
+
+---
+
+## Commands
+
+> All commands accept `--server <name>` to pick an MCP server from `mcp.json`.
+> If only one server is configured, it's auto-selected. Otherwise, use `dm servers` to discover available servers.
+
+### 0) List servers (discover available MCP servers)
+
+```bash
+./.factory/skills/droid-mode/bin/dm servers
+```
+
+Lists all MCP servers configured in `mcp.json` (both project and user level).
+Servers with `disabled: true` are shown as "disabled (good!)" since they won't bloat Droid's context.
+
+### 1) Doctor (sanity check)
+
+```bash
+./.factory/skills/droid-mode/bin/dm doctor --server contextrepo
+```
+
+Checks:
+- Finds `mcp.json`
+- Resolves the server entry (user overrides project)
+- Attempts `initialize` + `tools/list` (unless `--no-connect`)
+
+### 2) Index tools (compact list)
+
+```bash
+./.factory/skills/droid-mode/bin/dm index --server contextrepo
+```
+
+Outputs a compact table (name + short description).  
+Use `--json` to return structured output.
+
+### 3) Search tools (narrow candidate set)
+
+```bash
+./.factory/skills/droid-mode/bin/dm search "semantic search over docs" --limit 8 --server contextrepo
+```
+
+This searches the cached index, refreshing if missing or stale.
+
+### 4) Hydrate tool schemas (small subset)
+
+```bash
+./.factory/skills/droid-mode/bin/dm hydrate search_documents get_document --server contextrepo
+```
+
+Writes an “hydration bundle” to:
+
+- `.factory/droid-mode/hydrated/<server>/<timestamp>/`
+
+Contents:
+- `tools.json` (full tool definitions for the subset)
+- `types.d.ts` (best-effort TS types for inputs/outputs)
+- `toolmap.json` (safe JS identifiers → tool names)
+
+### 5) Run a procedural workflow (“code-mode”)
+
+Create a workflow file that defines `workflow = async () => { ... }`.
+
+Example:
+
+```js
+// workflow.js
+workflow = async () => {
+  const docs = await t.searchDocuments({ query: "Droid Mode PRD", limit: 5 })
+  const full = await Promise.all(docs.results.map(d => t.getDocument({ id: d.id })))
+  return { count: full.length, ids: full.map(x => x.id) }
+}
+```
+
+Run it:
+
+```bash
+./.factory/skills/droid-mode/bin/dm run --server contextrepo --tools search_documents,get_document --workflow workflow.js
+```
+
+The runner:
+- Hydrates only the requested tools
+- Executes your workflow in a restricted JS sandbox (no imports/require/fetch)
+- Emits a JSON result + an execution trace
+
+---
+
+## Output & audit artifacts
+
+Artifacts are written under `.factory/droid-mode/` (project) when possible:
+
+- `cache/<server>/tools.json` — cached tool inventory
+- `hydrated/<server>/<timestamp>/...` — schema bundles
+- `runs/<server>/<timestamp>/run.json` — workflow result + trace
+
+---
+
+## Security posture (practical guardrails)
+
+This skill is designed so that:
+
+- Credentials remain in `mcp.json` env/headers (or your OS keyring), not in prompts.
+- The workflow sandbox does **not** expose `require`, `import`, `process`, or `fetch`.
+- Network access for workflows is mediated through the MCP server only.
+- Every tool call is traced (tool name, args hash, duration, and error flag).
+
+Optional: You can add a **PreToolUse hook** to block direct `mcp__*` tool calls and force use of this skill. See `examples/hooks/`.
+
+---
+
+## Design philosophy (north star)
+
+Treat MCP as infrastructure. Treat Skills as capability boundaries. Treat code as a reasoning amplifier — not as authority.