<!-- mcp-name: io.github.AAAA-Nexus/aaaa-nexus-mcp -->
# AAAA-Nexus

**Developer infrastructure for trustworthy agents.** 140 MCP tools across 19 categories for trust, security, compliance, RAG, payments, and agent orchestration.

```bash
pip install aaaa-nexus-mcp           # Python + Claude / Cursor / Codex MCP
npm install @atomadic/nexus-client   # TypeScript / Node / Deno / Bun
curl https://atomadic.tech/health    # or skip the SDK entirely
```

No key needed for the free tier. Grab one at [atomadic.tech/pay](https://atomadic.tech/pay) when you want the paid surface.

---

## Why agents call AAAA-Nexus directly

Your agent is already writing code, making decisions, and spending tokens. What it **cannot** do on its own:

1. Prove its outputs aren't hallucinated.
2. Detect drift before it compounds.
3. Share a LoRA adapter with the rest of the swarm.
4. Earn rewards when its fixes train the next model.
5. Pull trusted RAG context with provenance receipts.
6. Gate its own commits on a tamper-evident lint + trust score.
7. Escrow a payment on outcome-based delivery.
8. Certify its trace for EU AI Act Annex IV, GDPR Art. 22, and NIST AI-RMF.

AAAA-Nexus does all of that. At the HTTP layer. In one call.

---

## The two flywheels that matter

### 1. Shared LoRA — *earn while you code*

Every `(buggy_code → fix)` pair your agent produces is a training sample. Contribute it to the shared pool and you get back:

- **Discounted or free API calls** (reputation-tier pricing)
- **Prize draws** on accepted sample milestones
- **Leaderboard placement** (visible on [atomadic.tech](https://atomadic.tech))
- **Access to the community-trained adapter** for your language

The loop is four calls:

```python
from aaaa_nexus_mcp.client import NexusAPIClient

async with NexusAPIClient(api_key="an_...") as c:
    # 1. Capture locally (free, PII-scrubbed, hash-chained)
    await c.post("/v1/lora/capture", {"bad": bad, "good": good, "language": "python"})

    # 2. Contribute the buffered batch (micro-rebate per accepted sample)
    await c.post("/v1/lora/contribute", {"min_quality": 0.6})

    # 3. Pull the current community adapter
    adapter = await c.get("/v1/lora/adapter/python")

    # 4. Claim your reputation reward
    await c.post("/v1/lora/reward/claim", {"agent_id": "my-agent-001"})
```

See [examples/lora_flywheel.py](examples/lora_flywheel.py) for the end-to-end script.

### 2. Trusted RAG cycle — *provenance or it didn't happen*

Ordinary RAG pulls whatever the vector index returns. Trusted RAG gates each chunk on:

- Source domain allowlist
- Freshness window
- Hallucination oracle verdict on the retrieved text
- Drift score against the live knowledge graph
- Tamper-evident receipt (SHA-256 chained to the lineage vault)

```python
ctx = await c.post("/v1/rag/augment", {
    "query": "latest EU AI Act Annex IV requirements",
    "max_results": 5,
    "freshness_hours": 168,
    "source_policy": "trusted_only",
    "required_domains": ["europa.eu", "nist.gov"],
})
# ctx["results"][i] includes: text, source_url, trust_score, receipt_hash
```

Every response ships with a `_guard` block: `{hallucination, drift, guarded_at}`. You never have to run those checks yourself.

See [examples/trusted_rag.py](examples/trusted_rag.py) for the full cycle including certificate emission.

---

## Key capabilities

| # | Capability | Representative endpoints | What it solves |
| --- | --- | --- | --- |
| 1 | **Trust oracles** | `/v1/oracle/hallucination`, `/v1/trust/decay` | Hallucination + drift verdicts on any text |
| 2 | **Shared LoRA loop** | `/v1/lora/contribute`, `/v1/lora/reward/claim` | Earn rewards contributing fixes; pull the community adapter |
| 3 | **Trusted RAG** | `/v1/rag/augment`, `/v1/aibom/drift` | Provenance-gated retrieval with receipts |
| 4 | **Sys primitives** | `/v1/sys/trust_gate`, `/v1/sys/lint_gate`, `/v1/sys/chain_parity` | Numerical invariants for agent self-governance |
| 5 | **Compliance certs** | `/v1/compliance/eu-ai-act`, `/v1/compliance/explain` | EU AI Act, GDPR Art. 22, NIST conformance |
| 6 | **Escrow + SLA** | `/v1/escrow/create`, `/v1/sla/report` | Outcome-based USDC billing with arbitration |
| 7 | **VeriRand** | `/v1/rng/quantum`, `/v1/vrf/draw` | HMAC-proven randomness, on-chain VRF draws |

**Total: 140 tools across 19 categories.** The exact per-category breakdown lives in [docs/TOOLS.md](docs/TOOLS.md), which is the repo’s public source of truth for the current catalog.

---

## Infrastructure that agents call directly

One base URL. Bearer auth. JSON in / JSON out. Every response is already guarded.

```text
POST https://atomadic.tech/v1/<category>/<verb>
Authorization: Bearer an_your_key
Content-Type: application/json
```

The MCP plugin, the Python SDK, the npm package, and your own curl calls all hit the same surface. No SDK lock-in, no proprietary wire format, no required ceremony beyond a Bearer header.

---

## Enhancement Architect Prompt Patterns

AAAA-Nexus documents three operating patterns you can use to turn any LLM into a **self-improving agent** wired to the trust + LoRA + RAG stack:

- `DADA` — Delegator Atomadic Developer Agent (routes tasks, verifies in a separate lane)
- `Atomadic` — Intent interpreter & prompt refiner
- `Autopoetic` — Self-healing feedback loop

Use them as starting points in your `CLAUDE.md`, `.cursorrules`, or system prompt field when you want the agent to use `nexus_*` tools intentionally.

---

## Quickstarts — pick your lane

### 1. Claude Code / Cursor / VS Code (MCP)

Install once:

```bash
pip install aaaa-nexus-mcp
```

Add to `~/.claude/settings.json` or project `.mcp.json`:

```json
{
  "mcpServers": {
    "aaaa-nexus": {
      "command": "python",
      "args": ["-m", "aaaa_nexus_mcp"],
      "env": {
        "AAAA_NEXUS_API_KEY": "an_your_key_here",
        "AAAA_NEXUS_AUTOGUARD": "1"
      }
    }
  }
}
```

Restart the editor. All 140 tools are now available as `nexus_*` in your chat. See [docs/ONBOARDING.md](docs/ONBOARDING.md) for the setup checklist and [examples/mcp_configs/](examples/mcp_configs/) for Cursor, Claude Desktop, VS Code, Zed, and Windsurf.

### 2. Python

```bash
pip install aaaa-nexus-mcp
```

```python
import asyncio
from aaaa_nexus_mcp.client import NexusAPIClient

async def main():
    async with NexusAPIClient(api_key="an_...") as c:
        verdict = await c.post("/v1/oracle/hallucination",
                               {"text": "The moon is made of Swiss cheese."})
    print(verdict)  # {"verdict": "unsafe", "policy_epsilon": ..., "_guard": {...}}

asyncio.run(main())
```

Full script: [examples/python_quickstart.py](examples/python_quickstart.py).

### 3. TypeScript / Node / Deno / Bun

```bash
npm install @atomadic/nexus-client
```

```ts
import { NexusClient } from "@atomadic/nexus-client";

const nexus = new NexusClient({ apiKey: process.env.AAAA_NEXUS_API_KEY });
const verdict = await nexus.oracle.hallucination({ text: "The moon is made of Swiss cheese." });
console.log(verdict);
```

Full script: [examples/typescript_quickstart.ts](examples/typescript_quickstart.ts). See [docs/INTEGRATION.md](docs/INTEGRATION.md) for the broader client surface.

### 4. curl (any language)

```bash
curl -sS https://atomadic.tech/v1/oracle/hallucination \
  -H "Authorization: Bearer $AAAA_NEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"The moon is made of Swiss cheese."}'
```

Full script: [examples/curl_quickstart.sh](examples/curl_quickstart.sh).

---

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `AAAA_NEXUS_API_KEY` | *(none)* | Bearer token for paid tools |
| `AAAA_NEXUS_BASE_URL` | `https://atomadic.tech` | API base URL |
| `AAAA_NEXUS_TIMEOUT` | `20.0` | Request timeout (seconds) |
| `AAAA_NEXUS_AUTOGUARD` | `1` | Annotate every response with hallucination + drift verdicts |

Free tier endpoints that work without a key: `/health`, `/v1/rng/quantum`, `/v1/agent/card`, `/v1/metrics`.

---

## Documentation

- [docs/MCP_HTTP_SERVER.md](docs/MCP_HTTP_SERVER.md) — **HTTP MCP server** (Streamable HTTP, spec 2025-11-25) — zero-install, 7 core tools, x402 payment, Claude Desktop HTTP config
- [docs/MCP_CLIENTS.md](docs/MCP_CLIENTS.md) — editor-by-editor setup for the stdio package (Claude, Cursor, VS Code, Zed, Windsurf)
- [docs/INTEGRATION.md](docs/INTEGRATION.md) — language-by-language integration guide
- [docs/TOOLS.md](docs/TOOLS.md) — tool index and pricing references for the 140-tool surface
- [docs/LORA_REWARDS.md](docs/LORA_REWARDS.md) — rewards program, leaderboard, prize mechanics
- [docs/TRUSTED_RAG.md](docs/TRUSTED_RAG.md) — RAG cycle, provenance, receipt format

## Examples

- [examples/python_quickstart.py](examples/python_quickstart.py)
- [examples/typescript_quickstart.ts](examples/typescript_quickstart.ts)
- [examples/curl_quickstart.sh](examples/curl_quickstart.sh)
- [examples/lora_flywheel.py](examples/lora_flywheel.py) — earn rewards loop
- [examples/trusted_rag.py](examples/trusted_rag.py) — provenance-gated retrieval
- [examples/agent_self_gate.py](examples/agent_self_gate.py) — agent that gates its own commits
- [examples/mcp_configs/](examples/mcp_configs/) — drop-in configs for every MCP editor

## License

Source package: MIT. Generated OpenAPI schema: CC BY-ND 4.0.

MIT applies to the contents of this repository: the Python package, MCP wiring, examples, and public docs shipped here.
The hosted AAAA-Nexus service, backend implementation, models/proofs, pricing surfaces, and atomadic.tech site content are separate from this repository and may be separately licensed or proprietary.
Atomadic, AAAA-Nexus, and related names, logos, and branding are not granted under MIT.