{
  "markdown": "# YodMCP — Agent Operating System\n\n[![CI](https://github.com/ANAMIZED/YodMCP/actions/workflows/ci.yml/badge.svg)](https://github.com/ANAMIZED/YodMCP/actions/workflows/ci.yml)\n[![Version](https://img.shields.io/badge/version-0.5.0-blue.svg)](https://github.com/ANAMIZED/YodMCP)\n[![YodMCP MCP server](https://glama.ai/mcp/servers/ANAMIZED/YodMCP/badges/score.svg)](https://glama.ai/mcp/servers/ANAMIZED/YodMCP/score)\n[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://www.python.org/)\n[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-2026--07--28-purple.svg)](https://modelcontextprotocol.io/)\n\n**YodMCP** is a production-oriented **Agent Operating System** kernel on MCP: multi-graph memory, Tasks, Skills, A2A, attestation (software / simulated TEE), OpenTelemetry, and plan-based monetization.\n\nThis README is written so a senior engineer with **only this file + the source tree** can install, deploy every surface, exercise features, and verify end-to-end.\n\n## FOUNDRY mapping\n\nFOUNDRY (host-owned trust and memory for long-horizon agent swarms) separates untrusted proposal generation from host-owned verification + established-facts registry.\n\nYodMCP is that registry in production: agents call `memory_write`; promotion to semantic memory is gated; the host owns the evaluator. Full note: [`docs/FOUNDRY.md`](docs/FOUNDRY.md).\n\n### First dollar\n\nMeters first. Seat if the loop holds.\n\n| Unit | Stripe | x402 |\n|------|--------|------|\n| OpenGOS Search $0.40 | [Buy](https://buy.stripe.com/7sY8wQ5EW3iZ5xb5Re43S06) | `GET /v1/search` |\n| OpenGOS Draft $2.50 | [Buy](https://buy.stripe.com/9B69AUd7o7zf2kZ2F243S03) | `GET /v1/draft` |\n| Agentic OS Cycle $0.75 | [Buy](https://buy.stripe.com/3cI14o8R8dXD3p3frO43S04) | `GET /v1/cycle` |\n| **YodMCP Pro $49/mo** | [Subscribe](https://buy.stripe.com/bJe3cw0kCaLrbVz1AY43S09) | USDC |\n\nx402 rail: [x402-cloudflare-starter](https://github.com/ANAMIZED/x402-cloudflare-starter). Desk sync: https://anamized.grok.me\n\n## Package surfaces\n\n| Surface | Command | Default | Purpose |\n|---------|---------|---------|\n| **MCP** | `yodmcp` | stdio | Local MCP clients (Cursor, Claude Desktop, etc.) |\n| **MCP HTTP** | `yodmcp --http --port 8000` | `:8000/mcp` | Remote / Streamable HTTP MCP |\n| **API** | `yodmcp-api --port 8080` | `:8080` | REST health, memory, audit, skills, billing |\n| **A2A** | `yodmcp-a2a --port 9000` | `:9000` | Agent Card, message, tasks |\n| **SDK** | `from yodmcp.sdk import YodClient` | HTTP client | Thin client for the API |\n| **Skills** | `skills://` + `skills/*/SKILL.md` | auto-loaded | Agent Skills as MCP resources |\n| **Verify** | `pytest` + `scripts/verify_e2e.py` | CI | Substrate + durable + TEE modes |\n\n## Requirements\n\n- Python **3.11 or 3.12** (3.10+ declared; CI covers 3.11/3.12)\n- Optional: Docker for multi-service compose\n\n## Install\n\n```bash\ngit clone https://github.com/ANAMIZED/YodMCP.git\ncd YodMCP\npython -m venv .venv && source .venv/bin/activate   # recommended\npip install -e \".[dev]\"\n```\n\nCopy environment defaults:\n\n```bash\ncp .env.example .env\n```\n\n| Variable | Default | Meaning |\n|----------|---------|---------|\n| `YODMCP_MEMORY_BACKEND` | `memory` | `memory` \\| `sqlite` \\| `durable` |\n| `YODMCP_MEMORY_DB` | `./data/yodmcp_memory.db` | SQLite path when durable |\n| `YODMCP_ATTEST_MODE` | `software` | `software` \\| `simulated_tee` \\| `nitro` \\| `sgx` |\n| `YODMCP_PLAN` | `free` | `free` \\| `pro` \\| `enterprise` |\n| `YODMCP_TENANT_ID` | `default` | Soft quota tenant key |\n| `YODMCP_SKILLS_DIR` | *(auto)* | Override skills root |\n| `STRIPE_SECRET_KEY` | unset | Enables live Checkout Sessions |\n\n> **TEE honesty:** `nitro` / `sgx` are provider hooks; without real TEE libraries they fall back to simulated claims. Prefer `software` or `simulated_tee` for local verify.\n\n## Quick start (local)\n\n```bash\n# 1) MCP over stdio (attach from an MCP client)\nyodmcp\n\n# 2) REST API\nyodmcp-api --port 8080\n# curl http://127.0.0.1:8080/health\n\n# 3) A2A\nyodmcp-a2a --port 9000\n# curl http://127.0.0.1:9000/a2a/card\n```\n\n### MCP client configuration (stdio)\n\n**Cursor** — project `.cursor/mcp.json` or global MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"yodmcp\": {\n      \"command\": \"yodmcp\",\n      \"args\": [],\n      \"env\": {\n        \"YODMCP_MEMORY_BACKEND\": \"memory\",\n        \"YODMCP_PLAN\": \"free\",\n        \"YODMCP_ATTEST_MODE\": \"software\"\n      }\n    }\n  }\n}\n```\n\nIf `yodmcp` is not on `PATH`, use the module form:\n\n```json\n{\n  \"mcpServers\": {\n    \"yodmcp\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"yodmcp\"],\n      \"cwd\": \"/absolute/path/to/YodMCP\",\n      \"env\": {\n        \"PYTHONPATH\": \"src\",\n        \"YODMCP_MEMORY_BACKEND\": \"memory\"\n      }\n    }\n  }\n}\n```\n\n**Claude Desktop** — same shape under `mcpServers` in `claude_desktop_config.json`.\n\n**Streamable HTTP MCP** (remote clients that support URL transport):\n\n```bash\nyodmcp --http --host 0.0.0.0 --port 8000\n# endpoint: http://127.0.0.1:8000/mcp\n```\n\n## Docker\n\n```bash\ndocker compose up --build\n# API  :8080  A2A :9000  MCP HTTP :8000\n```\n\nSingle API container:\n\n```bash\ndocker build -t yodmcp .\ndocker run --rm -p 8080:8080 -e YODMCP_PLAN=free yodmcp\n```\n\n## Verify end-to-end (no external accounts required)\n\n```bash\n# Unit + integration\nYODMCP_MEMORY_BACKEND=memory YODMCP_ATTEST_MODE=software \\\n  PYTHONPATH=src pytest tests/ -v\n\n# Durable SQLite + simulated TEE\nYODMCP_MEMORY_BACKEND=sqlite YODMCP_MEMORY_DB=/tmp/yodmcp.db \\\n  YODMCP_ATTEST_MODE=simulated_tee \\\n  PYTHONPATH=src pytest tests/ -v\n\n# Exhaustive substrate script\nPYTHONPATH=src python scripts/verify_e2e.py\n```\n\nExpected: all tests green; script prints `ALL E2E CHECKS PASSED`.\n\nAPI smoke (with `yodmcp-api` running):\n\n```bash\ncurl -s http://127.0.0.1:8080/health\ncurl -s http://127.0.0.1:8080/api/skills\ncurl -s http://127.0.0.1:8080/api/billing/plans\ncurl -s http://127.0.0.1:8080/api/billing/status\n```\n\nSDK:\n\n```bash\npython examples/sdk_quickstart.py   # requires API on :8080\n```\n\n## MCP tools (catalog)\n\n| Tool | Description |\n|------|-------------|\n| `memory_write` | Insert one memory node (facts/decisions). Not for plans (`plan_cache_put`). |\n| `memory_read` | Retrieve nodes by similarity or `item_id`. Not for plans (`plan_cache_get`). |\n| `memory_delete` | Hard-delete one node + incident edges. Idempotent if missing. |\n| `memory_consolidate` | Promote importance ≥ 0.8 into semantic summaries. Does not delete sources. |\n| `memory_stats` | Node/edge/entity counts. Not content (`memory_read`). |\n| `tasks_create` | Create a durable pending task handle. |\n| `tasks_get` | Fetch one handle by id. |\n| `tasks_list` | List recent handles, optional status filter. |\n| `tasks_update` | Patch status/progress/result. Not cancel (`tasks_cancel`). |\n| `tasks_cancel` | Mark a handle cancelled (kernel state only). |\n| `tasks_stats` | Counts by status. Not a listing (`tasks_list`). |\n| `skills_list` | List Agent Skills + `skills://` URIs (bodies are resources). |\n| `a2a_card` | A2A Agent Card JSON. Not the MCP catalog (`discover_capabilities`). |\n| `plan_cache_get` / `plan_cache_put` / `plan_cache_delete` | Semantic plan templates. Not memory facts. |\n| `cache_stats` | In-process cache entry/hit totals. |\n| `attestation_recent` | TRACE-style provenance claims. Not the audit trail (`audit_recent`). |\n| `audit_recent` | Policy/tool Decision-System-of-Record events. |\n| `discover_capabilities` | List MCP tools + loaded skills. |\n| `echo` | Liveness probe (`message` echoed + version). |\n\nResources:\n\n- `skills://{name}` — skill markdown body\n- `yodmcp://agent-card` — agent card JSON\n\n## Skills\n\nBuilt-in skills are always registered. **Disk skills** under `skills/*/SKILL.md` are loaded automatically (override via `YODMCP_SKILLS_DIR`). Repo ships:\n\n- `memory-hygiene`, `safe-tool-use`, `funding-usdc`, `repo-bootstrap`\n- Plus built-in `long-horizon-planning`\n\n## Monetization\n\n| Plan | $/mo | Tool calls/day | Durable | TEE |\n|------|------|----------------|---------|-----|\n| Free | 0 | 500 | — | — |\n| Pro | 49 | 50k | yes | simulated |\n| Enterprise | 499 | unlimited | yes | Nitro/SGX hooks |\n\n- Soft quotas via tool gate; upgrade messaging on exhaustion\n- Live Stripe Checkout when `STRIPE_SECRET_KEY` is set; otherwise checkout returns `status: payment_link`\n\n| Option | Link |\n|------|------|\n| **YodMCP Pro** | https://buy.stripe.com/bJe3cw0kCaLrbVz1AY43S09 |\n| **YodMCP Enterprise** | https://buy.stripe.com/9B68wQ1oGcTz9NrfrO43S0a |\n| **Agentic OS Kernel Support** ($99) | https://buy.stripe.com/bJecN63wObPv6Bf7Zm43S02 |\n| **Public Goods Support** ($25) | https://donate.stripe.com/00w5kE3wOg5L8Jn2F243S00 |\n| **Agentic Systems Consulting Hour** ($199) | https://buy.stripe.com/dRmaEYgjA9Hnf7LdjG43S0b |\n\n### Non-custodial USDC (preferred for agents)\n\n| Network | Address |\n|---------|---------|\n| **Base** | `0xD3d0E9eDAe3Ac7bb199a8EAA761BdA423b878438` |\n| **Ethereum** | `0xD3d0E9eDAe3Ac7bb199a8EAA761BdA423b878438` |\n| **Solana** | `ETQwWf19axArsY493UfC6bxe2BmEzmzvCb58PPnC38A` |\n\nCanonical: [`funding/addresses.json`](funding/addresses.json)\n\n## Project layout\n\n```\nsrc/yodmcp/          # package (src-layout)\n  core/              # server, substrate, context\n  memory/            # in-memory + durable SQLite multi-graph\n  tools/             # MCP tool registration + gate\n  tasks/ skills/ cache/ security/ observability/ monetization/\n  api/ a2a/ sdk/\nskills/*/SKILL.md    # portable Agent Skills (loaded at runtime)\nscripts/verify_e2e.py\ntests/\ndocs/ARCHITECTURE.md\ndocs/FOUNDRY.md\ndocs/TDQS.md\n```\n\n## Known limitations (read before claiming production)\n\n1. **Plan cache** uses lightweight embeddings; default similarity threshold is **0.68** (not production vector search).\n2. **TEE** Nitro/SGX are hooks with simulated fallback unless you wire real providers.\n3. **Frontend** `src/yodmcp/frontend/dashboard.py` still uses legacy `core.runtime` and is **not** the primary control plane — use `yodmcp-api` + MCP tools.\n4. **Quotas** are soft (in-process meter); not a distributed billing ledger.\n5. Processes do **not** share in-memory state; use `sqlite` backend + shared volume for multi-process durability.\n\n## License\n\nApache-2.0 · [CONTRIBUTING](CONTRIBUTING.md) · [CHANGELOG](CHANGELOG.md) · [ARCHITECTURE](docs/ARCHITECTURE.md) · [FOUNDRY](docs/FOUNDRY.md) · [TDQS](docs/TDQS.md) · [AGENTS.md](AGENTS.md)\n",
  "bytes": 10384,
  "sha": "190ac48fc58ed9effabf05f2cc08979c8d1904ba03998781477ac2def1391ebc",
  "repo_slug": "anamized/yodmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_anamized_yodmcp_c3cac95e/readme"
}