Skip to main content
Glama

YodMCP — Agenten-Betriebssystem

CI Version YodMCP MCP server Python License MCP

YodMCP ist ein produktionsorientierter Agenten-Betriebssystem-Kernel auf MCP: Multi-Graph-Speicher, Tasks, Skills, A2A, Attestierung (Software / simuliertes TEE), OpenTelemetry und planbasierte Monetarisierung.

Dieses README ist so geschrieben, dass ein leitender Ingenieur mit nur dieser Datei + dem Quellbaum jede Schnittstelle installieren, bereitstellen, Funktionen ausprobieren und Ende-zu-Ende verifizieren kann.

FOUNDRY-Mapping

FOUNDRY (vom Host verwaltetes Vertrauen und Speicher für langfristige Agentenschwärme) trennt die Erzeugung nicht vertrauenswürdiger Vorschläge von der hostseitigen Verifikation und dem Register etablierter Fakten.

YodMCP ist dieses Register in Produktion: Agents rufen memory_write auf; die Übernahme in den semantischen Speicher ist kontrolliert; der Host besitzt den Evaluator. Ausführliche Notiz: docs/FOUNDRY.md.

First Dollar

Zuerst messen. Platz nehmen, wenn die Schleife hält.

Einheit

Stripe

x402

OpenGOS Search $0.40

Kaufen

GET /v1/search

OpenGOS Draft $2.50

Kaufen

GET /v1/draft

Agentic OS Cycle $0.75

Kaufen

GET /v1/cycle

YodMCP Pro $49/mo

Abonnieren

USDC

x402-Schiene: x402-cloudflare-starter. Desk-Sync: https://anamized.grok.me

Related MCP server: Agentic Control Framework (ACF)

Paket-Schnittstellen

| Schnittstelle | Befehl | Standard | Zweck | |---------|---------|---------| | MCP | yodmcp | stdio | Lokale MCP-Clients (Cursor, Claude Desktop, usw.) | | MCP HTTP | yodmcp --http --port 8000 | :8000/mcp | Remote-/Streamable-HTTP-MCP | | API | yodmcp-api --port 8080 | :8080 | REST-Health, Speicher, Audit, Skills, Abrechnung | | A2A | yodmcp-a2a --port 9000 | :9000 | Agent Card, Nachrichten, Tasks | | SDK | from yodmcp.sdk import YodClient | HTTP-Client | Schlanker Client für die API | | Skills | skills:// + skills/*/SKILL.md | automatisch geladen | Agent Skills als MCP-Ressourcen | | Verify | pytest + scripts/verify_e2e.py | CI | Substrate-, durable- und TEE-Modi |

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

Variable

Standard

Bedeutung

YODMCP_MEMORY_BACKEND

memory

memory | sqlite | durable

YODMCP_MEMORY_DB

./data/yodmcp_memory.db

SQLite-Pfad bei durable

YODMCP_ATTEST_MODE

software

software | simulated_tee | nitro | sgx

YODMCP_PLAN

free

free | pro | enterprise

YODMCP_TENANT_ID

default

Soft-Quota-Mandantenschlüssel

YODMCP_SKILLS_DIR

(auto)

Überschreibt das Skills-Wurzelverzeichnis

STRIPE_SECRET_KEY

unset

Aktiviert Live-Checkout-Sitzungen

TEE-Ehrlichkeit: nitro / sgx sind Provider-Hooks; ohne echte TEE-Bibliotheken fallen sie auf simulierte Ansprüche zurück. Bevorzugen Sie für die lokale Verifizierung 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"
      }
    }
  }
}

Falls yodmcp nicht im PATH ist, verwenden Sie die Modulform:

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

Claude Desktop – gleiche Form unter mcpServers in claude_desktop_config.json.

Streamable HTTP MCP (Remot-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

Einzel-API-Container:

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

Ende-zu-Ende-Verifizierung (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; das Skript gibt ALL E2E CHECKS PASSED aus.

API-Smoke-Test (bei 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)

Tool

Beschreibung

memory_write

Einen Speicherknoten einfügen (Fakten/Entscheidungen). Nicht für Pläne (plan_cache_put).

memory_read

Knoten nach Ähnlichkeit oder item_id abrufen. Nicht für Pläne (plan_cache_get).

memory_delete

Einen Knoten + zugehörige Kanten endgültig löschen. Idempotent, falls nicht vorhanden.

memory_consolidate

Importanz ≥ 0,8 in semantische Zusammenfassungen überführen. Löscht keine Quellen.

memory_stats

Anzahl von Knoten/Kanten/Entitäten. Kein Inhalt (memory_read).

tasks_create

Ein dauerhaftes Handle für eine anstehende Task erstellen.

tasks_get

Ein Handle anhand der ID abrufen.

tasks_list

Neueste Handles auflisten, optionaler Statusfilter.

tasks_update

Status/Fortschritt/Ergebnis patchen. Nicht abbrechen (tasks_cancel).

tasks_cancel

Ein Handle als abgebrochen markieren (nur Kernel-Zustand).

tasks_stats

Anzahl nach Status. Keine Auflistung (tasks_list).

skills_list

Agent Skills + skills://-URIs auflisten (Inhalte sind Ressourcen).

a2a_card

A2A-Agent-Card-JSON. Nicht der MCP-Katalog (discover_capabilities).

plan_cache_get / plan_cache_put / plan_cache_delete

Semantische Planvorlagen. Keine Speicherfakten.

cache_stats

Summen für Einträge/Treffer des prozessinternen Caches.

attestation_recent

TRACE-artige Herkunftsansprüche. Nicht der Audit-Trail (audit_recent).

audit_recent

Ereignisse des Decision-System-of-Record für Policy/Tool.

discover_capabilities

MCP-Tools + geladene Skills auflisten.

echo

Liveness-Probe (message wird zurückgegeben + Version).

Ressourcen:

  • skills://{name} — Skill-Markdown-Inhalt

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

Skills

Eingebaute Skills sind immer registriert. Disk-Skills unter skills/*/SKILL.md werden automatisch geladen (Überschreibung über YODMCP_SKILLS_DIR). Das Repo enthält:

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

  • Zusätzlich eingebaut: long-horizon-planning

Monetarisierung

Plan

$/mo

Tool-Aufrufe/Tag

Dauerhaft

TEE

Kostenlos

0

500

—

—

Pro

49

50k

ja

simuliert

Enterprise

499

unbegrenzt

ja

Nitro/SGX-Hooks

  • Soft-Quotas über das Tool-Gate; Upgrade-Hinweise bei Erschöpfung

  • Live-Stripe-Checkout, wenn STRIPE_SECRET_KEY gesetzt ist; andernfalls gibt der Checkout status: payment_link zurück.

Non-Custodial USDC (bevorzugt für Agenten)

Netzwerk

Adresse

Base

0xD3d0E9eDAe3Ac7bb199a8EAA761BdA423b878438

Ethereum

0xD3d0E9eDAe3Ac7bb199a8EAA761BdA423b878438

Solana

ETQwWf19axArsY493UfC6bxe2BmEzmzvCb58PPnC38A

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
docs/FOUNDRY.md
docs/TDQS.md

Bekannte Einschränkungen (lesen, bevor Sie Produktionsreife beanspruchen)

  1. Plan-Cache verwendet schlanke Embeddings; die standardmäßige Ähnlichkeitsschwelle beträgt 0,68 (keine Produktions-Vektorsuche).

  2. TEE Nitro/SGX sind Hooks mit simuliertem Fallback, sofern Sie keine echten Provider anbinden.

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

  4. Quotas sind weich (prozessinterner Zähler); kein verteiltes Abrechnungsbuch.

  5. Prozesse teilen keinen In-Memory-Zustand; verwenden Sie für die Dauerhaftigkeit über mehrere Prozesse hinweg das sqlite-Backend + ein gemeinsames Volume.

Lizenz

Apache-2.0 · CONTRIBUTING · CHANGELOG · ARCHITECTURE · FOUNDRY · TDQS · AGENTS.md

Available Tools

21 tools
a2a_cardGet A2A Agent CardA
Read-onlyIdempotent

Return this process's A2A Agent Card JSON (name, skills, endpoints) for agent-to-agent interop. Use when another agent needs the card. Do not use to list MCP tools or skills — that is discover_capabilities or skills_list. Read-only, no parameters, no side effects. Auth: tool policy gate.

Inputs: no named parameters. Returns: object

attestation_recentList recent attestation claimsA
Read-onlyIdempotent

Return recent attestation claims issued by this kernel (TRACE-style provenance: tool, allow/deny, risk tier, evidence mode). Use to verify a prior sandbox/TEE decision. Do not use for the policy/audit trail — that is audit_recent. This tool does not issue new claims. Read-only. limit is max claims, newest first (default 10). Auth: gate.

Inputs: limit. Returns: object

audit_recentList recent audit eventsA
Read-onlyIdempotent

Return the newest Decision-System-of-Record audit events (tool calls, policy allow/deny, risk tier, outcome), newest first. Use to inspect what the kernel just decided. Do not use for attestation evidence (attestation_recent) or cache metrics (cache_stats). Read-only. limit caps the list (default 20). Auth: tool policy gate.

Inputs: limit. Returns: object

cache_statsCache statisticsA
Read-onlyIdempotent

Return entry counts and hit totals for the in-process result/plan cache. Use for diagnostics. Do not use to read a plan (plan_cache_get) or memory (memory_read). Read-only, idempotent, no parameters. Auth: tool policy gate.

Inputs: no named parameters. Returns: object

discover_capabilitiesDiscover tools and skillsA
Read-onlyIdempotent

List this kernel's MCP tools and loaded Agent Skills, optionally filtered by a substring query. Use at session start or when unsure which tool to call. Do not use to fetch the A2A interoperability card — that is a2a_card — or skill bodies (read skills:// resources after skills_list). Read-only and idempotent. Auth: gate.

Inputs: query. Returns: object

echoEcho a connectivity probeA
Read-onlyIdempotent

Return the provided message plus server name/version to confirm the MCP session is alive. Use as a liveness probe. Do not use to discover tools (discover_capabilities) or to persist state. Read-only, idempotent, no network I/O, no quota side effects beyond the standard tool gate. message defaults to 'ping'.

Inputs: message. Returns: object

memory_consolidateConsolidate episodic memoryA

Promote high-importance nodes (importance >= 0.8) from from_level into new semantic summary nodes. Use after a burst of memory_write calls to compress working memory. Do not use as a delete — source nodes remain. Mutating, not idempotent (re-running creates additional summaries). Auth: tool policy gate.

Inputs: from_level. Returns: object

memory_deleteDelete a memory nodeA
DestructiveIdempotent

Permanently delete one memory node and its incident edges/entity index rows. Use when a fact must be forgotten. Do not use to hide a node while keeping it — there is no soft-delete. Destructive and idempotent: missing ids return deleted=false. Prefer memory_read first to confirm the id. Auth: policy gate; may require HITL.

Inputs: item_id (required). Returns: object

memory_readRead memory nodesA
Read-onlyIdempotent

Retrieve memory nodes by embedding similarity and/or exact item_id, optionally filtered by level, agent, session, or graph kind. Use to recall stored facts. Do not use for reusable plan templates — that is plan_cache_get. Read-only and idempotent. Returns scored items plus neighbor ids. Auth: tool policy gate.

Inputs: graph, level, limit, query, +3 more. Returns: object

memory_statsMemory graph statisticsA
Read-onlyIdempotent

Return node counts by level plus edge and entity-index sizes for the memory store. Use for capacity/health checks. Do not use to read node content — that is memory_read. Read-only, idempotent, no parameters. Auth: tool policy gate.

Inputs: no named parameters. Returns: object

memory_writeWrite a memory nodeA

Insert one node into the multi-graph memory store (episodic/semantic/procedural) and optionally add causal or entity edges. Use to remember facts, decisions, or session state the host should own. Do not use for reusable task plans — that is plan_cache_put. Mutating and not idempotent: each call creates a new item_id. Gated by plan quota. Nodes with importance >= 0.8 are what memory_consolidate later promotes. Auth: tool policy gate; no network I/O.

Inputs: content (required), level, agent_id, entities, +4 more. Returns: object

plan_cache_deleteDelete a cached planA
DestructiveIdempotent

Delete the exact plan-cache entry for task_description. Use to drop a stale template. Does not delete memory nodes (that is memory_delete). Destructive and idempotent: missing keys return deleted=false. Auth: tool policy gate.

Inputs: task_description (required). Returns: object

plan_cache_getLookup a cached planA
Read-onlyIdempotent

Semantic lookup of a previously stored plan template keyed by task_description. Use to reuse a multi-step plan. Do not use to recall facts from memory (memory_read) or to write a plan (plan_cache_put). Read-only. Returns found, similarity score, and plan. Default similarity threshold is 0.68. Auth: tool policy gate.

Inputs: task_description (required). Returns: object

plan_cache_putStore a plan templateA

Store a structured plan template keyed by task_description for later semantic reuse. Use after you have a working plan. Do not use for episodic facts (memory_write). Mutating; same task_description overwrites the exact key. Auth: tool policy gate.

Inputs: plan (required), task_description (required). Returns: object

skills_listList Agent SkillsA
Read-onlyIdempotent

List loaded Agent Skills with name, skills:// URI, description, and tags. Use to find skill resources to read next. Does not return skill markdown bodies — fetch those via the skills://{name} resource. Do not use for the A2A card (a2a_card). Read-only. Auth: tool policy gate.

Inputs: no named parameters. Returns: object

tasks_cancelCancel a taskA
DestructiveIdempotent

Mark a task cancelled. Use to stop polling a handle you no longer need. Does not kill an external worker process — it only updates kernel state. Destructive relative to the handle, idempotent if already cancelled. Missing ids return cancelled=false. Prefer tasks_get first. Auth: tool policy gate.

Inputs: task_id (required). Returns: object

tasks_createCreate a durable taskA

Create a durable async task handle (pending) that survives process restart when the sqlite tasks backend is enabled. Use to start long-running work you will poll with tasks_get or list with tasks_list. Do not use to store facts (memory_write) or plans (plan_cache_put). Mutating, not idempotent. ttl_ms controls handle expiry hint. Auth: tool policy gate + plan quota.

Inputs: ttl_ms, metadata, tool_name. Returns: object

tasks_getGet a task by idA
Read-onlyIdempotent

Fetch one task handle by task_id (status, progress, result, error). Use to poll after tasks_create. Do not use for aggregate counts — that is tasks_stats — or to list many tasks (tasks_list). Read-only and idempotent. Missing ids return task_not_found. Auth: tool policy gate.

Inputs: task_id (required). Returns: object

tasks_listList recent tasksA
Read-onlyIdempotent

List task handles, newest updated first, optionally filtered by status. Use to recover ids after restart. Do not use to poll a known id (tasks_get) or to mutate state. Read-only and idempotent. Auth: tool policy gate.

Inputs: limit, status. Returns: object

tasks_statsTask store statisticsA
Read-onlyIdempotent

Return total task count and counts by status for the task store. Use for dashboards. Do not use to read a specific handle (tasks_get) or to list handles (tasks_list). Read-only, idempotent, no parameters. Auth: tool policy gate.

Inputs: no named parameters. Returns: object

tasks_updateUpdate a taskA

Patch status, progress, message, result, or error on an existing task. Use while a worker is running. Do not use to cancel — that is tasks_cancel — or to create a new handle (tasks_create). Mutating; last write wins. Missing ids return task_not_found. Auth: tool policy gate.

Inputs: task_id (required), error, result, status, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 21 tools

    Disambiguation4/5

    The tool set is organized into clear subsystems and each description includes explicit 'do not use' cross-references. However, audit_recent and attestation_recent describe very similar recent-decision records, and discover_capabilities vs skills_list vs a2a_card are all discovery-flavored, so a couple of boundaries are easy to blur.

    Naming Consistency3/5

    Most memory_, tasks_, plan_cache_, and skills_ tools follow a readable resource_operation pattern. But discover_capabilities, audit_recent, attestation_recent, a2a_card, and echo break that pattern, resulting in a mixed though still understandable naming convention.

    Tool Count3/5

    With 21 tools, the surface is at the high end and feels heavy for a single server, especially with multiple stats and discovery variants. The broad subsystem coverage justifies most tools, but the overall count is borderline excessive.

    Completeness4/5

    The major subsystems have solid lifecycle coverage: memory has write/read/delete/consolidate, plan cache has get/put/delete, and tasks have create/read/list/update/cancel. Minor gaps remain, such as no hard-delete for tasks and no direct update for memory nodes, but agents can work around them.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers