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

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

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

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

Related MCP server: Agentic Control Framework (ACF)

Требования

• 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

Честность TEE: nitro / sgx — это хуки провайдера; без реальных TEE-библиотек они откатываются к имитируемым утверждениям (simulated claims). Для локальной проверки предпочитайте 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 (каталог)

Ресурсы:

• 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

Монетизация

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

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

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

Канонический источник: 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

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

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

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

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

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

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

Лицензия

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