Skip to main content
Glama

YodMCP — Агентская операционная система

CI Version YodMCP MCP server Python License MCP

YodMCP — это ориентированное на продакшн ядро агентной операционной системы на MCP: мультиграфовая память, задачи, навыки, A2A, аттестация (программная / симулированный TEE), OpenTelemetry и монетизация на основе планов.

Этот README написан так, чтобы старший инженер, имея только этот файл + дерево исходников, мог установить, развернуть каждую поверхность, опробовать функции и проверить работу end-to-end.

Сопоставление с FOUNDRY

FOUNDRY (доверие и память, принадлежащие хосту, для долгоживущих роёв агентов) разделяет генерацию непроверенных предложений и принадлежащую хосту верификацию + реестр установленных фактов.

YodMCP — это тот самый реестр в продакшене: агенты вызывают memory_write; продвижение в семантическую память ограничено шлюзом; оценщик принадлежит хосту. Полное описание: docs/FOUNDRY.md.

Первый доллар

Сначала метрики. Займи место, если цикл держится.

Единица

Stripe

x402

OpenGOS Search $0.40

Купить

GET /v1/search

OpenGOS Draft $2.50

Купить

GET /v1/draft

Agentic OS Cycle $0.75

Купить

GET /v1/cycle

YodMCP Pro $49/мес

Подписаться

USDC

Рельс x402: x402-cloudflare-starter. Синхронизация рабочего стола: https://anamized.grok.me

Related MCP server: Agentic Control Framework (ACF)

Поверхности пакета

| Поверхность | Команда | По умолчанию | Назначение | |---------|---------|---------| | MCP | yodmcp | stdio | Локальные MCP-клиенты (Cursor, Claude Desktop и т.д.) | | MCP HTTP | yodmcp --http --port 8000 | :8000/mcp | Удалённый / потоковый HTTP MCP | | API | yodmcp-api --port 8080 | :8080 | REST: health, память, аудит, навыки, биллинг | | A2A | yodmcp-a2a --port 9000 | :9000 | Agent Card, сообщения, задачи | | SDK | from yodmcp.sdk import YodClient | HTTP-клиент | Тонкий клиент для API | | Skills | skills:// + skills/*/SKILL.md | автозагрузка | Навыки агентов как ресурсы MCP | | Verify | pytest + scripts/verify_e2e.py | CI | Режимы Substrate + durable + TEE |

Требования

  • Python 3.11 или 3.12 (заявлен 3.10+; CI покрывает 3.11/3.12)

  • Опционально: Docker для мультисервисного compose

Установка

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

Скопируйте окружение по умолчанию:

cp .env.example .env

Переменная

По умолчанию

Значение

YODMCP_MEMORY_BACKEND

memory

memory | sqlite | durable

YODMCP_MEMORY_DB

./data/yodmcp_memory.db

Путь к SQLite для режима durable

YODMCP_ATTEST_MODE

software

software | simulated_tee | nitro | sgx

YODMCP_PLAN

free

free | pro | enterprise

YODMCP_TENANT_ID

default

Ключ тенанта для мягкой квоты

YODMCP_SKILLS_DIR

(авто)

Переопределение корня навыков

STRIPE_SECRET_KEY

не задано

Включает боевые Checkout-сессии

Честность TEE: nitro / sgx — это хуки провайдера; без реальных TEE-библиотек они откатываются к симулированным утверждениям. Для локальной проверки предпочитайте software или simulated_tee.

Быстрый старт (локально)

# 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-клиента (stdio)

Cursor — файл проекта .cursor/mcp.json или глобальные настройки MCP:

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

Если yodmcp отсутствует в PATH, используйте форму модуля:

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

Claude Desktop — та же структура в разделе mcpServers файла claude_desktop_config.json.

Streamable HTTP MCP (удалённые клиенты, поддерживающие 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

Один API-контейнер:

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

Проверка end-to-end (внешние аккаунты не требуются)

# 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

Ожидается: все тесты зелёные; скрипт печатает ALL E2E CHECKS PASSED.

API smoke-тест (при запущенном 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 (каталог)

Инструмент

Описание

memory_write

Вставить один узел памяти (факты/решения). Не для планов (plan_cache_put).

memory_read

Получить узлы по сходству или item_id. Не для планов (plan_cache_get).

memory_delete

Жёсткое удаление одного узла + инцидентных рёбер. Идемпотентно при отсутствии.

memory_consolidate

Повышает важность ≥ 0.8 до семантических сводок. Исходники не удаляются.

memory_stats

Количество узлов/рёбер/сущностей. Не содержимое (memory_read).

tasks_create

Создать устойчивый дескриптор ожидающей задачи.

tasks_get

Получить один дескриптор по id.

tasks_list

Список последних дескрипторов, опциональный фильтр по статусу.

tasks_update

Обновить статус/прогресс/результат. Не отмена (tasks_cancel).

tasks_cancel

Пометить дескриптор отменённым (только состояние ядра).

tasks_stats

Количество по статусам. Не список (tasks_list).

skills_list

Список навыков агентов + URI skills:// (тела — это ресурсы).

a2a_card

JSON карточки агента A2A. Не каталог MCP (discover_capabilities).

plan_cache_get / plan_cache_put / plan_cache_delete

Семантические шаблоны планов. Не факты памяти.

cache_stats

Итоги по записям/попаданиям внутрипроцессного кэша.

attestation_recent

Утверждения о происхождении в стиле TRACE. Не журнал аудита (audit_recent).

audit_recent

События Decision-System-of-Record для политик/инструментов.

discover_capabilities

Список MCP-инструментов + загруженных навыков.

echo

Проверка живости (эхо message + версия).

Ресурсы:

  • skills://{name} — тело навыка в Markdown

  • yodmcp://agent-card — JSON карточки агента

Навыки

Встроенные навыки регистрируются всегда. Дисковые навыки из skills/*/SKILL.md загружаются автоматически (переопределение через YODMCP_SKILLS_DIR). В репозитории поставляются:

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

  • Плюс встроенный long-horizon-planning

Монетизация

План

$/мес

Вызовов инструментов/день

Durable

TEE

Free

0

500

—

—

Pro

49

50k

да

симуляция

Enterprise

499

безлимитно

да

хуки Nitro/SGX

  • Мягкие квоты через шлюз инструментов; сообщение об апгрейде при исчерпании.

  • Боевой Stripe Checkout, если задан STRIPE_SECRET_KEY; в противном случае checkout возвращает status: payment_link.

Вариант

Ссылка

YodMCP Pro

https://buy.stripe.com/bJe3cw0kCaLrbVz1AY43S09

YodMCP Enterprise

https://buy.stripe.com/9B68wQ1oGcTz9NrfrO43S0a

Поддержка ядра Agentic OS ($99)

https://buy.stripe.com/bJecN63wObPv6Bf7Zm43S02

Поддержка общественных благ ($25)

https://donate.stripe.com/00w5kE3wOg5L8Jn2F243S00

Час консультаций по агентным системам ($199)

https://buy.stripe.com/dRmaEYgjA9Hnf7LdjG43S0b

Некастодиальный USDC (предпочтительно для агентов)

Сеть

Адрес

Base

0xD3d0E9eDAe3Ac7bb199a8EAA761BdA423b878438

Ethereum

0xD3d0E9eDAe3Ac7bb199a8EAA761BdA423b878438

Solana

ETQwWf19axArsY493UfC6bxe2BmEzmzvCb58PPnC38A

Канонический источник: funding/addresses.json

Структура проекта

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

Известные ограничения (прочитайте перед заявлением о продакшене)

  1. Кэш планов использует лёгкие эмбеддинги; порог сходства по умолчанию — 0.68 (не продакшен-векторный поиск).

  2. TEE Nitro/SGX — это хуки с симулированным запасным вариантом, если вы не подключите реальных провайдеров.

  3. Фронтенд src/yodmcp/frontend/dashboard.py по-прежнему использует устаревший core.runtime и не является основной панелью управления — используйте yodmcp-api + инструменты MCP.

  4. Квоты мягкие (внутрипроцессный счётчик); это не распределённый биллинговый реестр.

  5. Процессы не разделяют состояние в памяти; для долговечности в многопроцессном режиме используйте бэкенд sqlite + общий том.

Лицензия

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