YodMCP — Sistema Operativo para Agentes

YodMCP es un núcleo de Sistema Operativo para Agentes orientado a producción sobre MCP: memoria multigrafo, Tareas, Habilidades, A2A, atestación (software / TEE simulado), OpenTelemetry y monetización basada en planes.

Este README está escrito para que un ingeniero senior con solo este archivo + el árbol de fuentes pueda instalar, desplegar cada superficie, ejercitar funciones y verificar de extremo a extremo.

Superficies del paquete

Related MCP server: Agentic Control Framework (ACF)

Requisitos

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

• Opcional: Docker para compose multiservicio

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]"

Copiar valores predeterminados de entorno:

cp .env.example .env

Honestidad sobre TEE: nitro / sgx son enlaces de proveedor; sin bibliotecas TEE reales, recurren a reclamaciones simuladas. Prefiera software o simulated_tee para 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 de cliente MCP (stdio)

Cursor — archivo .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, use 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.

HTTP MCP transmisible (clientes remotos que soportan transporte 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 API único:

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

Verificación de extremo a extremo (no requiere 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

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

Prueba de 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

Herramientas MCP (catálogo)

Recursos:

• skills://{nombre} — cuerpo de la habilidad en markdown

• yodmcp://agent-card — JSON de la tarjeta del agente

Habilidades

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

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

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

Monetización

• Cuotas blandas a través de puerta de herramientas; mensajes de actualización al agotarse

• Sesión de pago Stripe en vivo cuando STRIPE_SECRET_KEY está configurada; de lo contrario, la sesión de pago devuelve status: payment_link

USDC no custodiado (preferido para agentes)

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

Limitaciones conocidas (lea antes de reclamar producción)

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

2. TEE Nitro/SGX son enlaces con retroceso simulado a menos que conecte proveedores reales.

3. Interfaz de usuario src/yodmcp/frontend/dashboard.py todavía usa core.runtime heredado y no es el plano de control principal — use yodmcp-api + herramientas MCP.

4. Cuotas son blandas (medidor en proceso); no es un libro de facturación distribuido.

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

Licencia

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