Alara Bridge (StdIO)

April 19, 2025 · View on GitHub

This package provides a Machine Cognition Protocol (MCP) bridge using standard input/output (stdio) to connect an MCP client (like Cursor) to the Alara backend API.

Features

Dynamically fetches available tools from the Alara OpenAPI schema.
Executes tool calls by forwarding requests to the Alara API.
Authenticates with the backend using an API key provided via environment variable.

Installation

# Install from PyPI
pip install alara

Configuration

This bridge uses the command-based configuration method for MCP clients like Cursor. The package includes a helper script to generate the necessary JSON snippet for you.

Install the package:
```
pip install alara
```
Generate your API Key: Obtain your API key from the Alara platform dashboard.
Generate MCP Configuration: Run the following command in your terminal, replacing YOUR_ALARA_API_KEY_HERE with the key you obtained:
```
python -m alara.main --api-key YOUR_ALARA_API_KEY_HERE --print-mcp-config
```
(Note: If python doesn't work, try python3)

Copy the Output: The command will print a JSON object similar to the example below. Copy this entire object.

{
    "mcpServers": {
        "alara": {
            "name": "Alara",
            "description": "Alara Bridge (Python Module)",
            "protocol": "stdio",
            "command": "/path/to/installed/python", // Path to python in venv
            "args": ["-m", "alara.main"],
            "cwd": "/path/to/alara/project/root",
            "env": {
                "ALARA_API_KEY": "YOUR_ALARA_API_KEY_HERE", // Your key inserted here
                "ALARA_MCP_URL": "https://alara-mcp.skolp.com" // Changed default backend URL
            }
        }
    }
}

(The command and cwd paths will be automatically detected based on your installation.)

Configure Cursor: Open your Cursor configuration file (e.g., ~/.cursor/mcp.json) and paste the copied JSON object into the "mcpServers" section (or merge it if the section already exists).
Reload MCP Clients: Reload the clients in Cursor (e.g., via the command palette).

Development Setup

Clone the repository:

git clone https://github.com/rizkisyaf/alara.git
cd alara

Create a Python virtual environment:

python3 -m venv venv
source venv/bin/activate

Install dependencies, including development tools:
```
pip install -e ".[dev]" 
```
(Note: Requires defining [project.optional-dependencies] in pyproject.toml if you have dev tools like pytest, ruff, etc.)

Create a .env file in the project root with your API key for local testing:

ALARA_API_KEY=YOUR_ALARA_API_KEY_HERE
ALARA_MCP_URL=https://alara-mcp.skolp.com # Changed default backend URL
# Optional: Set LOG_LEVEL=DEBUG for more verbose logging
# LOG_LEVEL=DEBUG

Run the bridge directly (for testing purposes):
```
python -m alara.main 
```

License

This project is licensed under the MIT License - see the LICENSE file for details (if one exists).