✨ Winx - MCP Server for Shell & Coding Agents ✨

Winx is a specialized Model Context Protocol (MCP) server for LLM code agents that need local shell execution, file reads, file edits, image reads, and task context snapshots.

It is inspired by WCGW, but it is not a Python wrapper. Winx provides a native Rust MCP server with PTY-backed shell sessions, workspace-aware file access, mode-aware write restrictions, and robust SEARCH/REPLACE editing behavior designed for real coding-agent workflows.

Features

Stateful shell execution through BashCommand, including foreground commands, background commands, status checks, text input, special keys, and ASCII input.
Workspace initialization through Initialize, with wcgw, architect, and code_writer modes.
File reading through ReadFiles, including path suffix line ranges such as /path/file.rs:10-40, /path/file.rs:10-, and /path/file.rs:-40.
File editing through FileWriteOrEdit, including full writes and tolerant SEARCH/REPLACE blocks.
Context capture through ContextSave.
Image reads through ReadImage for multimodal MCP clients.

MCP Tools

Tool	Purpose
`Initialize`	Initializes the workspace, mode, and thread state. Call this before other tools.
`BashCommand`	Runs shell commands and interacts with running foreground/background commands.
`ReadFiles`	Reads one or more files with line numbers and optional line ranges.
`FileWriteOrEdit`	Writes full files or applies SEARCH/REPLACE edits after the file has been read.
`ContextSave`	Saves a task summary and relevant file contents for handoff/resume.
`ReadImage`	Reads an image file and returns base64 content with MIME metadata.

Search/Replace Editing

FileWriteOrEdit supports standard blocks:

  <<<<<<< SEARCH
  old content
  =======
  new content
  >>>>>>> REPLACE

The matcher is intentionally tolerant for common agent mistakes:

preserves atomicity: ambiguous or missing matches fail without writing;
handles indentation drift and adjusts replacement indentation;
removes ReadFiles line numbers when they are accidentally included;
normalizes common Unicode quote, dash, and ellipsis mistakes;
can use surrounding blocks as context to disambiguate repeated snippets;
supports single-line substring edits when the search block is part of a line.

Installation

Install the binary from crates.io:

cargo install winx-code-agent

This puts winx-code-agent on your $PATH (usually ~/.cargo/bin). Every example below assumes the binary is reachable; if it isn't, use the absolute path returned by which winx-code-agent.

Requirements:

Rust 1.75+ (rustc --version)
Linux, macOS, or WSL2
A terminal that can host a PTY (any standard terminal works)

One-liner via the CLI (stdio is the default transport):

claude mcp add winx -- winx-code-agent

Or drop a .mcp.json in your project root:

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

Add to your config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

Restart Claude Desktop after saving.

One-liner:

codex mcp add winx -- winx-code-agent

Or edit ~/.codex/config.toml:

[mcp_servers.winx]
command = "winx-code-agent"
env = { RUST_LOG = "winx_code_agent=info" }

Add to ~/.cursor/mcp.json (or .cursor/mcp.json for project-local):

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

Add to .vscode/mcp.json:

{
  "servers": {
    "winx": {
      "type": "stdio",
      "command": "winx-code-agent"
    }
  }
}

Add to your Zed settings (~/.config/zed/settings.json):

{
  "context_servers": {
    "winx": {
      "source": "custom",
      "command": "winx-code-agent",
      "args": [],
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

Add to opencode.json:

{
  "mcp": {
    "winx": {
      "type": "local",
      "command": ["winx-code-agent"],
      "enabled": true,
      "environment": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "args": [],
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

agy is Google's new Gemini-powered Antigravity CLI (Go binary published as agy in ~/.local/bin). It reads MCP servers from a shared JSON config — there's no mcp add subcommand yet.

Add to ~/.gemini/config/mcp_config.json (the CLI also reads ~/.gemini/antigravity/mcp_config.json; keep both in sync if you also use the Antigravity IDE):

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

If winx-code-agent is not on the agy process $PATH, swap command for the absolute path (~/.cargo/bin/winx-code-agent after cargo install winx-code-agent).

Add to your ~/.continue/config.yaml:

mcpServers:
  - name: winx
    command: winx-code-agent
    env:
      RUST_LOG: winx_code_agent=info

Add to ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

Settings → MCP Servers → Add MCP Server:

{
  "winx": {
    "command": "winx-code-agent",
    "env": { "RUST_LOG": "winx_code_agent=info" }
  }
}

Add to your Roo Code MCP config:

{
  "mcpServers": {
    "winx": {
      "type": "stdio",
      "command": "winx-code-agent"
    }
  }
}

Any MCP client that supports a local stdio process can run Winx with this shape:

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "args": [],
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

If the client cannot find winx-code-agent on $PATH, replace it with the absolute path (which winx-code-agent or ~/.cargo/bin/winx-code-agent).

If you want the latest unreleased changes or a custom build:

git clone https://github.com/gabrielmaialva33/winx-code-agent.git
cd winx-code-agent
cargo install --path .

cargo install --path . is the same as cargo install winx-code-agent but pinned to the working tree. You can also run the binary directly without installing:

cargo build --release
./target/release/winx-code-agent

Verify the connection

After configuring your client, the first tool call should be Initialize. From any MCP client you can confirm Winx is reachable by listing available tools — you should see Initialize, BashCommand, ReadFiles, FileWriteOrEdit, ContextSave, and ReadImage.

Development

Useful local checks:

cargo fmt --all -- --check
cargo check --tests
cargo clippy --all-targets --all-features
cargo test --all-features

For formatting changes:

cargo fmt --all

Security Model

Winx is a local MCP server with filesystem and shell access. Treat any MCP client connected to it as capable of reading files, editing files, and running commands within the configured workspace and mode.

Use architect mode for read-oriented sessions and code_writer mode when you want to restrict writable globs and allowed commands. See SECURITY.md for reporting and operational guidance.

License

MIT - Gabriel Maia (@gabrielmaialva33)

winx-code-agent 0.2.307