@nanobot-ai/workflow-toolbox

MCP (Model Context Protocol) server providing code operation tools with sandboxed execution.

Quick Start

Run directly with npx (no installation required):

npx @nanobot-ai/workflow-toolbox

Or install globally:

npm install -g @nanobot-ai/workflow-toolbox
workflow-toolbox

Usage

Basic Usage

# Start server on default port (5174)
npx @nanobot-ai/workflow-toolbox

# Specify custom port
npx @nanobot-ai/workflow-toolbox --port 8080

# Specify host and port
npx @nanobot-ai/workflow-toolbox --host 0.0.0.0 --port 3000

# Custom workspace and data directories
npx @nanobot-ai/workflow-toolbox \
  --workspace-dir /path/to/workspace \
  --data-dir /path/to/data

CLI Options

• -p, --port <port> - Port to listen on (default: 5174, or PORT env var)
• -h, --host <host> - Host to bind to (default: localhost, or HOST env var)
• --workspace-dir <dir> - Workspace directory (default: current directory)
• --data-dir <dir> - Data directory for sandbox storage (default: <workspace>/.nanobot/data)
• -V, --version - Output version number
• --help - Display help

Environment Variables

• PORT - Server port (overridden by --port flag)
• HOST - Server host (overridden by --host flag)
• WORKSPACE_DIR - Working directory for file operations
• DATA_DIR - Storage location for sandbox data and process state

Available MCP Tools

This package provides an MCP server with the following tools for code operations:

File Operations

• read - Read file contents with optional encoding (utf-8/base64)
• write - Write content to files
• edit - Edit files using find/replace operations
• listdir - List directory contents
• glob - Find files by glob patterns
• grep - Search file contents with regex

Process Execution

• bash - Execute bash commands in the sandbox
• bashoutput - Get output from background processes
• killshell - Terminate background processes

Task Management

• todowrite - Create and update todo lists
• todoread - Read todo lists

Architecture

The workflow toolbox uses a LocalSandbox architecture for isolated execution:

• Direct Filesystem Access - Uses LocalDriver for fast, direct file operations
• Process Management - Persistent process state with background execution support
• No Containerization - Runs directly on the local filesystem (no Docker required)
• Data Persistence - Sandbox state stored in .nanobot/data/ directory

Directory Structure

<workspace>/
├── .nanobot/
│   └── data/
│       ├── configs/           # Sandbox configuration files
│       └── sandboxes/         # Sandbox data directories
│           └── {sandboxId}/
│               └── .processes/  # Process state and output
│                   └── {processId}/
│                       ├── meta.json
│                       ├── stdout.txt
│                       ├── stderr.txt
│                       ├── exitcode.txt
│                       └── pid.txt
└── <your project files>

MCP Integration

Connect to this server from any MCP-compatible client:

1. Start the server:

   npx @nanobot-ai/workflow-toolbox --port 5174

2. Configure your MCP client to connect to http://localhost:5174/mcp/coder

3. Available endpoints:

   • /mcp/coder - Code operation tools (read, write, bash, etc.)

Development

Local Development

# Clone the repository
git clone <repo-url>
cd workflow-toolbox

# Install dependencies
pnpm install

# Run in development mode
cd packages/services
pnpm run dev

# Build for production
pnpm run build

# Test locally
node dist/cli.js --port 5175

Building from Source

# Build all packages
pnpm -r run build

# Test the CLI
cd packages/services
node dist/cli.js --help

Examples

Using with an MCP Client

// Example: Connect from an MCP client
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({
  name: "my-app",
  version: "1.0.0"
}, {
  capabilities: {}
});

await client.connect({
  url: "http://localhost:5174/mcp/coder"
});

// Use tools
const result = await client.callTool({
  name: "read",
  arguments: {
    filePath: "/path/to/file.txt"
  }
});

Running as a Service

# Using PM2
pm2 start "npx @nanobot-ai/workflow-toolbox" --name workflow-toolbox

# Using systemd (create /etc/systemd/system/workflow-toolbox.service)
[Unit]
Description=Nanobot Workflow Toolbox
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/workspace
ExecStart=/usr/bin/npx @nanobot-ai/workflow-toolbox --port 5174
Restart=on-failure

[Install]
WantedBy=multi-user.target

Security Considerations

⚠️ Important Security Notes:

• This tool provides direct filesystem access to the workspace directory
• Commands executed via the bash tool run with the same permissions as the server process
• Do not expose this server to untrusted networks without proper authentication
• Consider running in a containerized or sandboxed environment for production use
• Always validate and sanitize inputs from untrusted sources

Troubleshooting

Port Already in Use

# Try a different port
npx @nanobot-ai/workflow-toolbox --port 5175

Permission Errors

Ensure the server process has read/write access to:

• Workspace directory (WORKSPACE_DIR)
• Data directory (DATA_DIR)

Process Output Not Available

Processes need time to complete. Use wait before calling bashoutput:

const processId = await bash({ command: "ls -la" });
await wait({ processId });
const output = await bashoutput({ shellId: processId });

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT - See LICENSE file for details

Related Packages

This package depends on:

• @nanobot-ai/sandbox - Sandbox execution environment
• @nanobot-ai/coder - Code operation tools
• @nanobot-ai/agentconfig - Agent configuration
• @nanobot-ai/nanomcp - MCP server framework

Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki