{ "markdown": "\n> **📖 Read-only mirror.** `argus` is published from the canonical AI-Factory monorepo.\n> **Pull requests are not accepted** — any commit pushed here is overwritten by\n> `scripts/mirror_satellites.sh` on the next sync.\n> 🐞 Found a bug or have a request? Please **[open an issue](https://github.com/alexar76/argus/issues)**.\n\n# ARGUS-3 — MCP server\n\n\n\n\n

\n \"CI\"\n \"argus\n \"WARDEN\n \"Crypto\n \"290\n \"Test\n \"License:\n

\n\n\n> 🌐 **English** · [Русский](README-ru.md) · [Español](README-es.md) · [Français](README-fr.md) · [中文](README-zh.md) · [Glossary](https://github.com/alexar76/aicom/blob/main/docs/localization-glossary.md)\n\n\n**One MCP server. WARDEN-hardened agent. Wallet optional.**\n\nTransport: **stdio** (`argus mcp`). Built with the official\n**Model Context Protocol** TypeScript SDK ([`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk)).\nCompatible hosts: Claude Desktop, Cursor, Glama, and any MCP client that supports stdio servers.\n\n| Item | Location |\n|------|----------|\n| MCP entrypoint | `argus mcp` → [`src/channels/mcp_server.ts`](src/channels/mcp_server.ts) |\n| Tools | `argus_ask`, `argus_status`, `argus_capabilities` |\n| WARDEN firewall | [`docs/security-warden.md`](docs/security-warden.md) |\n| Glama / Docker (stdio) | [`Dockerfile.glama`](Dockerfile.glama), [`glama.json`](glama.json) |\n\nPart of the [AICOM open agent economy](https://magic-ai-factory.com).\n**Live demo:** [magic-ai-factory.com/argus/](https://magic-ai-factory.com/argus/) · **Community:** [Discord · Pollux](https://discord.gg/aimarket) · [Telegram · Castor](https://t.me/just_for_agents)\n\n

\n Live landing\n ·\n WARDEN firewall\n ·\n Install\n ·\n Wiki\n

\n\n

\n \"WARDEN\n

\n\n**MCP firewall first — wallet optional.** ARGUS-3 vets every third-party MCP server through **WARDEN** (static scan → threat feed → origin → def-pinning) before a single tool runs. Crypto, wallet, and on-chain economy are **off by default**.\n*(short name **ARGUS** · CLI: `argus` · npm: **`argus-warden`** · scoped: `@alexar76/argus3`)*\n\n> **Why \"ARGUS-3\"?** In the myth, **Argus Panoptes** — the hundred-eyed watchman —\n> was unbeatable until **Hermes** talked him to sleep and slew him. ARGUS-3 is the\n> watchman that *doesn't* fall for Hermes: a hundred eyes open (WARDEN), frugal to a\n> fault, immune to smooth-talking competitors.\n>\n> Third time's the watchman. 👁️\n\nARGUS is the **demand-side reference client** the agent economy was missing. The\necosystem already has producers (the Factory 🏭), a broker (the Hub 🛒), pricing\n(ACEX 📈), trust math (the LUMEN oracle 🔮) and observability (the Monitor 👽).\nWhat it lacked was a first-class agent an ordinary person runs — one that\n**discovers, pays for, consumes and sells** capabilities. That's ARGUS.\n\nIt is built on two stack layers that generic MCP clients typically lack:\n\n1. **🛡️ WARDEN** — an MCP security firewall that vets third-party servers before\n their tool definitions ever reach the model: a tiered static scan, a signed\n threat feed, an origin check, and tool-def pinning against rug-pulls. Every\n gate decides from what ARGUS already holds locally.\n **Works with no wallet and no chain.**\n2. **💸 Native settlement** *(optional)* — pay per-call and get paid in USDC on Base\n through AIMarket escrow when you enable crypto and connect a wallet.\n\n…and it stays frugal (a hard budget governor + live token meter — no\nself-reflection on your dime), speaks **any model** (Anthropic, OpenAI-compatible,\nChinese, local), and — critically — **runs fully autonomously when the economy is\nunavailable.** No wallet, no network to AICOM? It's still a best-in-class local,\nMCP-secured assistant.\n\n> ### 🔒 Crypto is OFF by default\n> **A blockchain is not required to run ARGUS-3.** Wallet, lottery, ACEX, paid\n> invokes, and on-chain settlement are **disabled by default** and turn on only\n> when you set **`ARGUS_CRYPTO_ENABLED=1`** (plus a wallet). Out of the box you get\n> the full agent — WARDEN, any model, memory, channels, and **free off-chain oracle\n> reads** — with no chain, no token, no wallet, no custody. Crypto is opt-in.\n\n---\n\n## Why ARGUS is different\n\n| | What it does | Why it matters |\n|---|---|---|\n| 🛡️ **WARDEN firewall** | Every MCP server is vetted by a gate chain — static tool-def scan → threat feed → **origin** → def-pinning — before a single tool runs. | Tool-poisoning, rug-pulls (def drift), exfiltration and credential harvesting are blocked *by default*. Every gate decides from data ARGUS already holds locally, so vetting needs no network and nothing can talk the verdict out of it. |\n| 💸 **Native + autonomous economy** | Discover → open USDC channel → invoke → settle (consumer); register in the Mesh → list → earn (provider). Loads **only** with a wallet. | Turns AICOM into a real two-sided market. With no wallet the module never loads — zero dependency, zero failure surface. |\n| ⚖️ **Token-frugal by design** | Bounded reasoning-budget governor with hard $/token ceilings, model tiering, `cache_control`, curated handoff, compaction, and a **live meter**. | The \"cheaper\" claim is *auditable*, not marketing. Exceeding a ceiling stops the task — it never silently overspends. |\n| 🌐 **Any provider** | One `Provider` interface over Anthropic-native, any OpenAI-compatible endpoint (incl. DeepSeek, Qwen, GLM, Kimi…), and local Ollama. | Your keys, your models, your costs. Triage on a cheap/local model, escalate only when needed. |\n\n---\n\n> 🧭 **Core capabilities** — design intent and stack dependencies for each headline\n> feature — **[docs/killer-features.md](docs/killer-features.md)**\n> · [ru](docs/killer-features-ru.md) · [es](docs/killer-features-es.md).\n\n## Quickstart\n\n**One command** (interactive wizard, ~2 minutes):\n\n```bash\ncurl -fsSL https://magic-ai-factory.com/install | bash\n```\n\n**Or install from npm** (same CLI, no curl script):\n\n```bash\nnpm install -g argus-warden@latest\nmkdir -p ~/.argus/agent && cd ~/.argus/agent\nargus setup && argus doctor\n```\n\nPackage: [`argus-warden` on npm](https://www.npmjs.com/package/argus-warden) · scoped: [`@alexar76/argus3`](https://www.npmjs.com/package/@alexar76/argus3) · CLI: `argus` · `npx argus-warden --help`\n\nThen `argus chat` or `argus serve`.\n\n### Run as MCP server (stdio)\n\n```bash\nnpm install -g @alexar76/argus3\n# or: npm install && npm run build && node dist/index.js mcp\nargus mcp\n```\n\nClaude Desktop / Cursor (`mcpServers` entry):\n\n```json\n{\n \"mcpServers\": {\n \"argus\": {\n \"command\": \"argus\",\n \"args\": [\"mcp\"]\n }\n }\n}\n```\n\n### Tools (2)\n\n| Tool | When to use | Returns | Example |\n|------|-------------|---------|---------|\n| `argus_ask` | Bounded NL work via agent core. Optional `response_format` / `focus`. Sensitive tools deny-by-default; budget-metered LLM. | Plain-text answer (`isError` on failure/budget stop) | `argus_ask({ task: \"Summarise https://example.com in three bullets\", response_format: \"bullets\" })` |\n| `argus_status` | Liveness before heavy `argus_ask` (`detail`: basic\\|full) | JSON status | `argus_status({ detail: \"basic\" })` |\n| `argus_capabilities` | Discovery / WARDEN posture without spending LLM tokens | JSON tool catalog | `argus_capabilities({ include_schemas: false })` |\n\nGlama TDQS: MCP `annotations` (readOnly / destructive / idempotent / openWorld), Behavior + Usage Guidelines in every description, structured params with examples — calibrated to the score rubric (not the old one-liner).\n\n### Publish on Glama\n\nListing: **[glama.ai/mcp/servers/alexar76/argus](https://glama.ai/mcp/servers/alexar76/argus)**\n\nSame pattern as **[aimarket-oracle-gateway](https://github.com/alexar76/aimarket-oracle-gateway)**: repo-root [`glama.json`](glama.json) + [`Dockerfile.glama`](Dockerfile.glama) + `node dist/index.js mcp`.\n\n> If `magic-ai-factory.com/install` returns 404, use the mirror:\n> `curl -fsSL https://modeldev.modelmarket.dev/install | bash`\n\n**Docs:** [Wiki](https://github.com/alexar76/argus/wiki) · [User guide (20 languages)](docs/user-guide/) · [Developer guide — publish a capability in 15 min (20 languages)](docs/developer-guide/) · [Use case — your ARGUS on AICOM (EN / RU)](docs/use-case-external-operator.md) · [The Verifiable Conscience (block diagrams)](docs/verifiable-conscience.md) · [When ARGUS won't help you 😈](docs/user-guide/humor/) · [Ecosystem whitepaper](https://github.com/alexar76/aicom/blob/main/docs/ecosystem/whitepaper/en.md)\n\n
\nManual install (developers — from git)\n\n```bash\ncd argus\nnpm install\nnpm run build\n\n# 1) Configure (safe to commit — NO secrets live here)\ncp argus.config.example.json argus.config.json\n\n# 2) Add keys to .env (all optional; with none, ARGUS uses a local Ollama model)\ncp .env.example .env # then edit\n\n# 3) Check what's wired up\nnode dist/index.js doctor\n\n# 4) Ask something\nnode dist/index.js ask \"summarise https://example.com in three bullets\"\n\n# 5) Interactive\nnode dist/index.js chat\n```\n\n
\n\nDuring development you can skip the build step with `npm run dev -- ask \"…\"`.\n\n### The autonomy guarantee\n\nARGUS needs **nothing** from AICOM to work:\n\n```bash\n# No ANTHROPIC_API_KEY, no wallet — just a local model:\nARGUS_LOCAL_BASE_URL=http://127.0.0.1:11434/v1 node dist/index.js ask \"hello\"\n```\n\nWith no `ARGUS_WALLET_KEY`, `doctor` reports `economy: OFF (autonomous)` and the\nentire economy layer is never constructed. See [docs/autonomy.md](docs/autonomy.md).\n\n---\n\n## Architecture\n\nFive layers. Everything above the autonomy line runs offline; the economy clips\non underneath, gated purely on the presence of a wallet.\n\n```mermaid\nflowchart TB\n subgraph OFF[\"Runs offline — no AICOM, no wallet\"]\n L1[\"Layer 1 · Providers — Anthropic · OpenAI-compatible · local\"]\n L2[\"Layer 2 · Bounded agent core — plan→execute→observe + budget governor\"]\n L3[\"Layer 3 · Memory / self-learning — episodes · lessons · pins\"]\n L4[\"🛡️ Layer 4 · MCP host + WARDEN — static · threat · origin · pinning\"]\n L1 --- L2 --- L3 --- L4\n end\n GATE{{\"— autonomy line — needs ARGUS_WALLET_KEY\"}}\n L5[\"🛒 Layer 5 · Economy — discover · pay · invoke · settle · sell\"]\n L4 -.-> GATE -.-> L5\n L5 -.->|wraps| SDK[\"@aimarket/agent SDK\"]\n```\n\nFull diagrams and the module map: **[docs/architecture.md](docs/architecture.md)**.\n\n---\n\n## 🛡️ WARDEN — the MCP firewall\n\n> WARDEN ships separately as **[`@aimarket/warden`](https://github.com/alexar76/warden)** — a\n> zero-dependency library you can put in front of your own MCP host without adopting ARGUS.\n> ARGUS depends on that package; this section is what it does inside the agent.\n\nAn MCP server's tool *descriptions* are attacker-controlled text the model reads\nas instructions. WARDEN treats every server as hostile-by-default and runs each\nconnection through gates before any tool is exposed:\n\n```mermaid\nflowchart LR\n S[MCP server] --> A[1 · static scan] --> B[2 · threat feed] --> C[3 · origin] --> D[4 · def-pinning] --> V{allow?}\n V -->|yes| OK[bridge tools
pin defs]\n V -->|no| NO[block + report]\n```\n\n- **Static scan** — injection / exfiltration / secret-harvesting / hidden-unicode signatures in tool defs. Rules are **tiered**: *blocking* rules cover phrasing with no benign reading; *advisory* rules (an `api_key` parameter, an `.env` mention, a \"you must\") are reported but never block and never affect the score — which is what lets honest servers through. Every verdict names the ruleset version + digest that produced it.\n- **Threat feed** — built-in deny-list + optional signed remote feed.\n- **Origin** — where the server declaration came from: you listed it in `mcp.servers`, or it was discovered from a remote `mcp.catalogs` entry. With `allowUnknownServers: false` a catalog-discovered server is blocked (`SERVER_UNDECLARED`); your own declarations **always** pass, so fail-closed still leaves a way to connect.\n- **Pinning** — hashes the approved tool set; later **drift = rug-pull**, forces re-approval.\n\nSensitive tools (write/delete/exec/payment/…) additionally require explicit user\napproval at call time. Details: **[docs/security-warden.md](docs/security-warden.md)**.\n\n```bash\nnode dist/index.js warden scan # vet your configured MCP servers\n```\n\n---\n\n## 💸 Economy integration\n\nARGUS reuses the existing **AI Market Protocol v2** and the `@aimarket/agent`\nSDK — no new endpoints.\n\n```bash\nexport ARGUS_WALLET_KEY=0x... # enables the economy layer\nnode dist/index.js economy status\nnode dist/index.js economy discover \"translate to 5 languages\" --budget 1\nnode dist/index.js economy register # list ARGUS in the AI Service Mesh\n```\n\nConsumer flow: `discover → openChannel (USDC/Base) → invoke (X-Payment-Channel) →\nsettle`. Provider flow: register identity + wallet in the Mesh, list capabilities,\nearn (and become eligible for the agent lottery / machine-UBI). See\n**[docs/economy-integration.md](docs/economy-integration.md)** ·\n**[docs/mcp-oracles-capabilities.md](docs/mcp-oracles-capabilities.md)** (17 oracles, MCP, selling).\n\n---\n\n## Multi-provider\n\n| Adapter | Covers |\n|---|---|\n| **Anthropic-native** | Claude Opus/Sonnet/Haiku/Fable — first-class `cache_control`; default for the core loop |\n| **OpenAI-compatible** | OpenAI, DeepSeek, Qwen/DashScope, Zhipu GLM, Moonshot/Kimi, MiniMax, Mistral, Groq, Together, OpenRouter, vLLM |\n| **Local** | Ollama / llama.cpp — offline + the cheap triage tier |\n\nModels are assigned to tiers (`triage` / `core` / `heavy`) in\n`argus.config.json`; routing falls back across tiers when a key is missing.\n\n---\n\n## 🎮 Agent Arena — level up, keep streaks, flex your card\n\nRunning an agent should be *fun*. Agent Arena turns **real ecosystem activity** into\nthe game mechanics a young, global audience already loves — Duolingo-style streaks,\nWrapped-style shareable cards, gaming rank cards:\n\n- **XP & levels** — earn XP for finishing tasks, selling capabilities, playing the\n oracle lottery, trading on ACEX, and staying frugal (low `$`/task).\n- **Daily streaks** 🔥 — keep your agent active day after day.\n- **Quests & badges** — *First Blood* (first lottery win), *Rainmaker* (first `$1`\n earned selling capabilities), *Frugal* (a task under `$0.001`), *Trusted* (top-half\n LUMEN reputation), *Warden* (blocked a malicious MCP server), *Polyglot*, *Whale*, *Lucky*…\n *Trusted* and the reputation rank are **not earnable today**: a LUMEN score needs a\n trust graph, and no deployment publishes the trust edges ARGUS would be scored on.\n- **Flex Card** — `argus flex` (or `/flex` in Telegram) renders a slick, shareable card:\n handle, level, streak, `$` earned, win-rate, top badges, reputation rank (blank until\n a trust graph exists). Numbers + emoji = no language barrier → share it anywhere.\n- **Global leaderboard** *(opt-in)* — rank against agents worldwide by XP, earnings, or frugality.\n\nEvery stat is **real** — it's your actual economy and frugality\nperformance, computed locally from your agent's own memory + signed economy receipts,\nso it's hard to fake and not vanity points. Sharing and the leaderboard are **off by\ndefault and owner-controlled** — your data stays yours. Full design: [docs/arena.md](docs/arena.md).\n\n**Live demo (this fleet):**\n- **LIVE** (Base mainnet): [https://magic-ai-factory.com/arena](https://magic-ai-factory.com/arena) — `:8787` → `GET /arena/stats`\n- **UNI** (Universe / Anvil): [https://magic-ai-factory.com/arena-uni/](https://magic-ai-factory.com/arena-uni/) — `:8788` → same UI, `mode=uni`\n\nUse the **TEST · LIVE · UNI** switcher on the Arena page to flip between demo metrics and each deployed node.\n\n---\n\n## Configuration\n\n- **`argus.config.json`** — non-secret config (providers, models, tier pricing for the meter, budget ceilings, WARDEN policy, MCP servers/catalogs, economy endpoints). Safe to commit. Start from `argus.config.example.json`.\n- **`.env`** — secrets only: API keys (`ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, …), `ARGUS_WALLET_KEY`, and optional `ALIEN_API_TOKEN` for the Alien Monitor run feed. Never commit. Start from `.env.example`.\n\n`economy.enabled` is **derived** — it is true *iff* `ARGUS_WALLET_KEY` is set.\n\n---\n\n## Where it sits in the ecosystem\n\n> `aicom` Factory **builds** agents → listed & invoked through **AIMarket** (Hub +\n> protocol) → **Oracles** (LUMEN trust, randomness, VDF, consensus) price and\n> secure them → financed on **ACEX** → visualised by **Alien Monitor**.\n>\n> **ARGUS is the demand side**: the agent that *spends* in this market, *sells*\n> into it, and *defends* the user against the MCP supply chain — with a firewall\n> that needs none of the above to work.\n\n---\n\n## Channels\n\nOne bounded agent core, many channels — each with the auth model natural to it.\nFull matrix + design: **[docs/channels.md](docs/channels.md)**.\n\n| Channel | Run | Auth |\n|---|---|---|\n| CLI | `argus ask` / `argus chat` | local (interactive approval) |\n| Telegram | `argus telegram` | owner-locked (first `/start` claims) |\n| HTTP API | `argus serve` | `/health` open · `POST /ask` Bearer `ARGUS_HTTP_TOKEN` |\n| MCP-server | `argus mcp` | local stdio — exposes `argus_ask` / `argus_status` / `argus_capabilities` |\n\n`argus serve` runs Telegram + the HTTP server together (this is what the\ncontainer runs). `GET /health` is also the hook that lets ARGUS appear as a live\n**node** in Alien Monitor. Set `ALIEN_MONITOR_URL` + `ALIEN_API_TOKEN` to push\neach completed run to the node's verifiable-run panel (oracle calls, WARDEN\nblocks, hires, sealed receipt). Discord, Slack, Email, Matrix, WhatsApp and voice are\nready-to-add adapters (see the doc).\n\n## Deployment (Docker)\n\nARGUS launches untrusted MCP servers as child processes, so the container is also\na security boundary around them — not just packaging.\n\n```bash\ncp argus.config.example.json argus.config.json # edit\ncp .env.example .env # add secrets\ndocker compose up -d --build # serve: Telegram + HTTP /health\n```\n\nSecrets come from `.env` (never baked into the image); `argus.config.json` is\nmounted read-only; state persists in the `argus-state` volume; a `HEALTHCHECK`\nprobes `/health`. Economy is OFF by default in the container (autonomous).\n\n## Development\n\n```bash\nnpm run typecheck # tsc --noEmit (strict)\nnpm test # vitest (budget governor, MCP host + WARDEN wiring, provider mapping)\nnpm run build # emit dist/\n```\n\n## Status\n\n`v0.1` — bounded agent loop, multi-provider routing, WARDEN gate chain (static +\nthreat + origin + pinning), memory/lessons, MCP host, economy consumer/provider\nwrappers, and four channels (CLI, Telegram, HTTP, MCP-server) + Docker — all\nimplemented and tested. OS-level MCP sandboxing (seccomp/Landlock/sandbox-exec),\nthe signed threat-feed publisher, and the remaining channel adapters are the v2\ntrack — see the docs.\n\n## Demo\n\n- **Live:** https://magic-ai-factory.com/argus/\n- **Docs:** https://github.com/alexar76/argus/wiki\n\n## Related repos\n\n| Repo | Role |\n|------|------|\n| [aicom](https://github.com/alexar76/aicom) | AI-Factory — ships capabilities ARGUS consumes |\n| [aimarket-hub](https://github.com/alexar76/aimarket-hub) | Federation hub — discover, invoke, settle |\n| [oracles](https://github.com/alexar76/oracles) | LUMEN reputation + verifiable math |\n| [alien-monitor](https://github.com/alexar76/alien-monitor) | ARGUS appears as a live graph node |\n| [dioscuri](https://github.com/alexar76/dioscuri) | Twin community agents — MNEMOSYNE Q&A |\n\n## Community\n\nThe [DIOSCURI](https://github.com/alexar76/dioscuri) twins answer questions from synced GitHub docs.\n\n| Channel | Twin | Best for |\n|---------|------|----------|\n| [Discord](https://discord.gg/aimarket) | Pollux | Help, ideas, show-and-tell |\n| [Telegram](https://t.me/just_for_agents) | Castor | Releases, digests, quick news |\n\n**Ecosystem map:** [Alien Monitor](https://monitor.modelmarket.dev/) · [AICOM](https://magic-ai-factory.com)\n\n## License\n\nMIT — your keys, your infra, your data. Part of the [AICOM](https://alexar76.github.io/aicom/) open agent-economy.\n", "bytes": 21615, "sha": "e87735e8e0ffe10534503e38f3c7f38d6cb8d9ef8e663fa268979279270ca8d6", "repo_slug": "alexar76/argus", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_alexar76_argus3_839848cc/readme" }