Metadata-Version: 2.4
Name: ivy-sale-cli
Version: 0.1.2
Summary: CLI + MCP Server client for the ivy-sale open platform
Author: Profly
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: typer>=0.12
Requires-Dist: mcp>=2.0
Requires-Dist: pydantic>=2.0

# 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 后（见文末「发布」），终端用户直接：

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

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

```bash
pip install -e .
```

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

## 登录

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

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

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

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

## CLI 用法

```bash
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 使用

```json
{
  "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 名。

## 发布（维护者）

```bash
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 不允许覆盖已发布过的版本号）。
