YodMCP
YodMCP — 智能体操作系统
YodMCP 是一个面向生产的、基于 MCP 的 智能体操作系统内核:多图记忆、Tasks、Skills、A2A、证明(软件 / 模拟 TEE)、OpenTelemetry,以及基于套餐的变现。
本 README 旨在让一位资深工程师仅凭此文件 + 源码树即可完成安装、部署所有运行面、实践各项功能,并做端到端验证。
FOUNDRY 映射
FOUNDRY(面向长周期智能体集群的宿主持有式信任与记忆)将不可信的提案生成与宿主持有的验证 + 既有事实注册表分离开来。
YodMCP 正是该注册表在生产中的实现:智能体调用 memory_write;提升到语义记忆的过程受门控;评估器由宿主持有。完整说明:docs/FOUNDRY.md。
第一美元
计量优先。若闭环成立,则入座。
单位 | Stripe | x402 |
OpenGOS Search $0.40 |
| |
OpenGOS Draft $2.50 |
| |
Agentic OS Cycle $0.75 |
| |
YodMCP Pro $49/mo | USDC |
x402 轨道:x402-cloudflare-starter。Desk 同步: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 client | 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(用于多服务 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变量 | 默认值 | 含义 |
|
|
|
|
| 使用 durable 后端时的 SQLite 路径 |
|
|
|
|
|
|
|
| 软配额租户键 |
| (自动) | 覆盖 skills 根目录 |
| 未设置 | 启用实时 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/cardMCP 客户端配置(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/mcpDocker
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/statusSDK:
python examples/sdk_quickstart.py # requires API on :8080MCP 工具(目录)
工具 | 描述 |
| 插入一个记忆节点(事实/决策)。不用于方案(请用 |
| 按相似度或 |
| 硬删除一个节点及其关联边。若节点不存在则幂等。 |
| 将重要性 ≥ 0.8 的记忆提升为语义摘要。不会删除源节点。 |
| 节点/边/实体计数。不返回内容(请用 |
| 创建一个持久化的待处理任务句柄。 |
| 按 id 获取一个句柄。 |
| 列出最近的句柄,可选状态过滤。 |
| 更新状态/进度/结果。不用于取消(请用 |
| 将句柄标记为已取消(仅内核状态)。 |
| 按状态统计数量。不是列表(请用 |
| 列出 Agent Skills 及 |
| A2A Agent Card JSON。不是 MCP 目录(请用 |
| 语义方案模板。不是记忆事实。 |
| 进程内缓存条目/命中总数。 |
| TRACE 风格来源声明。不是审计轨迹(请用 |
| 策略/工具决策记录系统(Decision-System-of-Record)事件。 |
| 列出 MCP 工具及已加载的技能。 |
| 存活探针(回显 |
资源:
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 | — | — |
专业版 | 49 | 50k | 是 | 模拟 |
企业版 | 499 | 无限 | 是 | Nitro/SGX 钩子 |
通过工具网关实现软配额;额度耗尽时显示升级提示
设置
STRIPE_SECRET_KEY后启用实时 Stripe Checkout;否则 checkout 返回status: payment_link
选项 | 链接 |
YodMCP Pro | |
YodMCP Enterprise | |
Agentic OS 内核支持 ($99) | |
公共物品支持 ($25) | |
Agentic Systems 咨询小时 ($199) |
非托管 USDC(智能体首选)
网络 | 地址 |
Base |
|
Ethereum |
|
Solana |
|
项目结构
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已知限制(在宣称生产可用之前请阅读)
Plan cache(方案缓存) 使用轻量级嵌入;默认相似度阈值为 0.68(不是生产级向量搜索)。
TEE Nitro/SGX 是带模拟回退的钩子,除非你接入真实提供商。
前端
src/yodmcp/frontend/dashboard.py仍使用旧版core.runtime,并不是主要控制平面 — 请使用yodmcp-api+ MCP 工具。配额 是软性的(进程内计量器),并非分布式计费账本。
各进程不共享内存状态;如需多进程持久化,请使用
sqlite后端 + 共享卷。
许可证
Apache-2.0 · CONTRIBUTING · CHANGELOG · ARCHITECTURE · FOUNDRY · TDQS · AGENTS.md
Available Tools
21 toolsa2a_cardGet A2A Agent CardARead-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 claimsARead-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 eventsARead-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 statisticsARead-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 skillsARead-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 probeARead-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 nodeADestructiveIdempotent
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 nodesARead-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 statisticsARead-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 planADestructiveIdempotent
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 planARead-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 SkillsARead-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 taskADestructiveIdempotent
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 idARead-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 tasksARead-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 statisticsARead-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
Scored across 21 tools
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.
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.
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.
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
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables deployment of autonomous AI agents with memory and tool execution capabilities through a WebSocket-based MCP protocol. Provides production-ready infrastructure with REST API access, persistent state management, and extensible function registry for building self-hosted AI systems.-
- AlicenseDqualityDmaintenanceAI-native orchestration layer with 80+ tools for task management, code editing, browser automation, terminal control, and persistent memory across CLI, local MCP, and cloud deployments.697 npm31ISC
- AlicenseNot gradedqualityDmaintenanceFoundational MCP/A2A-native core platform for secure credential injection, native x402 micropayments, and Agent-to-Agent routing.2MIT
- AlicenseNot gradedqualityDmaintenanceA production-ready MCP server that equips AI agents with dynamic, persistent, and executable skills. It enables secure script execution and progressive disclosure to reduce context window usage.22 npmMIT