YodMCP — Agent Operating System

YodMCP ist ein produktionsorientierter Agent Operating System-Kernel auf MCP: Multi-Graph-Speicher, Tasks, Skills, A2A, Attestierung (Software / simulierter TEE), OpenTelemetry und planbasierte Monetarisierung.

Diese README ist so geschrieben, dass ein Senior‑Engineer mit nur dieser Datei + dem Quellbaum das System installieren, alle Oberflächen bereitstellen, Funktionen testen und End-to-End verifizieren kann.

Paketoberflächen

Related MCP server: Agentic Control Framework (ACF)

Anforderungen

• Python 3.11 oder 3.12 (3.10+ deklariert; CI deckt 3.11/3.12 ab)

• Optional: Docker für Multi‑Service‑Compose

Installation

git clone https://github.com/ANAMIZED/YodMCP.git
cd YodMCP
python -m venv .venv && source .venv/bin/activate   # recommended
pip install -e ".[dev]"

Umgebungsstandards kopieren:

cp .env.example .env

TEE‑Ehrlichkeit: nitro / sgx sind Provider‑Hooks; ohne echte TEE‑Bibliotheken fallen sie auf simulierte Claims zurück. Für lokale Tests bevorzuge software oder simulated_tee.

Schnellstart (lokal)

# 1) MCP over stdio (attach from an MCP client)
yodmcp

# 2) REST API
yodmcp-api --port 8080
# curl http://127.0.0.1:8080/health

# 3) A2A
yodmcp-a2a --port 9000
# curl http://127.0.0.1:9000/a2a/card

MCP‑Client‑Konfiguration (stdio)

Cursor — Projekt‑.cursor/mcp.json oder globale MCP‑Einstellungen:

{
  "mcpServers": {
    "yodmcp": {
      "command": "yodmcp",
      "args": [],
      "env": {
        "YODMCP_MEMORY_BACKEND": "memory",
        "YODMCP_PLAN": "free",
        "YODMCP_ATTEST_MODE": "software"
      }
    }
  }
}

Wenn yodmcp nicht im PATH ist, verwende die Modulform:

{
  "mcpServers": {
    "yodmcp": {
      "command": "python",
      "args": ["-m", "yodmcp"],
      "cwd": "/absolute/path/to/YodMCP",
      "env": {
        "PYTHONPATH": "src",
        "YODMCP_MEMORY_BACKEND": "memory"
      }
    }
  }
}

Claude Desktop — gleiche Struktur unter mcpServers in claude_desktop_config.json.

Streamable HTTP MCP (Remote‑Clients, die URL‑Transport unterstützen):

yodmcp --http --host 0.0.0.0 --port 8000
# endpoint: http://127.0.0.1:8000/mcp

Docker

docker compose up --build
# API  :8080  A2A :9000  MCP HTTP :8000

Einzelner API‑Container:

docker build -t yodmcp .
docker run --rm -p 8080:8080 -e YODMCP_PLAN=free yodmcp

End-to-End verifizieren (keine externen Konten erforderlich)

# Unit + integration
YODMCP_MEMORY_BACKEND=memory YODMCP_ATTEST_MODE=software \
  PYTHONPATH=src pytest tests/ -v

# Durable SQLite + simulated TEE
YODMCP_MEMORY_BACKEND=sqlite YODMCP_MEMORY_DB=/tmp/yodmcp.db \
  YODMCP_ATTEST_MODE=simulated_tee \
  PYTHONPATH=src pytest tests/ -v

# Exhaustive substrate script
PYTHONPATH=src python scripts/verify_e2e.py

Erwartet: alle Tests grün; Skript gibt ALL E2E CHECKS PASSED aus.

API‑Smoke (mit laufendem yodmcp-api):

curl -s http://127.0.0.1:8080/health
curl -s http://127.0.0.1:8080/api/skills
curl -s http://127.0.0.1:8080/api/billing/plans
curl -s http://127.0.0.1:8080/api/billing/status

SDK:

python examples/sdk_quickstart.py   # requires API on :8080

MCP‑Tools (Katalog)

Ressourcen:

• skills://{name} — Skill‑Markdown‑Body

• yodmcp://agent-card — Agent‑Card‑JSON

Skills

Integrierte Skills sind immer registriert. Festplatten‑Skills unter skills/*/SKILL.md werden automatisch geladen (Überschreibung über YODMCP_SKILLS_DIR). Das Repository enthält:

• memory-hygiene, safe-tool-use, funding-usdc, repo-bootstrap

• Plus integrierten long-horizon-planning

Monetarisierung

• Soft‑Kontingente über Tool‑Gate; Upgrade‑Meldung bei Erschöpfung

• Live‑Stripe‑Checkout bei gesetztem STRIPE_SECRET_KEY; sonst gibt Checkout status: payment_link zurück

Nicht‑verwahrender USDC (bevorzugt für Agenten)

Kanonisch: funding/addresses.json

Projektstruktur

src/yodmcp/          # package (src-layout)
  core/              # server, substrate, context
  memory/            # in-memory + durable SQLite multi-graph
  tools/             # MCP tool registration + gate
  tasks/ skills/ cache/ security/ observability/ monetization/
  api/ a2a/ sdk/
skills/*/SKILL.md    # portable Agent Skills (loaded at runtime)
scripts/verify_e2e.py
tests/
docs/ARCHITECTURE.md

Bekannte Einschränkungen (vor Produktionseinsatz lesen)

1. Plan‑Cache verwendet leichte Embeddings; standardmäßige Ähnlichkeitsschwelle ist 0,68 (keine produktionsreife Vektorsuche).

2. TEE: Nitro/SGX sind Hooks mit simuliertem Fallback, es sei denn, Sie binden echte Provider ein.

3. Frontend src/yodmcp/frontend/dashboard.py verwendet noch das alte core.runtime und ist nicht die primäre Steuerungsebene – verwenden Sie yodmcp-api + MCP‑Tools.

4. Kontingente sind soft (In‑Process‑Meter); kein verteiltes Abrechnungs‑Ledger.

5. Prozesse teilen keinen gemeinsamen In‑Memory‑Zustand; verwenden Sie sqlite‑Backend + gemeinsames Volume für Multi‑Prozess‑Dauerhaftigkeit.

Lizenz

Apache-2.0 · CONTRIBUTING · CHANGELOG · ARCHITEKTUR · AGENTS.md