Aura-Code MCP server
Commit Oct 31, 2026Provides an agentic framework for AI software assurance, architectural blueprinting, and active guardrails during AI-driven development.
Also known as Maferreira25/Aura-Code
- Stars
- 1
- Tools
- β
- Downloads, 30 days
- β
- Latest version
- β
- Last commit
- Oct 31, 2026
- License
- MIT
What is Aura-Code MCP?
Aura-Code provides an agentic framework for AI software assurance, architectural blueprinting, and active guardrails during AI-driven development.
Summary generated from the project's README
About Aura-Code MCP server
AuraCode provides a framework for software assurance and architectural planning designed to prevent risks like architectural erosion and hallucinated dependencies during AI-driven development. It is built for developers and non-technical users who want to move from raw ideas to evidence-gated releases using a zero-trust approach. The system requires users to define complete theoretical architectures in markdown blueprints before any code is generated, ensuring that business rules and technical trade-offs are explicitly approved rather than guessed by an agent.
Users interact with the framework through a command-line interface to manage different layers of protection. The toolkit includes Aura Guard for inspecting tool execution, Aura Worktree for isolating agent changes in independent Git directories, and Aura Cage for configuring DevContainer environments with default-deny network policies. For automated development, the Aura Loop provides a stateful iteration runner that enforces strict verification levels, including compilation, AST linters, and security checks, to prevent agents from bypassing tests or accumulating context degradation.
What you can do with it
- 1Prevent destructive command executionAn AI agent can be restricted from running dangerous shell commands like root deletions or disk formatting through active hook checks.
- 2Isolate agent development tasksA user can create a dedicated Git worktree to ensure that an AI's experimental changes do not affect the main development branch.
- 3Detect code quality issuesA developer can run deterministic analyzers to find dead code, resource leaks, or type-hint violations without relying on an LLM.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report βNot verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work Β· What to fix for more points
- Source repository linked and reachablemaferreira25/aura-code is public and reachablegithub.com/maferreira25/aura-code βPass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html βPass
- Commit or release in the last yearLast commit or release 2026-10-31github.com/maferreira25/aura-code βPass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAuraCode β Agentic Unified Reliability & Assurance Framework
AuraCode (Agentic Unified Reliability & Assurance for Code)
Status: 0.3.0.dev0 (Development Preview) β active implementation and validation
Language Support: Python has structural AST checks. TypeScript, JavaScript, Go, Java, and C# currently have partial heuristic checks and are not yet certified as equivalent AST coverage.
A vendor-neutral assurance toolkit evolving into a guided AI application builder. The current release provides real governance and analysis components, but it is not yet an end-to-end certified application builder. The missing builder, packaging, user experience, and empirical validation work is tracked in the roadmap and the approved _auracode_sdd/ specifications.
π Manifesto: AI Software Assurance & Lay-User Pair Programming
Artificial intelligence has fundamentally transformed software engineering. Large Language Models (LLMs) and autonomous coding agents can now interpret requirements, refactor systems, invoke tools, and generate thousands of lines of code in seconds. However, this velocity introduces critical risks when non-technical users interact with AI: hallucinated dependencies, silent assumptions, architectural erosion, superficial test suites (vitiated oracles), prompt injection vulnerabilities, and "AI slop" (bloated code, forgotten stubs, and unnecessary abstractions).
AuraCode bridges this gap through Zero-Trust AI Pair Programming for Non-Technical Users:
AI Zero Trust & Zero Presumption: Do not trust AI simply because the output looks plausible. AI must never silently guess requirements, interfaces, or technical trade-offs. Demand empirical evidence and explicit human authorization for every decision.
Core Principles of AuraCode
- Zero-Presumption Directive (TolerΓ’ncia Zero a PresunΓ§Γ΅es): The AI agent is strictly forbidden from inferring or deciding business rules, screen behaviors, data models, or error cases on its own. Every ambiguityβno matter how smallβtriggers a plain-language question to the user.
- House Blueprint First Paradigm (
_auracode_sdd/): Just like constructing a house, no application code, directories, or scripts are generated before the complete theoretical architecture (frontend, backend, database, security, APIs, design system, assurance level AL1-AL4) is fully specified and reviewed in markdown blueprints under_auracode_sdd/(4 graduated profiles:micro[1 spec],lite[3 specs],standard[7 specs], orenterprise[15 specs]). - Plain-Language Dialogue & Physical World Analogies: Complex technical trade-offs are translated into real-world analogies (e.g., Database $\rightarrow$ "Smart Filing Cabinet", Backend $\rightarrow$ "Restaurant Kitchen", API $\rightarrow$ "Waiter taking orders", Frontend $\rightarrow$ "Storefront counter", Authentication $\rightarrow$ "ID Badge"). Structured choice menus with simple pros and cons are provided whenever technical options arise.
- Active Containment & Sandboxing Controls: AuraCode provides Worktree, Guard, and Cage controls. Their protection applies only when installed, configured, and verified for the active execution surface.
- Native AST Static Analysis & Mutation Testing (
auracode <command>): Deterministic analyzers inspect supported patterns without relying on an LLM as the judge: they flag selected dead-code and stub patterns (auracode slop), possible resource leaks (auracode leaks), selected injection vectors (auracode sec), type-hint violations (auracode types), configured Clean Architecture dependency violations (auracode arch), and vacuous test patterns (auracode tests). Python receives structural AST analysis; the other listed languages currently receive narrower heuristic checks. These checks reduce risk but do not prove the absence of defects. - Progressive Assurance Levels (AL1 to AL4): From low-risk local utilities (AL1) to mission-critical financial infrastructure (AL4), verification rigor scales proportionally with the impact of failure.
π‘οΈ Five Implemented Control Areas
The development preview contains five control areas. Each one has a limited enforcement surface and must be verified in the environment where it is used:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β AURACODE V2.0 STACK β
ββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββ€
β 1. AURA GUARD β 2. AURA WORKTREE β 3. SDD ENTERPRISE β
β Pattern-based hook checksβ Optional branch isolation β 15 specification templates β
β on configured surfaces β through explicit worktrees β requiring human completion β
β and recognized commands β and verified Git state β and approval β
ββββββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββ€
β 4. AURA CAGE β 5. AURA LOOP β
β DevContainer Default-Deny configuration β Stateful iteration runner β
β requiring build and runtime verification β with configurable gates β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββ
1. Aura Guard: Active Pre/Post-Tool Execution Hooks (auracode guard)
- Inspects invocations only on integrations that load
.agents/hooks.jsonand dispatch them throughtools/pre_tool_guard.py. - Pattern-Based Protection: Rejects the supported destructive command patterns, including representative root deletion, disk-formatting,
dd, and destructive Git reset forms. - Pattern-Based Exfiltration Defense: Rejects supported patterns that pipe recognized secret names or private-key paths to recognized network tools. It does not inspect every possible shell, tool, encoding, or data-flow path.
- Quick setup:
auracode guard install .or direct audit check:auracode guard check --tool run_command --cmd "rm -rf /".
2. Aura Worktree: Physical Git Isolation (auracode worktree)
- Creates an independent Git worktree directory under
.auracode/worktrees/<task>for sessions that use this workflow. - When the worktree workflow is used and verified, agent changes are isolated from the developer's active branch.
- Commands:
auracode worktree create --task auth-featureauracode worktree listauracode worktree merge --task auth-featureauracode worktree clean --task auth-feature
3. SDD Enterprise Architecture: 15 Modular Specs (auracode init --profile enterprise)
- Extends the baseline 7-blueprint House Blueprint to 15 enterprise-grade specification cadernos:
01_visao_geral_e_negocio.mdβ Core vision and business domain.02_arquitetura_e_componentes.mdβ Clean Architecture boundaries and structural layout.03_modelo_de_dados_e_armazenamento.mdβ Schema, relational mapping, and persistence.04_seguranca_e_permissoes.mdβ RBAC, identity boundaries, and cryptography.05_apis_e_integracoes.mdβ Contract gateways and webhook specifications.06_interface_e_design_system.mdβ Storefront design system and UI components.07_nivel_de_garantia_e_testes.mdβ Assurance Level targets (AL1βAL4) and test pyramid.08_observabilidade_e_telemetria.mdβ Distributed tracing, structured metrics, and health checks.09_conformidade_e_privacidade.mdβ LGPD/GDPR compliance, data retention, and anonymization.10_resiliencia_e_recuperacao.mdβ Disaster recovery, circuit breakers, and RTO/RPO objectives.11_modelo_de_ameacas.mdβ STRIDE threat modeling, attack surface, and counter-measures.12_escalabilidade_e_cache.mdβ Horizontal scaling policies and caching invalidation strategies.13_integracoes_externas.mdβ Upstream/downstream partner SLAs, timeouts, and fallbacks.14_migracao_e_legado.mdβ Database versioning, migration rollback paths, and legacy bridging.15_implantacao_e_rollout.mdβ Blue/green deployment, canary releases, and rollback criteria.
4. Aura Cage: DevContainer Default-Deny Configuration (auracode cage)
- Generates a Linux DevContainer configuration with an
iptablesDefault-Deny policy and an explicit allowlist. - The policy applies only inside a successfully built and running container after
auracode cage verifyconfirms the expected configuration. Merely generating the files does not isolate the host or prove runtime enforcement. - This reduces common outbound exfiltration paths; it does not neutralize prompt injection itself or prove that every side channel is closed.
- Commands:
auracode cage init .auracode cage verify
5. Aura Loop: Ralph Architecture Autonomous Runner (auracode loop)
- Implements the stateless runner pattern inspired by Geoffrey Huntley's Ralph Architecture.
- Context Reset: Starts each supported iteration from explicit file state in a fresh process context. This is intended to reduce accumulated-context degradation, not prove model reliability.
- Anti-Reward-Hacking: Enforces 5 strict deterministic verification levels (Compilation $\rightarrow$ AST Linters $\rightarrow$ Unit Tests $\rightarrow$ Semantic Coverage $\rightarrow$ Security Check) after each turn. If an agent attempts to delete tests or weaken assertions to claim success, the iteration is rejected.
- Circuit Breaker: Automatic emergency halt if 3 consecutive failures occur, preventing wasteful token loops.
- Commands:
auracode loop run --max-turns 10auracode loop statusauracode loop reset
ποΈ Target Journey: From Idea to Evidence-Gated Release
AuraCode is being evolved toward a complete guided journey for non-technical users. In 0.3.0.dev0, several controls exist, but the visual Studio and certified end-to-end builder are still under construction. Production readiness must be established for a specific release and environment; it is never inferred from installing AuraCode.
graph TD
A["π‘ Raw Idea (Non-Technical Founder / User)"] --> B["1. Plain-Language Interview & Clarification<br>(auracode-new / auracode-clarify)"]
B --> C["2. House Blueprint Specifications<br>_auracode_sdd/ (Basic 7 or Enterprise 15)"]
C -->|Explicit Human Approval| D["3. Isolation & Active Protection<br>(Aura Worktree + Aura Cage + Aura Guard)"]
D --> E["4. Supervised Construction & AST Linters<br>(auracode-forward + arch, slop, leaks, sec, types)"]
E --> F["5. Autonomous Loop & Evidence Review<br>(Aura Loop / SARIF v2.1.0 / AL1βAL4)"]
F --> G["Release Candidate With Explicit Evidence"]
1. The Analogy: The "Senior Chief Engineer" vs. The "Hasty Mason"
- Conventional AI (Vibe Coding): Acts like a hasty mason who immediately pours cement and lays bricks on bare soil without a foundation or plumbing blueprints. The structure might look nice on day one, but it cracks, leaks, and collapses under production traffic.
- AuraCode (Senior Pair Programming): Aims to act like a chief engineer who first documents the blueprint in plain language and requires approval before construction. During implementation, supported code patterns can be checked by deterministic analyzers, while Worktree, Guard, and Cage add protection only on their configured and verified surfaces.
2. The 5-Phase Production Scope of Work
π Phase 1: Zero-Jargon Briefing & Clarification
- Zero-Presumption Directive: The AI is forbidden from guessing data models, screen behavior, or business rules.
- Physical World Analogies: Technical concepts are translated into daily physical terms (Database $\rightarrow$ "Smart Filing Cabinet", Backend $\rightarrow$ "Restaurant Kitchen", API $\rightarrow$ "Order Waiter", Authentication $\rightarrow$ "Building Badge").
- Gate G1 Ambiguity Scanner: The
auracode ambiguitycommand flags supported vague phrases ("maybe", "should work", "standard way") for human clarification; a clean result is not proof that every ambiguity was removed.
π Phase 2: The House Blueprint β SDD Specifications (_auracode_sdd/)
No code is generated before explicit user sign-off on the specification blueprints:
- Micro Profile (
--profile micro): 1 concise task/utility spec (01_task_spec.md) for quick scripts and bugfixes (AL1). - Lite Profile (
--profile lite): 3 essential blueprints (Vision & Rules, Architecture & Data, Tests & Acceptance) for MVPs and validation (AL2). - Standard Profile (
--profile standardor--profile basic): 7 core architectural blueprints for production web and backend systems (AL3). - Enterprise Profile (
--profile enterprise): 15 comprehensive blueprints for mission-critical, regulated, and high-scale systems (AL4).
π Phase 3: Sandboxed & Isolated Execution Environment
- Aura Worktree: Creates an isolated branch workspace (
.auracode/worktrees/<task>), safeguarding the developer's working directory. - Aura Cage: Generates a DevContainer Default-Deny configuration that must be built, run, and verified; it reduces selected network-exfiltration paths inside that container.
- Aura Guard: Activates pre-tool hooks for supported integrations and rejects recognized destructive or exfiltration command patterns.
ποΈ Phase 4: Supervised Construction & Clean Architecture
Implementation (auracode-forward) is strictly governed by deterministic AST linters:
- Configured Architecture Boundaries:
auracode archvalidates supported Python import relationships againstcontracts.json. - Slop Patterns:
auracode slopflags supported empty-stub, unreachable-code, and swallowed-exception patterns. - Resource Patterns:
auracode leaksflags supported resource-acquisition patterns that lack a recognized context manager. - Type-Hint Rules:
auracode typeschecks supported Python function signatures and selectedAnyusage. - Injection Patterns:
auracode secflags supported uses ofeval,exec, SQL string construction, andshell=True; it is not a universal security proof. - Dependency Existence Check:
auracode depsqueries PyPI metadata for declared Python packages and versions. It does not verify signatures, provenance, or package safety. - Surgical Diffs:
auracode diffchecks the selected Git diff against the configured line limit and protected-test rules.
π‘οΈ Phase 5: Autonomous Loop Execution & Assurance Evaluation
- Aura Loop: Multi-turn autonomous iterations with fresh process context intended to reduce accumulated-context degradation.
- OASIS SARIF v2.1.0 Integration: Unified findings format ingested by GitHub Advanced Security, SonarQube, and VS Code.
- Global Security Standards: Control coverage mapped to NIST SSDF 1.1, OWASP LLM Top 10, CWE Top 25, and ISO 25010.
- Non-Vacuous Test Suites:
auracode testsaudits test ASTs to ensure assertions are semantic and meaningful (zeroassert True).
3. Comparison: Conventional AI (Vibe Coding) vs. AuraCode
| Engineering Criterion | Conventional AI (Vibe Coding) | AuraCode (Senior Pair Programming) |
|---|---|---|
| Project Kickoff | Generates code immediately without understanding real scope | Structured interview and SDD Blueprint sign-off (Basic 7 or Enterprise 15) |
| Missing Requirements | AI guesses silently and makes unverified architectural choices | Zero Presumption: AI pauses and provides structured options with analogies |
| Code Architecture | Spaghetti code mixing DB, business logic, and UI in single files | Clean Architecture with inward dependency AST contracts (contracts.json) |
| Working Directory | Dirty working trees, broken uncommitted files, overwritten code | Aura Worktree: Complete physical Git directory isolation per task |
| Host System Safety | Executes dangerous commands (rm -rf, format) blindly |
Aura Guard: Real-time fail-closed hooks intercepting destructive actions |
| Network & Injection | Open network access vulnerable to prompt injection exfiltration | Aura Cage: Configures a Default-Deny policy inside a built and verified DevContainer |
| Error Handling | Errors swallowed with empty try/catch or except: pass |
Fail-Closed: AST linters block dead code and silent swallows (auracode slop) |
| Autonomous Runner | Long-context degradation (Dumb Zone) and hallucinated tasks | Aura Loop: Stateless Ralph Architecture runner with 5-level AST gates |
| Dependencies | Frequent package hallucinations and supply chain vulnerabilities | PyPI package/version existence lookup (auracode deps); no signature or safety attestation |
| Test Suite Quality | Tautological or fake tests (assert True) that test nothing |
AST Visitor (auracode tests) enforces semantic asserts and blocks tampering |
| Production Readiness | Often asserted without evidence | Readiness is not automatic; each required guarantee must be executed and evidenced for the declared scope |
π How to Install and Use in Your Project (Beginner & Lay-User Friendly Guide)
The current preview includes the Aura Studio visual shell and local server, but its guided workflows have not been implemented yet; the journey therefore still expects terminal familiarity.
Follow the simple steps below:
Step 0: Check prerequisites
The AuraCode CLI requires Python 3.9 or higher. Checkpoint and worktree workflows also require Git; Docker is needed only for Cage, container preview, and deployment workflows.
To check if Python is installed on your machine, open your terminal (Command Prompt, PowerShell, or macOS/Linux Terminal) and type:
python --version
- If it returns
Python 3.9or higher (3.10, 3.11, 3.12, 3.13), you are ready! - If it is not installed or returns an error, download the official installer for free at: python.org/downloads (on Windows, make sure to check the box "Add Python to PATH" during installation).
Step 1: Install the development preview
Until an official signed distribution exists, the command below installs directly from the development repository and must not be treated as a stable release:
# Standard Python-focused assurance:
pip install git+https://github.com/Maferreira25/Aura-Code.git
# Optional: With Tree-sitter multi-language AST support (TypeScript, JavaScript, Go, Java, C#):
pip install "auracode[multilang] @ git+https://github.com/Maferreira25/Aura-Code.git"
Verify what was actually installed:
auracode doctor
auracode skills verify
In the current preview, doctor reports studio=PASS for package integrity but keeps the overall result at NOT_RUN because studio_workflows=NOT_RUN: the guided workflows have not been implemented and validated yet. This is a known limitation, not a complete success. Additionally, doctor verifies whether the Docker daemon is responding (flagged NOT_RUN if Docker is installed but daemon is offline).
To copy the verified official skills into the current project without overwriting local changes:
auracode skills install .
π‘ Tip for Advanced Users (Instant Execution via
uvx):
If you already use Astral'suv, you can execute any AuraCode command directly without prior installation:
uvx --from git+https://github.com/Maferreira25/Aura-Code.git auracode <command>
Step 2: Choose Your Scenario
Now that AuraCode is installed, choose what you want to do:
π’ Scenario A: Starting a Brand-New Project from Scratch
(You have an idea for an app, website, or backend and want to develop it with explicit assurance checks)
- Create a clean folder for your project and enter it:
mkdir my-new-project cd my-new-project - Launch the Interactive Requirements Wizard:
The current prototype runs a five-stage briefing and scaffolds draft templates. It returns clarity asauracode wizard # (alias: auracode interview)NOT_RUN, never supplies missing decisions, and does not authorize construction. - Review and complete every generated blueprint in
_auracode_sdd/before approving it. - Application construction is not yet an end-to-end CLI feature in this preview; do not treat the scaffold as production readiness evidence.
π‘ Scenario B: Auditing and Protecting an Existing (Production) Project
(You already have a codebase and want to discover hidden bugs, silent errors, resource leaks, and architectural technical debt)
- Open your terminal inside your existing project folder:
cd path/to/your/project - Install the Real-Time Safety Guardrail (Aura Guard) and Git Pre-Push Hook:
This configures the supported integrations. Protection applies only to execution surfaces that invoke the hook and must be checked withauracode guard install .auracode guard check; it is not a universal barrier. - Run a Comprehensive Health Audit:
If your project is multi-language (Python, TypeScript, JavaScript, Go, Java, C#), run:auracode audit .auracode multilang . - Verify if your test suite has vitiated test oracles (fake/tautological assertions):
AuraCode will pinpoint gaps and generate prescriptive unit test code snippets ready to plug into your test suite.auracode tests --mutate
π οΈ CLI Reference (auracode <command>)
AuraCode provides static analysis, containment, mutation testing, multi-language, terminal briefing, local preflight, evidence audit, installation diagnostics, and skill-package commands:
# 1. Initialize workspace directories and SDD blueprints (profile: micro, lite, standard, enterprise)
auracode init --profile standard
# 2. Interactive Terminal Briefing Wizard for lay users (Zero Jargon TUI)
auracode wizard
# or alias: auracode interview
# 3. Flag supported textual ambiguity markers and generate clarification questions (Gate G1)
auracode ambiguity .
# 4. Scan Python AST for dead code, unreachable code, and swallowed errors
auracode slop .
# 5. Scan Python AST for unclosed resource leaks (file handles, sockets, DB connections)
auracode leaks .
# 6. Scan Python AST for strict type hints and unconstrained 'Any' usage
auracode types .
# 7. Scan test suite integrity, detect vacuous tests, or execute AST mutation testing
auracode tests .
auracode tests --mutate -s tools/multilang_runner.py -t tests/test_multilang_runner.py
# 8. Scan multi-language codebases (Python, TS, JS, Go, Java, C#) with unified SARIF reporting
auracode multilang .
# 9. Scan Python AST for injection vectors (eval/exec, shell=True, SQL injection)
auracode sec .
# 10. Verify Clean Architecture layer boundaries using AST contracts
auracode arch .
# 11. Verify dependencies against PyPI to prevent hallucinated packages (slopsquatting)
auracode deps .
# 12. Verify that repository changes are surgical (< 500 lines) and block test tampering
auracode diff .
# 13. Ingest external SARIF 2.1.0 or JSON linter findings for unified reporting
auracode sarif linter-report.json
# 14. Assess project against an Assurance Level (AL1-AL4)
auracode assess assessment.json
# 15. Start stdio Model Context Protocol (MCP) server for IDE integration
auracode mcp
Aura-Code MCP questions
What languages does AuraCode support for AST analysis?
Python currently has structural AST checks, while TypeScript, JavaScript, Go, Java, and C# have partial heuristic checks.
How does AuraCode prevent AI from making unauthorized decisions?
It uses a Zero-Presumption Directive where the AI is forbidden from inferring business rules or technical trade-offs and must ask the user for clarification.
What are the different assurance levels available?
The framework uses Progressive Assurance Levels ranging from AL1 (low-risk local utilities) to AL4 (mission-critical financial infrastructure).
Can AuraCode isolate agent changes from my main code?
Yes, through Aura Worktree, which creates independent Git worktree directories to isolate agent sessions from your active branch.