orkio 0.3.1

✨ Autonomous Unified Resource Architect ✨

🧠 Describe what you want. AURA builds it for you.

An AI-powered Model Context Protocol server that interprets natural language tasks,
validates them for safety, and executes them through a modular plugin architecture.
Write a task in Notion — or talk to an AI agent — and watch real projects appear on disk.

🌟 Overview

Most AI tools give you text. AURA gives you real, running projects.

You describe what you want — "Build a FastAPI todo app" — and AURA handles everything: understanding your intent, choosing the right framework, generating real code with proper structure, and scaffolding the entire project on your filesystem.

AURA works in three ways:

🏗️ Supported Frameworks

Every generated project contains real, functional code — not placeholders.

🎯 Features

🏛️ Architecture

              ┌──────────────┐
              │📝 User Task │
              └──────┬───────┘
                     ▼
              ┌──────────────┐
              │ 🧠 Interpreter│──→ LLM or rule-based fallback
              └──────┬───────┘
                     ▼
              ┌──────────────┐
              │ 🛡️ Validator │──→ rejects invalid plans
              └──────┬───────┘
                     ▼
              ┌──────────────┐
              │ 🎯 Orchestrator│──→ coordinates the pipeline
              └──────┬───────┘
                     ▼
              ┌──────────────┐
              │ 🔌 Plugin Mgr │──→ routes to the right plugin
              └──────┬───────┘
                     ▼
        ┌────────────┼────────────┐
        ▼            ▼            ▼
   ┌─────────┐ ┌─────────┐ ┌─────────┐
   │📦Scaff.│ │📋 Notion│ │🐙 GitHub│  ...
   └─────────┘ └─────────┘ └─────────┘
        │
        ▼
   ┌──────────────┐
   │ 📁Real Files │
   └──────────────┘

🔒 Safety chain detail

The LLM is never trusted blindly. Every response passes through validation:

Task ──→ LLM (1 call) ──→ JSON parse ──→ Validator ──→ Executor
              │                  │
              ▼ fail             ▼ fail
         Rule-based parser ◄────┘

💡 The system never crashes. Every failure is handled gracefully.

📂 Project Structure

aura-mcp/
├── 🐍 aura_mcp/                     Python package
│   ├── 💻 cli/                       Typer CLI (start, config, plugins, doctor, init)
│   ├── ⚙️ config/                    YAML config + loader with env overrides
│   ├── 🧠 core/                      Orchestrator, interpreter, executor, validator
│   ├── 🔗 integrations/
│   │   ├── 🤖 llm/                   LLM abstraction (OpenAI, local, factory)
│   │   └── 📋 notion.py              Notion API client
│   ├── 🔌 plugins/                   Auto-discovered plugin system
│   │   ├── base.py                   BasePlugin abstract class
│   │   ├── manager.py               Discovery + registry + dispatch
│   │   ├── scaffolder_plugin.py     Project scaffolding
│   │   ├── notion_plugin.py         Notion integration
│   │   ├── github_plugin.py         GitHub API
│   │   ├── docker_plugin.py         Dockerfile generation
│   │   └── filesystem_plugin.py     File & directory operations
│   ├── 🌐 server/                    FastMCP server (stdio transport)
│   └── 🛠️ utils/                     Logger, file helpers
├── 🧪 tests/                         252 pytest tests
├── 📜 scripts/                        DevOps verification scripts
├── 📚 docs/                           CONFIG.md, PLUGINS.md, README.md
├── 🌍 website/                        Static landing page
├── 📝 examples/                       Demo commands
├── 📦 pyproject.toml                  Package definition
├── 🐳 Dockerfile                      Container build
└── 🔄 .github/workflows/ci.yml       CI pipeline

🚀 Installation

From PyPI

pip install orkio

From source

git clone https://github.com/your-username/aura-mcp.git
cd aura-mcp
pip install -e .

With dev dependencies

pip install -e ".[dev]"

⚙️ Configure

cp .env.example .env

Edit .env with your keys:

NOTION_API_KEY=ntn_your_key
NOTION_DATABASE_ID=your_database_id
OPENAI_API_KEY=sk-your_key          # optional — falls back to rule-based parser
GITHUB_TOKEN=ghp_your_token         # optional — needed for github plugin

Or generate a YAML config:

aura init       # creates aura_config.yaml in the current directory

📋 Set up Notion

Create a database with these properties:

Then connect your integration: open the database menu (...) → Connections → add your integration.

💻 Usage

CLI commands

🩺 Doctor output

$ aura doctor

AURA MCP — System Doctor

 Check                Status  Detail
 Python version       ✅ OK    3.11.9
 Config file          ✅ OK    .../aura_mcp/config/config.yaml
 NOTION_API_KEY       ✅ OK    set
 NOTION_DATABASE_ID   ✅ OK    set
 OPENAI_API_KEY       ✅ OK    set
 GITHUB_TOKEN         ⚠️ MISS  missing
 LLM mode             ✅ OK    openai
 Plugins loaded       ✅ OK    docker, filesystem, github, notion, scaffolder

🔧 MCP Tools

AURA exposes three tools via the Model Context Protocol. Any MCP-compatible client — Claude Desktop, Cursor, or your own tooling — can call them directly.

🤖 Claude Desktop integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "aura-mcp": {
      "command": "aura",
      "args": ["start"]
    }
  }
}

Then ask Claude:

💬 "Run my pending Notion tasks"

💬 "Scaffold a FastAPI backend for a bookstore"

💬 "What tasks are pending in my Notion?"

📝 Examples

These task strings work with run_single_task or as Notion task titles:

🔹 create a fastapi todo app
🔹 build a react dashboard for analytics
🔹 setup a node express REST API for a bookstore
🔹 scaffold a fastapi blog backend
🔹 create a react portfolio website
🔹 build a node chat server with express

▶️ Example pipeline run

[AURA] ✅ === AURA MCP — Execution Pipeline ===
[AURA] 📋 Processing 1 task(s)...
[AURA] 📌 ---- Task: "Build a task manager with React" ----
[AURA] 🧠 Interpreting task...
[AURA] ✅ Parsed → action: scaffold_project, framework: react, name: task_manager
[AURA] 📦 Scaffolding react project...
[AURA] 📁 Created 8 file(s)
[AURA] ✅ Task completed
[AURA] 🏁 === Pipeline complete ===
[AURA] 📊 Results: 1 succeeded, 0 failed, 1 total

🔌 Plugin System

Plugins extend AURA without modifying core code. Every BasePlugin subclass inside aura_mcp/plugins/ is discovered and registered automatically at startup.

Built-in plugins

✍️ Writing a custom plugin

from aura_mcp.plugins.base import BasePlugin

class MyPlugin(BasePlugin):
    @property
    def name(self) -> str:
        return "my_plugin"

    def describe(self) -> str:
        return "Does something useful"

    async def execute(self, intent: dict) -> dict:
        # Your logic here
        return {"status": "ok"}

Drop the file into aura_mcp/plugins/ and it's live on the next startup. No wiring needed.

📖 See docs/PLUGINS.md for the full plugin development guide.

⚙️ Configuration

AURA loads configuration from three layers (last wins):

  ① Built-in defaults   →   ② YAML config file   →   ③ Environment variables
       (always)              (if file exists)            (highest priority)

Key settings

Example config

workspace: ~/projects
default_stack: fastapi
log_level: info
llm_mode: openai

openai:
  model: gpt-3.5-turbo

📖 See docs/CONFIG.md for the full configuration reference.

🧪 Testing

AURA includes a comprehensive test suite with 252 automated tests covering every subsystem.

# 🧪 Run the full suite
pytest

# 📋 Verbose output
pytest tests/ -v

# 🎯 Run a specific test file
pytest tests/test_pipeline.py

Test coverage breakdown

🛠️ DevOps verification

# Full package install + test run
python scripts/test_package_install.py

# Docker build + container verification
bash scripts/test_docker.sh

🐳 Docker

Build and run AURA in a container:

# 🏗️ Build the image
docker build -t aura-mcp .

# 🔌 List plugins
docker run --rm aura-mcp plugins

# 🩺 Run system doctor
docker run --rm aura-mcp doctor

# 🚀 Start the MCP server
docker run --rm -i \
  -e NOTION_API_KEY=ntn_your_key \
  -e NOTION_DATABASE_ID=your_db_id \
  aura-mcp start

💡 The scripts/test_docker.sh script automates Docker verification and handles missing Docker gracefully.

🤝 Contributing

Contributions are welcome — especially new plugins and integrations!

1. 🍴 Fork the repository
2. 🌿 Create a feature branch    →  git checkout -b feature/my-feature
3. ✅ Run linter and tests       →  ruff check aura_mcp/ && pytest
4. 📬 Open a pull request

📖 Please read CONTRIBUTING.md before submitting.

🤝 See CODE_OF_CONDUCT.md for community guidelines.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.