orkio 0.3.1

Autonomous Unified Resource Architect — an extensible MCP platform that reads Notion tasks and executes them

✨ 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:

💬 Via Notion	🤖 Via AI Agent	⌨️ Via CLI
Write a task in Notion. AURA fetches it, builds it, marks it done.	Claude Desktop, Cursor, or any MCP client calls AURA's tools directly.	Run aura start and interact through the command line.

🏗️ Supported Frameworks

⚡ FastAPI main.py · routes.py requirements.txt Pydantic models · CRUD

🟢 Node / Express index.js · package.json Routes · Middleware CORS · Error handling

⚛️ React src/App.js · Components package.json Styling · HTML template

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

---

🎯 Features

	Feature	Description
🧠	AI Task Interpretation	Understands natural language via OpenAI with a deterministic rule-based fallback
🛡️	Safety Chain	Every plan is validated before execution — bad input never reaches the filesystem
🔌	Plugin Architecture	Drop a file into aura_mcp/plugins/ and it's discovered automatically
📦	Project Scaffolding	Generates complete FastAPI, Node/Express, and React projects
🔧	3 MCP Tools	run_aura · get_pending_tasks · run_single_task
🧩	5 Built-in Plugins	Notion · Scaffolder · GitHub · Docker · Filesystem
💻	CLI Toolkit	start · plugins · config · doctor · init
⚙️	YAML Config + Env Overrides	Three-layer configuration with sensible defaults
🐳	Docker Support	Single-stage Dockerfile for containerized deployment
✅	252 Automated Tests	Comprehensive coverage across every subsystem

---

🏛️ 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 ◄────┘

Scenario	What Happens
🔑 No OpenAI key?	Rule-based parser runs automatically
💥 LLM returns bad JSON?	Falls back to rule-based parser
🚫 Validator rejects the plan?	Falls back to rule-based parser
❌ Execution fails?	Notion updated with error details, pipeline continues

💡 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:

Property	Type	Notes
Name	Title	Your task description
Status	Status	Pending → In progress → Done
Output	Rich text	AURA writes results here

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

---

💻 Usage

CLI commands

Command	Description
🟢 aura start	Start the MCP server (stdio transport)
🔌 aura plugins	List all discovered plugins with health status
⚙️ aura config	Display the active configuration (secrets masked)
🩺 aura doctor	Check system readiness — Python, config, env vars, plugins
📄 aura init	Initialize a config file in the current directory
🐛 aura plugins-debug	Show detailed debug info for every loaded plugin

🩺 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.

Tool	Input	Description
🚀 run_aura	—	Full pipeline: fetch Notion tasks → interpret → scaffold → update status
📋 get_pending_tasks	—	Return all pending tasks from the connected Notion database
⚡ run_single_task	{ task: "..." }	Interpret and scaffold from text — no Notion required

🤖 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

Plugin	Emoji	Capabilities
scaffolder	📦	Generate React, Node.js, and FastAPI projects
notion	📋	Fetch pending tasks, update task status
github	🐙	Create repositories, commit files via the GitHub API
docker	🐳	Generate Dockerfiles for Node, React, and FastAPI
filesystem	📁	Create folders, create files, list directories

✍️ 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

Key	Env Override	Default	Description
workspace	AURA_WORKSPACE	~/projects	📁 Where scaffolded projects are created
llm_mode	AURA_LLM_MODE	openai	🤖 LLM provider: openai or local
log_level	AURA_LOG_LEVEL	info	📊 Logging verbosity
notion.api_key	NOTION_API_KEY	—	📋 Notion integration token
notion.database_id	NOTION_DATABASE_ID	—	📋 Notion database to read tasks from
openai.api_key	OPENAI_API_KEY	—	🧠 OpenAI API key
openai.model	OPENAI_MODEL	gpt-3.5-turbo	🧠 Model used for task interpretation
github.token	GITHUB_TOKEN	—	🐙 GitHub personal access token

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

Test File	Tests	Covers
🔄 test_pipeline.py	39	Interpreter → Validator → Orchestrator integration
📦 test_scaffolder.py	61	React, Node, FastAPI project generation
🔌 test_plugins.py	40	Plugin discovery, registry, execution
💻 test_cli.py	34	CLI commands (start, plugins, config, doctor, init)
⚙️ test_config.py	36	Config loading, env overrides, YAML merge
🌐 test_mcp_server.py	28	MCP server tools and JSON responses
🧠 test_interpreter.py	6	Rule-based task interpretation
🛡️ test_validator.py	8	Plan validation and sanitization

🛠️ 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.

---

💜 Built Aryan Kumar

📚 Documentation · 🔌 Plugin Guide · ⚙️ Configuration · 🔒 Security

⭐ Star this repo if you find it useful! ⭐