ivy-sale-cli

ivy-sale-agent 平台开放接口的 CLI + MCP Server 客户端。同一个包，两种用法：

• CLI：直接在终端里用 ivy-sale <command>。
• MCP Server：ivy-sale mcp serve 以 stdio 方式启动，配置进 Claude Code / Codex 等支持 MCP 的 AI Agent 客户端里，让它调用平台的客户/待办/知识库/问答能力。

两者背后走同一套 /open/v1/* 网关接口、同一份凭证。

安装

发布到 PyPI 后（见文末「发布」），终端用户直接：

uv pip install ivy-sale-cli
# 或不装到全局环境、临时跑一次：
uvx ivy-sale-cli --help

开发这个仓库本身则用可编辑安装：

pip install -e .

Windows 终端如果看到中文输出乱码（不影响 MCP 客户端使用，只影响人眼直接看终端）， 设置 set PYTHONUTF8=1 或 chcp 65001 后再运行即可。

登录

Phase 1 暂不支持浏览器登录，需要先拿到一个开放平台 Token（sk- 开头），然后：

ivy-sale auth login --api-key sk-xxxxxxxx
ivy-sale auth whoami

也可以不落盘，直接用环境变量（适合 CI / 被其他 Agent 当子进程拉起的场景）：

export SALE_AGENT_API_KEY=sk-xxxxxxxx
export SALE_AGENT_BASE_URL=https://api.ivy.sale/open/v1   # 默认值，按需覆盖

CLI 用法

ivy-sale customer list --keyword 张三
ivy-sale customer get 123
ivy-sale customer create --name "某某公司" --phone 138xxxx

ivy-sale todo list --pending
ivy-sale todo add "跟进某某客户" --due "2026-09-05 18:00:00"
ivy-sale todo done 456

ivy-sale knowledge search "退保流程"

所有命令都支持 --json 输出机器可读结构，供脚本/其他 Agent 解析。

作为 MCP Server 使用

{
  "mcpServers": {
    "ivy-sale": {
      "command": "ivy-sale",
      "args": ["mcp", "serve"],
      "env": {
        "SALE_AGENT_API_KEY": "sk-xxxxxxxx",
        "SALE_AGENT_BASE_URL": "https://api.ivy.sale/open/v1"
      }
    }
  }
}

启动时会先用 Token 调用一次 /open/v1/me/info 自检，Token 无效会直接报错退出，不会注册工具。

Phase 1 固定注册 7 个工具（search_customers / get_customer / create_customer / list_todos / create_todo / complete_todo / search_knowledge），不按 Token 的 scope 动态过滤—— 如果 Token 缺少对应权限，调用对应工具时网关会返回 403，工具的返回文本里会带上缺失的 scope 名。

发布（维护者）

python -m pip install --upgrade build twine
python -m build                # 产出 dist/*.whl + dist/*.tar.gz
python -m twine check dist/*   # 校验元数据/README能否被PyPI正常渲染
python -m twine upload dist/*  # 需要 PyPI 账号 + API token(https://pypi.org/manage/account/token/)

发新版本前记得改 pyproject.toml 里的 version（PyPI 不允许覆盖已发布过的版本号）。