staff-mcp

English | 简体中文

A next-generation Model Context Protocol (MCP) server that transforms any AI assistant into a highly capable, container-aware, and role-adaptable digital employee.

It provides secure file management, shell execution, LSP-powered code intelligence, a 5-tier Skill & Profile ecosystem, and a revolutionary Docker Transparent Proxy Mode.

🚀 Quick Start

1. Standard Host Mode

Run directly on your physical machine or virtual environment.

npx -y staff-mcp@latest --working-dir /path/to/your/project

2. Docker Transparent Proxy Mode (Cyber-Shell)

Seamlessly spawn the AI assistant inside any Docker container while keeping the protocol connection with the host. It mounts your project and the staff-mcp binary automatically—zero overhead, instant startup!

# Debug a Node.js project inside a pure Alpine container
npx -y staff-mcp@latest --docker node:20-alpine

# Perform security analysis inside a custom reverse-engineering image
npx -y staff-mcp@latest --docker chineseastar/security:latest --profile android-reverse

3. Claude Desktop Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "staff-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "staff-mcp@latest",
        "--working-dir",
        "/path/to/your/project"
      ]
    }
  }
}

4. Reverse MCP Mode (Intranet Penetration)

Connect your local machine to a centralized remote gateway (like chat-ai) from behind NAT/Firewalls. No local open ports required! It automatically handles disconnects and infinite retries.

npx -y staff-mcp@latest -t reverse \
  --ru https://chat.your-domain.com/api/mcp-reverse \
  --rt your_secure_token_here \
  --rn my-macbook-pro

🛠️ Core Capabilities

1. Seamless Containerization (--docker)

Never pollute your host machine again. By simply appending --docker <image>, staff-mcp:

• Instantly injects itself into the container via read-only bind mounts (no npm install inside the container).
• Automatically translates Windows/Mac paths to Linux container paths.
• Provides a --docker-args backdoor for hardware pass-through (e.g., ADB USB debugging, GPUs, host network).

2. Skill & Profile Ecosystem (--profile)

staff-mcp acts as an "AI Workspace Configurator". It uses a 5-tier Cascade Resolution architecture to load role-specific skills (SOPs & Prompts) dynamically, all under the unified .staff directory convention:

| Priority | Tier | Path | Watch | |:---:|:---|:---|:---:| | 1 (Highest) | Project | <cwd>/.staff/skills | ✅ 实时生效（自动创建目录） | | 2 | Project Profile | <cwd>/.staff/profiles/<profile>/skills | 🔄 需重启 | | 3 | Global Profile | ~/.staff/profiles/<profile>/skills | 🔄 需重启 | | 4 | Global | ~/.staff/skills | 🔄 需重启 | | 5 (Lowest) | Built-in | staff-mcp/builtin-profiles | 🔄 需重启 |

Profile is an additive parameter — tiers 1 and 4 are always loaded regardless of profile. Tiers 2, 3, and 5 append profile-specific paths. When skills with the same name exist at multiple tiers, the higher-priority one wins (merge with override, not whole-tier replacement).

Only the project-level .staff/skills/ directory is live-watched. The directory is auto-created on startup if absent, and auto-recovered if deleted at runtime. All other tiers require restart.

Switch roles on the fly:

npx -y staff-mcp@latest --profile default
npx -y staff-mcp@latest --profile android-reverse

3. Built-in skill-manager

Out of the box, the AI assistant knows how to manage its own skills! You can simply ask it to:

"Install the official Anthropic canvas-design skill into my project." It will securely download, configure, and reload the skill without you lifting a finger.

4. Advanced Shell & Code Intelligence

• Intelligent Shell Execution: Auto-detects and upgrades to /bin/bash if available, supporting complex pipelines and background tasks (e.g., starting dev servers and tailing logs).
• LSP Integration: Extract symbols, get diagnostics, go to definitions, and find references for TypeScript, Python, and more.
• Secure Sandbox: Strictly confines the AI to the specified working directory and user-defined allowed paths.

🎛️ CLI Arguments

| Option | Description | Default | | :--- | :--- | :--- | | -w, --working-dir | Root directory for the sandbox | process.cwd() | | -d, --allowed-dir | Extra directories allowed for access | [] | | -r, --profile | The active profile for skills (e.g., android-reverse) | default | | --enable-lsp | Enable LSP capabilities (disabled by default) | false | | --docker | Run inside a Docker container using this image | undefined | | -D, --docker-args | Extra args for docker run (e.g., -e FOO=BAR) | [] | | -t, --transport | Transport type (stdio, http, or reverse) | stdio | | -p, --port | Port for HTTP server | 3000 | | -h, --host | Host for HTTP server | 127.0.0.1 | | --ru, --reverse-url | URL for Reverse MCP Gateway | undefined | | --rt, --reverse-token | Security token for Reverse MCP | undefined | | --rn, --reverse-name | Server name for Reverse MCP | undefined |

Hardware Pass-through Example (Android Reverse Engineering)

If you need the AI to interact with an Android device connected via USB while running inside a container, utilizing network-based ADB pass-through is the most reliable cross-platform solution:

# 1. Start ADB Server on the host machine listening on all interfaces:
# adb kill-server && adb -a nodaemon server start

# 2. Start staff-mcp with the ADB_SERVER_SOCKET environment variable injected
# On Mac/Windows:
npx -y staff-mcp@latest --docker chineseastar/security:latest -D "-e ADB_SERVER_SOCKET=tcp:host.docker.internal:5037"

# On Native Linux (If not using --network host, point to the docker bridge IP):
npx -y staff-mcp@latest --docker chineseastar/security:latest -D "-e ADB_SERVER_SOCKET=tcp:172.17.0.1:5037"

# Alternative for Native Linux (Share host network stack completely):
npx -y staff-mcp@latest --docker chineseastar/security:latest -D "--network host"

📄 License

MIT