yodmcp

YodMCP — Agent 操作系统

YodMCP 是一个面向生产环境的 Agent 操作系统内核，基于 MCP 构建：支持多图记忆、任务、技能、A2A、证明（软件／模拟 TEE）、OpenTelemetry 和基于计划的变现。

本 README 面向仅凭此文件和源代码树即可安装、部署各个接口、体验功能并验证端到端流程的资深工程师。

FOUNDRY 映射

FOUNDRY（面向长周期 Agent 群体的、由主机掌控的信任与记忆）将不可信的提案生成与由主机掌控的验证及既定事实注册表分离。

YodMCP 在生产环境中就是该注册表：Agent 调用 memory_write；提升至语义记忆需要经过门控；评估器由主机掌控。完整说明：docs/FOUNDRY.md。

首笔收入

先计量，再在闭环稳定后推出订阅席位。

单位	Stripe	x402
OpenGOS 搜索 $0.40	购买	GET /v1/search
OpenGOS 草稿 $2.50	购买	GET /v1/draft
Agentic OS 周期 $0.75	购买	GET /v1/cycle
YodMCP Pro $49/月	订阅	USDC

x402 支付通道：x402-cloudflare-starter。Desk 同步：https://anamized.grok.me

软件包接口

接口	命令	默认值	用途
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/*/SKILL.md	自动加载	作为 MCP 资源提供的 Agent 技能
验证	pytest + scripts/verify_e2e.py	CI	Substrate、持久化和 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	durable 模式下的 SQLite 路径
YODMCP_ATTEST_MODE	software	software | simulated_tee | nitro | sgx
YODMCP_PLAN	free	free | pro | enterprise
YODMCP_TENANT_ID	default	软配额租户键
YODMCP_SKILLS_DIR	(auto)	覆盖技能根目录
STRIPE_SECRET_KEY	未设置	启用实时 Checkout Sessions

关于 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 风格的来源声明。不提供审计记录（使用 audit_recent）。
audit_recent	策略/工具决策系统记录事件。
discover_capabilities	列出 MCP 工具和已加载的技能。
echo	存活探测（回显 message 和版本）。

资源：

• skills://{name} — 技能 Markdown 正文
• yodmcp://agent-card — Agent Card JSON

技能

内置技能始终处于注册状态。skills/*/SKILL.md 下的磁盘技能会自动加载（通过 YODMCP_SKILLS_DIR 覆盖）。仓库附带：

• memory-hygiene、safe-tool-use、funding-usdc、repo-bootstrap
• 另有内置的 long-horizon-planning

盈利模式

方案	$/月	每日工具调用次数	持久化	TEE
免费版	0	500	—	—
Pro	49	50k	是	模拟
Enterprise	499	不限	是	Nitro/SGX hooks

• 通过工具闸门实施软配额；达到上限后显示升级提示
• 设置 STRIPE_SECRET_KEY 后启用 Stripe Checkout；否则结账会返回 status: payment_link

选项	链接
YodMCP Pro	https://buy.stripe.com/bJe3cw0kCaLrbVz1AY43S09
YodMCP Enterprise	https://buy.stripe.com/9B68wQ1oGcTz9NrfrO43S0a
Agentic OS Kernel 支持（$99）	https://buy.stripe.com/bJecN63wObPv6Bf7Zm43S02
公共物品支持（$25）	https://donate.stripe.com/00w5kE3wOg5L8Jn2F243S00
Agentic Systems 咨询时段（$199）	https://buy.stripe.com/dRmaEYgjA9Hnf7LdjG43S0b

非托管 USDC（推荐供 Agent 使用）

网络	地址
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 · 贡献指南 · 更新日志 · 架构 · FOUNDRY · TDQS · AGENTS.md