Skip to main content
Glama

YodMCP — 에이전트 운영 체제

CI Version YodMCP MCP server Python License MCP

YodMCP는 프로덕션 지향 에이전트 운영 체제 커널입니다: 다중 그래프 메모리, 태스크, 스킬, A2A, 증명(소프트웨어/시뮬레이션된 TEE), OpenTelemetry, 플랜 기반 수익화를 제공합니다.

이 README는 이 파일 + 소스 트리만 가지고 시니어 엔지니어가 모든 표면을 설치·배포하고, 기능을 실행하며, 엔드투엔드로 검증할 수 있도록 작성되었습니다.

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/mo

구독

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 | 원격 / Streamable HTTP MCP | | API | yodmcp-api --port 8080 | :8080 | REST 상태, 메모리, 감사, 스킬, 결제 | | A2A | yodmcp-a2a --port 9000 | :9000 | Agent Card, 메시지, 태스크 | | SDK | from yodmcp.sdk import YodClient | HTTP 클라이언트 | API용 경량 클라이언트 | | Skills | skills:// + skills/*/SKILL.md | 자동 로드 | MCP 리소스로 제공되는 Agent Skills | | Verify | pytest + scripts/verify_e2e.py | CI | Substrate + durable + TEE 모드 |

요구 사항

  • Python 3.11 또는 3.12 (3.10+ 선언; CI는 3.11/3.12 포함)

  • 선택 사항: 다중 서비스 컴포즈용 Docker

설치

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

durable일 때 SQLite 경로

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 — claude_desktop_config.json의 mcpServers 아래 동일한 형태입니다.

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

엔드투엔드 검증 (외부 계정 불필요)

# 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 스모크 (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

Agent Skills + skills:// URI 목록 (본문은 리소스).

a2a_card

A2A Agent Card JSON. MCP 카탈로그 아님 (discover_capabilities).

plan_cache_get / plan_cache_put / plan_cache_delete

의미 플랜 템플릿. 메모리 사실 아님.

cache_stats

프로세스 내 캐시 항목/적중 합계.

attestation_recent

TRACE 스타일 입증(provenance) 클레임. 감사 추적 아님 (audit_recent).

audit_recent

정책/도구 결정 기록 시스템 이벤트.

discover_capabilities

MCP 도구 + 로드된 스킬 목록.

echo

활성 상태 프로브 (message 에코 + 버전).

리소스:

  • skills://{name} — 스킬 마크다운 본문

  • yodmcp://agent-card — 에이전트 카드 JSON

스킬

내장 스킬은 항상 등록됩니다. skills/*/SKILL.md 아래의 디스크 스킬은 자동으로 로드됩니다 (YODMCP_SKILLS_DIR로 재정의 가능). 저장소는 다음을 제공합니다:

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

  • 추가로 내장 long-horizon-planning

수익화

플랜

$/mo

일일 도구 호출

지속형

TEE

무료

0

500

—

—

프로

49

50k

예

시뮬레이션

엔터프라이즈

499

무제한

예

Nitro/SGX 훅

  • 도구 게이트를 통한 소프트 쿼터; 소진 시 업그레이드 메시지

  • STRIPE_SECRET_KEY가 설정되면 실시간 Stripe Checkout; 그렇지 않으면 결제가 status: payment_link를 반환합니다.

비수탁 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