MCP Agent Health Reporter

io.github.aos-standard由 GitHub 帳號 aos-standard 發布v0.3.1更新於 Oct 24, 2026

Advisory AOS agent health scan before deployment (manifest, services, immune loop, evidence).

已驗證STDIO僅桌面開發者工具安全與監控

概覽

AI 產生的概覽

掃描本機 AI 代理目錄，回傳 AOS 就緒評分、分項分數與稽核摘要，供部署前檢查。

可以做什麼
提供兩個工具：aos_agent_health_scan 對目標目錄中的單一代理評分，回傳 aos_score、certified 旗標、各分項分數（清單宣告、systemd 執行環境、免疫迴圈、實體證據）以及先例中介資料；aos_agent_health_audit 掃描整個目錄，回傳 total_tools、avg_score 等彙總與每個代理的報告。它是建議性工具，用來找出本機正常但部署後失效的代理。
適用情境
當你維護一個代理定義目錄，需要在部署前做就緒檢查，或對多個代理做批次稽核時使用。適合本機開發流程中希望取得評分報告而非人工檢查的情境。
執行需求
以 PyPI 套件 mcp-agent-health 透過 stdio 在本機執行，可用 uvx 啟動或 pip 安裝，需要 Python。選用環境變數：AOS_HEALTH_TARGET_DIR 設定預設掃描根目錄（回退為目前工作目錄），AOS_HEALTH_MCP_LOG 設定 JSONL 日誌路徑，AOS_HEALTH_MCP_TRANSPORT 選擇傳輸方式（預設 stdio）。未宣告帳號或 API 金鑰。
安裝前請注意
掃描會讀取你指定的目錄，請謹慎選擇目標路徑。它會寫入 JSONL 呼叫日誌，預設位於使用者家目錄下的 ~/.aos_health_mcp/calls.jsonl，可用 AOS_HEALTH_MCP_LOG 重新導向。評分僅供參考，certified 旗標並非權威核准。README 說明此伺服器已從 aos-agent-health-mcp 更名，現有 MCP 設定需要更新。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 MCP Agent Health Reporter，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

MCP Agent Health Reporter

Renamed (2026-07): Formerly aos-agent-health-mcp / CLI aos-health-mcp. Migrate with pip install mcp-agent-health==0.3.1 and update your MCP config command to mcp-agent-health.

MCP server that validates agent health under AOS discipline and reports readiness scores. Use it to catch agents that silently fail in production — healthy locally, broken when deployed.

Install

bash
pip install mcp-agent-health==0.3.1# or editable from source:# pip install -e ./packaging

MCP Client Configuration

Add to your mcp.json (Cursor / Claude Desktop):

json
{  "mcpServers": {    "mcp-agent-health": {      "command": "mcp-agent-health",      "args": [],      "env": {        "AOS_HEALTH_TARGET_DIR": "/path/to/your/agents"      }    }  }}

Tool: aos_agent_health_scan

Request (non-default args — real signal):

json
{  "tool_id": "1066",  "target_dir": "/home/builder/my-agents",  "mock": false}

Response:

json
{  "status": "success",  "aos_score": 62.5,  "certified": false,  "tool_id": "1066",  "target_dir": "/home/builder/my-agents",  "target_path": "/home/builder/my-agents/1066_AOS_Agent_Health_Reporter",  "sections": {    "manifest_declared": 12.5,    "systemd_runtime": 0.0,    "immune_loop": 0.0,    "physical_evidence": 25.0  },  "precedent_meta": {    "precedent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",    "tool_id": "1066",    "created_date": "2026-06-14T12:00:00+00:00",    "source_signal_hash": "a1b2c3d4"  },  "scanned_at": "2026-06-14T12:00:00+00:00"}

Tool: aos_agent_health_audit

Request:

json
{  "target_dir": "/home/builder/my-agents",  "mock": false}

Response (excerpt):

json
{  "status": "success",  "total_tools": 3,  "avg_score": 54.2,  "target_dir": "/home/builder/my-agents",  "reports": []}

Self-Test (G1 evidence)

bash
python3 packaging/scripts/smoke_self_call.py# Appends one line to ~/.aos_health_mcp/calls.jsonl

Canonical source sync (TASK B)

正本: core/ahr_scan_pure.py（直接編集はこちらのみ）
配布コピー: packaging/aos_health_mcp/_scan_pure.py（直接編集禁止 — 同期スクリプト経由）

bash
python3 packaging/scripts/sync_scan_pure.py          # copy + verifypython3 packaging/scripts/sync_scan_pure.py --check-only  # CI gate

一致検証: pytest tests/test_logic.py::TestAosAgentHealthReporter::test_scan_pure_canonical_sync

G2 clean install (mock=false)

bash
python3 -m venv /tmp/aos-g2-venv/tmp/aos-g2-venv/bin/pip install -e packaging//tmp/aos-g2-venv/bin/python packaging/scripts/g2_clean_install_smoke.py

Environment Variables

VariableDescription
AOS_HEALTH_TARGET_DIRDefault scan root (fallback: cwd)
AOS_HEALTH_MCP_LOGJSONL log path (default: ~/.aos_health_mcp/calls.jsonl)
AOS_HEALTH_MCP_TRANSPORTstdio (default)

來源：packaging/README.md，提交 cec614f

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v0.3.1最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分