bluebox

Bluebox is a Python-based MCP server that runs the bluebox agent to perform web data extraction by interpreting natural language requests, mapping them to pre-built routines, and orchestrating multiple routines in parallel. The agent can fall back to an AI browser-driven workflow for tasks without predefined routines, post-process results with Python (CSV, JSON, etc.), and save outputs to a local workspace. Use this server when you need to programmatically query undocumented or UI-driven web APIs and automate complex data extraction tasks. After starting, you can interact with the agent to request analyses like price checks, data compilation from multiple web sources, or routine-driven scrapes, and you can replay successful sessions via generated context files to reproduce results quickly in future runs.

Prerequisites:

• Python 3.12+ installed on your system
• Access to Vectorly API key (VECTORLY_SERVICE_TOKEN)
• An API key for an LLM provider (OPENAI_API_KEY or ANTHROPIC_API_KEY) depending on your choice
• Optional: uv for dependency management (recommended for faster installs)

Installation steps:

1. Clone the repository:

git clone https://github.com/VectorlyApp/bluebox.git
cd bluebox

2. Create and activate a Python virtual environment:

python3 -m venv bluebox-env
source bluebox-env/bin/activate  # On Windows: bluebox-env\Scripts\activate

3. Install the package in editable mode:

pip install -e .

4. Optional: install with uv for faster dependency handling:

# If you have uv installed or install it first
uv venv bluebox-env
source bluebox-env/bin/activate
uv pip install -e .

5. Set required environment variables (see prerequisites) and run the server via the MCP config (see mcp_config section):

# Example launching via the MCP system (depends on your MCP orchestrator)
# This command assumes the MCP runner reads the Python module entrypoint as shown in mcp_config
python -m bluebox

• The bluebox agent requires a Vectorly API key and an LLM provider key. Ensure these are kept secure and not committed to version control.
• If you use OpenAI, set OPENAI_API_KEY in your environment or a .env file; if you prefer Anthropic, set ANTHROPIC_API_KEY instead.
• For dependency management, uv can speed up environment setup, but is optional.
• The agent can produce a local workspace with generated outputs; ensure your filesystem has enough space for large post-processed results.
• To replay a successful session, use the /generate_context mechanism described in the README and then load the context file on a new run.