Brainfaq MCP

🚀 brainfaq-mcp

An MCP server for the Brainfuck programming language, enabling your favorite LLM to debug Brainfuck programs.

🚀 Quick Start

Use the following command to run the MCP server:

npx brainfaq-mcp

To use it in VS Code, add the following JSON snippet to .vscode/mcp.json (create the file if it doesn't exist):

{
  "servers": {
    "brainfaq-mcp": {
      "command": "npx",
      "args": ["brainfaq-mcp"]
    }
  }
}

The MCP can be added to other IDEs with LLM agents support (e.g., Cursor) in a similar way. Check their documentation and configure them to run npx brainfaq-mcp. It will start the MCP server in stdio mode.

✨ Features

MCP Tools

• load_code: Reset the debugger and load new Brainfuck source code. It supports configurable tape size, min/max cell values, and initial input.
• step: Execute a specified number of instructions (default 1) with detailed state output.
• run: Run the program until it finishes or waits for input, with an optional instruction limit.
• add_input: Append characters to the input buffer when the program is waiting for input.
• get_state: Get the current interpreter state (memory, pointers, output) with optional windowing.
• read_output: Get the complete output string generated so far.

Capabilities

• Full Brainfuck support (8 operations: >, <, +, -, ., ,, [, ]).
• Overflow/underflow detection with configurable value limits.
• Bracket matching validation and loop control.
• Step-by-step execution and debugging.
• Memory protection with configurable tape size.

📦 Installation

Setup

npm i

Build

npm run build

Tests

npm run test

The tests are inspired by the Brainfuck test suite by Daniel Cristofani.

📄 Release

First, build the source code using the commands above.

Login to NPM

npm login

Publish to NPM

npm publish

📄 License

All work in this repository is licensed under the "Creative Commons Attribution-ShareAlike 4.0 International License".