Skip to main content
Glama

YodMCP — Sistema Operativo para Agentes

CI Version YodMCP MCP server Python License MCP

YodMCP es un kernel de sistema operativo para agentes orientado a producción sobre MCP: memoria multigrafo, Tasks, Skills, A2A, atestación (software / TEE simulado), OpenTelemetry y monetización basada en planes.

Este README está redactado para que un ingeniero sénior con solo este archivo + el árbol de fuentes pueda instalar, desplegar cada interfaz, ejercitar las funciones y verificar de extremo a extremo.

Mapeo de FOUNDRY

FOUNDRY (confianza y memoria propiedad del host para enjambres de agentes de horizonte largo) separa la generación de propuestas no confiables de la verificación propiedad del host y el registro de hechos establecidos.

YodMCP es ese registro en producción: los agentes llaman a memory_write; la promoción a memoria semántica está sujeta a control; el host es el propietario del evaluador. Nota completa: docs/FOUNDRY.md.

Primer dólar

Mide primero. Siéntate si el bucle aguanta.

Unidad

Stripe

x402

OpenGOS Search $0.40

Comprar

GET /v1/search

OpenGOS Draft $2.50

Comprar

GET /v1/draft

Agentic OS Cycle $0.75

Comprar

GET /v1/cycle

YodMCP Pro $49/mo

Suscribirse

USDC

Vía x402: x402-cloudflare-starter. Sincronización de escritorio: https://anamized.grok.me

Related MCP server: Agentic Control Framework (ACF)

Interfaces del paquete

| Interfaz | Comando | Predeterminado | Propósito | |---------|---------|---------| | MCP | yodmcp | stdio | Clientes MCP locales (Cursor, Claude Desktop, etc.) | | MCP HTTP | yodmcp --http --port 8000 | :8000/mcp | Remoto / Streamable HTTP MCP | | API | yodmcp-api --port 8080 | :8080 | REST de salud, memoria, auditoría, skills y facturación | | A2A | yodmcp-a2a --port 9000 | :9000 | Agent Card, mensaje, tareas | | SDK | from yodmcp.sdk import YodClient | Cliente HTTP | Cliente ligero para la API | | Skills | skills:// + skills/*/SKILL.md | auto-cargadas | Agent Skills como recursos MCP | | Verify | pytest + scripts/verify_e2e.py | CI | Modos Substrate + durable + TEE |

Requisitos

  • Python 3.11 o 3.12 (se declara 3.10+; CI cubre 3.11/3.12)

  • Opcional: Docker para compose multi-servicio

Instalación

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

Copia los valores predeterminados del entorno:

cp .env.example .env

Variable

Predeterminado

Significado

YODMCP_MEMORY_BACKEND

memory

memory | sqlite | durable

YODMCP_MEMORY_DB

./data/yodmcp_memory.db

Ruta SQLite en modo durable

YODMCP_ATTEST_MODE

software

software | simulated_tee | nitro | sgx

YODMCP_PLAN

free

free | pro | enterprise

YODMCP_TENANT_ID

default

Clave de tenant de cuota flexible

YODMCP_SKILLS_DIR

(auto)

Sobrescribe la raíz de skills

STRIPE_SECRET_KEY

sin definir

Habilita Checkout Sessions en modo producción

Honestidad sobre TEE: nitro / sgx son ganchos de proveedor; sin bibliotecas TEE reales recurren a afirmaciones simuladas. Prefiere software o simulated_tee para la verificación local.

Inicio rápido (local)

# 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

Configuración del cliente MCP (stdio)

Cursor — .cursor/mcp.json del proyecto o configuración global de MCP:

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

Si yodmcp no está en PATH, usa la forma de módulo:

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

Claude Desktop — misma estructura bajo mcpServers en claude_desktop_config.json.

Streamable HTTP MCP (clientes remotos que admiten transporte por URL):

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

Contenedor solo de la API:

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

Verificación de extremo a extremo (no se requieren cuentas externas)

# 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

Resultado esperado: todas las pruebas en verde; el script imprime ALL E2E CHECKS PASSED.

Prueba de humo de la API (con yodmcp-api en ejecución):

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

Herramienta

Descripción

memory_write

Inserta un nodo de memoria (hechos/decisiones). No para planes (plan_cache_put).

memory_read

Recupera nodos por similitud o item_id. No para planes (plan_cache_get).

memory_delete

Elimina definitivamente un nodo + aristas incidentes. Idempotente si no existe.

memory_consolidate

Promueve importancia ≥ 0.8 a resúmenes semánticos. No elimina las fuentes.

memory_stats

Conteos de nodos/aristas/entidades. No contenido (memory_read).

tasks_create

Crea un manejador de tarea pendiente durable.

tasks_get

Obtiene un manejador por id.

tasks_list

Lista manejadores recientes, con filtro de estado opcional.

tasks_update

Actualiza estado/progreso/resultado. No cancela (tasks_cancel).

tasks_cancel

Marca un manejador como cancelado (solo estado del kernel).

tasks_stats

Conteos por estado. No es un listado (tasks_list).

skills_list

Lista Agent Skills + URIs skills:// (los cuerpos son recursos).

a2a_card

JSON de Agent Card de A2A. No el catálogo MCP (discover_capabilities).

plan_cache_get / plan_cache_put / plan_cache_delete

Plantillas semánticas de planes. No hechos de memoria.

cache_stats

Totales de entradas/aciertos de la caché en proceso.

attestation_recent

Afirmaciones de procedencia al estilo TRACE. No el registro de auditoría (audit_recent).

audit_recent

Eventos del sistema de registro de decisiones de políticas/herramientas.

discover_capabilities

Lista herramientas MCP + skills cargadas.

echo

Sonda de actividad (message repetido + versión).

Recursos:

  • skills://{name} — cuerpo markdown de la skill

  • yodmcp://agent-card — JSON de agent card

Skills

Las skills integradas siempre están registradas. Las skills en disco bajo skills/*/SKILL.md se cargan automáticamente (se pueden sobrescribir mediante YODMCP_SKILLS_DIR). El repositorio incluye:

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

  • Además de la integrada long-horizon-planning

Monetización

Plan

$/mo

Llamadas de herramientas/día

Persistente

TEE

Free

0

500

—

—

Pro

49

50k

sí

simulado

Enterprise

499

ilimitado

sí

ganchos Nitro/SGX

  • Cuotas flexibles mediante la compuerta de herramientas; mensaje de actualización al agotarse.

  • Stripe Checkout en modo producción cuando STRIPE_SECRET_KEY está definida; de lo contrario, checkout devuelve status: payment_link.

USDC no custodial (preferido para agentes)

Red

Dirección

Base

0xD3d0E9eDAe3Ac7bb199a8EAA761BdA423b878438

Ethereum

0xD3d0E9eDAe3Ac7bb199a8EAA761BdA423b878438

Solana

ETQwWf19axArsY493UfC6bxe2BmEzmzvCb58PPnC38A

Canónico: funding/addresses.json

Estructura del proyecto

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

Limitaciones conocidas (léelas antes de declarar producción)

  1. La caché de planes usa embeddings ligeros; el umbral de similitud predeterminado es 0.68 (no es búsqueda vectorial de producción).

  2. TEE Nitro/SGX son ganchos con respaldo simulado a menos que conectes proveedores reales.

  3. Frontend src/yodmcp/frontend/dashboard.py sigue usando el core.runtime heredado y no es el plano de control principal — usa yodmcp-api + herramientas MCP.

  4. Las cuotas son flexibles (medidor en proceso); no son un libro mayor de facturación distribuido.

  5. Los procesos no comparten estado en memoria; usa el backend sqlite + volumen compartido para la durabilidad multiproceso.

Licencia

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