Yodmcp

YodMCP — Agent Operating System

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.

This 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.

FOUNDRY mapping

FOUNDRY (host-owned trust and memory for long-horizon agent swarms) separates untrusted proposal generation from host-owned verification + established-facts registry.

YodMCP 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.

First dollar

Meters first. Seat if the loop holds.

x402 rail: x402-cloudflare-starter. Desk sync: https://anamized.grok.me

Package surfaces

Requirements

• Python 3.11 or 3.12 (3.10+ declared; CI covers 3.11/3.12)
• Optional: Docker for multi-service compose

Install

git clone https://github.com/ANAMIZED/YodMCP.git

cd YodMCP python -m venv .venv && source .venv/bin/activate # recommended pip install -e ".[dev]"

Copy environment defaults:

cp .env.example .env

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.

Quick start (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

MCP client configuration (stdio)

Cursor — project .cursor/mcp.json or global MCP settings:

{

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

If yodmcp is not on PATH, use the module form:

{

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

Claude Desktop — same shape under mcpServers in claude_desktop_config.json.

Streamable HTTP MCP (remote clients that support URL transport):

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

Single API container:

docker build -t yodmcp .

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

Verify end-to-end (no external accounts required)

# 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

Expected: all tests green; script prints ALL E2E CHECKS PASSED.

API smoke (with yodmcp-api running):

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 tools (catalog)

Resources:

• skills://{name} — skill markdown body
• yodmcp://agent-card — agent card JSON

Skills

Built-in skills are always registered. Disk skills under skills/*/SKILL.md are loaded automatically (override via YODMCP_SKILLS_DIR). Repo ships:

• memory-hygiene, safe-tool-use, funding-usdc, repo-bootstrap
• Plus built-in long-horizon-planning

Monetization

• Soft quotas via tool gate; upgrade messaging on exhaustion
• Live Stripe Checkout when STRIPE_SECRET_KEY is set; otherwise checkout returns status: payment_link

Non-custodial USDC (preferred for agents)

Canonical: funding/addresses.json

Project layout

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

Known limitations (read before claiming production)

1. Plan cache uses lightweight embeddings; default similarity threshold is 0.68 (not production vector search).
2. TEE Nitro/SGX are hooks with simulated fallback unless you wire real providers.
3. Frontend src/yodmcp/frontend/dashboard.py still uses legacy core.runtime and is not the primary control plane — use yodmcp-api + MCP tools.
4. Quotas are soft (in-process meter); not a distributed billing ledger.
5. Processes do not share in-memory state; use sqlite backend + shared volume for multi-process durability.

License

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