✨ 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.

Quick Start

Requirements

Rust 1.75 or newer
Linux, macOS, or WSL2

Build

git clone https://github.com/gabrielmaialva33/winx-code-agent.git
cd winx-code-agent
cargo build --release

Run

./target/release/winx-code-agent serve

The server uses MCP over stdio.

MCP Client Configuration

Example configuration:

{
  "mcpServers": {
    "winx": {
      "command": "/absolute/path/to/winx-code-agent/target/release/winx-code-agent",
      "args": ["serve"],
      "env": {
        "RUST_LOG": "warn"
      }
    }
  }
}

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.304