Winx Code Agent

What gabrielmaialva33/winx-code-agent MCP server does

gabrielmaialva33/winx-code-agent MCP server exposes coding-agent operations through MCP. Its toolset covers workspace initialization, shell execution, file reading and editing, context handoff, image delivery, and code navigation. The runtime is implemented in Rust and supports both local stdio clients and Streamable HTTP clients.

The server is designed for tasks that require more than one-off command execution. Shell state can persist within a session, including the current directory, foreground processes, background processes, interactive input, and terminal UI activity. Workspace modes include full access, read-only architect mode, and a code-writer mode with command and write-glob restrictions.

How it works

For local use, an MCP client launches winx-code-agent over stdio. For networked use, the process serves an MCP endpoint such as /mcp over Streamable HTTP. HTTP requests are authenticated with a bearer token and are associated with a principal, workspace, and durable session. On Unix, Winx uses a control process and per-session guardians to keep PTYs alive across HTTP disconnects, client restarts, and adapter upgrades.

The Initialize tool establishes the workspace relationship and returns a thread identifier, workspace root, and bounded temporary artifact directory. Clients generally call it once, unless their MCP environment provides Roots support for automatic bootstrapping. Shell commands can run in the foreground or background, be polled, and receive input such as Enter or Ctrl-C.

File mutations use a typed workflow. Reads return line-numbered content, visible ranges, and an opaque revision. EditFiles can then apply revision-bound patches, exact search-and-replace operations, batches, verification, and undo. Planning and validation happen before writes, and edits use canonical paths and atomic per-file replacement.

Tools and capabilities

The gabrielmaialva33/winx-code-agent MCP server provides these documented tools:

• Initialize for workspace and session setup.
• BashCommand for shell commands, polling, interactive input, and terminal UI control.
• ReadFiles for single or batched reads with line ranges and revision information.
• EditFiles for creating, changing, verifying, and undoing files.
• ContextSave for writing task details, file globs, active files, and Git state to a handoff file.
• ReadImage for validated JPEG, PNG, GIF, or WebP input as native MCP image content.
• CodeMap for Tree-sitter symbol outlines and reference lookup across supported codebases.

CodeMap supports outline and reference operations, with repository symbol maps bounded by token budget. The supplied description identifies 13 supported languages, including Python and Elixir.

Setup and configuration

Install the executable with Cargo:

cargo install winx-code-agent

A local MCP client can launch winx-code-agent directly. For HTTP, create a protected token file and start the service with a loopback bind and token-file option:

winx-code-agent serve --http --bind 127.0.0.1:8000 --token-file ~/.config/winx-http-token

Clients connect to http://127.0.0.1:8000/mcp and send the token as a bearer credential. Cloud clients require a reachable HTTPS endpoint, typically through a private tunnel, VPN, or authenticated reverse proxy. WINX_SHELL=zsh selects zsh instead of the default shell.

Limitations and notes

HTTP is the primary deployment path, but remote clients cannot use a loopback-only endpoint without an intervening network mechanism. The default HTTP configuration requires a strong bearer token and is intended to remain private unless protected by suitable HTTPS infrastructure. The command and write restrictions depend on the selected workspace mode, so agents needing unrestricted access must use the full-access mode. Image sources are size- and dimension-bounded, and terminal output is bounded before delivery to the model.