Metadata-Version: 2.4
Name: ymcp
Version: 0.3.0
Summary: Python MCP workflow tools for host-controlled planning workflows
Project-URL: Homepage, https://github.com/ymcp/ymcp
Project-URL: Documentation, https://github.com/ymcp/ymcp#readme
Project-URL: Issues, https://github.com/ymcp/ymcp/issues
Project-URL: Source, https://github.com/ymcp/ymcp
Author: Ymcp contributors
License-Expression: MIT
License-File: LICENSE
Keywords: fastmcp,mcp,planning,trae,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.27
Requires-Dist: mempalace<4,>=3.3.2
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: pytest<9,>=8; extra == 'dev'
Requires-Dist: tomli<3,>=2; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Description-Content-Type: text/markdown

# Ymcp

Trae / 通用 LLM 宿主可用的 MCP 工具包，提供 `ydeep`、`yplan`、`ydo` 等 workflow tools，以及基于 MemPalace 的长期记忆能力。

## 核心模型

- **tool 负责轻 gate**：阶段入口、统一 handoff、Elicitation 选项、必要时产出最终交接 artifact
- **skill 负责思考**：具体推理过程由 LLM 自主完成
- **LLM 自主循环**：Ymcp 不维护重型服务端状态机，只提供关键流转约束
- **中间阶段不回灌复杂状态**：同一调用链内由 LLM 自己承接上下文
- **handoff.options 更接近菜单项**：重点是 `value`、`title`、`description`、`recommended`

## 当前 workflow tools

- `ydeep`
  - 对应 prompt：`deep-interview`
  - 输入核心：`brief`
  - 输出核心：`skill_content`、统一 `handoff`
- `yplan`
  - 对应 prompts：`planner` → `architect` → `critic`
  - 输入核心：`task`
  - 输出核心：阶段 `skill_content`、统一 `handoff`
  - 阶段链路：`yplan -> yplan_architect -> yplan_critic -> yplan_complete`
- `ydo`
  - 对应 prompt：`ralph`
  - 输入核心：无业务输入（依赖当前调用链上下文）
  - 输出核心：`skill_content`、统一 `handoff`

## Handoff contract

- `handoff.options` 是下一步动作的唯一权威源
- tool 只声明“有哪些下一步选项”，不声明自动参数映射协议
- 推荐宿主按固定约定串联阶段，而不是让 LLM 或 tool 维护复杂路由协议
- `ydeep_complete` 默认只进入 `yplan`，不再直接跳到 `ydo`
- `yplan` 只接受 `task`；如果来源是 `clarified_artifact`，应由宿主先转换为普通 `task`
- `yplan_critic` 只声明两个合法下一步：`yplan_critic` 或 `yplan_complete`
- `yplan_critic` 不强制固定 `APPROVE/REVISE` 协议；由 LLM 自行判断继续评审还是完成收口
- `yplan_complete` / `ydo_complete` 现在是更彻底的无输入收口阶段：调用它本身就表示 LLM 认为当前阶段已结束
- 只有 `ydeep_complete` 仍产出 `clarified_artifact`；planning / execution 的 complete 阶段不再要求输入摘要或构造中间 artifact

## 设计边界

- MCP tool 提供结构化阶段边界与下一步选项
- LLM 先完整思考与输出，再由宿主点击 complete / next-step 进入下一个 workflow
- complete 类工具（`ydeep_complete` / `yplan_complete` / `ydo_complete`）在关键节点提供 handoff 选项，并应通过 **Elicitation** 向用户展示菜单
- `host_controls` 仅表达当前返回实际依赖的宿主能力
- `status` 表示当前 tool 调用结果；`meta.required_host_action` 只表达宿主当前是“继续思考”还是“展示并收口”
- `handoff.options` 是下一步动作的**唯一权威源**；`allowed_next_actions` 仅为派生兼容视图
- `handoff.options` 应被视为服务端给出的菜单，而不是让 LLM 自己构造的路由对象

## 安装

```powershell
pip install ymcp
```

## 更新

```powershell
pip install -U ymcp
```

## 一键初始化 Trae 与默认记忆库

```powershell
ymcp init-trae
```

## 记忆

回答历史事实前先查 `mempalace_search` / `mempalace_get_drawer`；任务完成后把稳定偏好、项目约定、重要决策和踩坑结论写入 `mempalace_add_drawer` 或 `mempalace_diary_write`。
