Skip to main content
Glama

YodMCP — 智能体操作系统

CI Version YodMCP MCP server Python License MCP

YodMCP 是一个面向生产的、基于 MCP 的 智能体操作系统内核:多图记忆、Tasks、Skills、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。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

变量

默认值

含义

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

(自动)

覆盖 skills 根目录

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 风格来源声明。不是审计轨迹(请用 audit_recent)。

audit_recent

策略/工具决策记录系统(Decision-System-of-Record)事件。

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

—

—

专业版

49

50k

是

模拟

企业版

499

无限

是

Nitro/SGX 钩子

  • 通过工具网关实现软配额;额度耗尽时显示升级提示

  • 设置 STRIPE_SECRET_KEY 后启用实时 Stripe Checkout;否则 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. Plan cache(方案缓存) 使用轻量级嵌入;默认相似度阈值为 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