tyc-cli 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -23,6 +23,19 @@
 
 - 默认 stdout 由紧凑单行 JSON 改为缩进 2 空格 JSON。需要旧默认行为的脚本请显式加 `--compact`
 
+## [0.3.4] - 2026-05-28
+
+### 变更
+
+- 更新 CLI catalog 中部分搜索类工具的 help/参数说明，使命令语义与 MCP Server 实际参数映射一致：
+  - `companies-by-industry-region`：明确 `industry` 为国标行业代码，`region` 为地区代码
+  - `companies-by-ranking`：明确按企业名称、统一社会信用代码或天眼查企业 ID 查询企业上榜榜单
+  - `companies-by-tag`：明确未传 `tag` 时使用 `searchKey` 作为标签名称
+  - `listed-companies`：明确按企业名称、统一社会信用代码或天眼查企业 ID 搜索上市公司信息
+  - `search-patents` / `search-trademarks`：说明 `applicant` 会作为关键词按申请人字段搜索，不是与 `searchKey` 叠加的二次过滤
+  - `search-bids`：说明 `purchaser` 的搜索语义，并明确 `bidType` 支持的公告类型枚举
+- 版本号提升至 `0.3.4`。
+
 ## [0.3.0] - 2026-04-29
 
 ### 新增

package/README.md

@@ -15,12 +15,17 @@
 Streamable HTTP）调用天眼查 162 个业务语义聚合工具，覆盖企业工商、知产、司法风险、
 董监高等全维度商业数据。
 
+当前 MCP Server 的 `tools/list` 默认只公开少量 AI Agent 入口工具
+（搜索、公司画像、能力目录、`call_tool` / `call_tools_batch` 等），但 162 个业务语义
+工具仍注册在服务端并保持 `tools/call` 兼容。CLI 不依赖 `tools/list` 构建命令树，
+而是使用打包内 `catalog.json` 直达这些业务工具。
+
 **核心特点**：
 
 - 🧠 **MCP 客户端架构**：CLI 只做协议转换与参数透传；多源合并、时间戳格式化、
   空结果归一化、`_summary` 注入等业务逻辑由 MCP Server 完成
-- 🔌 **即插即用**：默认连接官方 MCP 端点 `https://mcp.tianyancha.com/v1`；
-  支持 `--url` 指向私有部署
+- 🔌 **公网优先**：默认连接天眼查 MCP 端点 `https://mcp.tianyancha.com/mcp`；
+  支持 `--url` 指向本地或私有部署
 - 🔄 **Session 复用**：`Mcp-Session-Id` 本地缓存 24 小时，后续调用零 initialize 开销
 - 🎯 **6 大业务分类 / 162 个工具**：企业基础信息 · 风险合规 · 知识产权 · 经营与公示 · 历史信息 · 董监高
 - 🤖 **AI Agent 友好**：tyc 英文 key 透传 / 时间戳格式化 / `_summary / _empty / _warnings` 元数据
@@ -49,16 +54,23 @@ npm install && npm run build && npm link
 ### 3. 初始化配置
 
 ```bash
-# 连接官方 MCP（默认）
-tyc init --authorization "YOUR_API_TOKEN"
+# 连接官方 MCP（默认）：浏览器 OAuth 登录
+tyc login
 
-# 连接自建 MCP
-tyc init --authorization "YOUR_API_TOKEN" --url "http://your-mcp-host:8080/v1"
+# 连接预发 / 本地 / 自建 MCP
+tyc login --url "https://ai-mcp-pre.tianyancha.com/mcp"
+tyc login --url "http://localhost:8080/mcp" --issuer "http://localhost:8080/oauth"
+
+# API key 兼容路径：已有天眼查 OpenAPI token 时可直接写入
+tyc init --authorization "YOUR_API_TOKEN"
 
 # 仅写配置、不校验（离线环境或先配好稍后上线）
 tyc init --authorization "YOUR_API_TOKEN" --no-verify
 ```
 
+> `tyc login` 会从 MCP protected-resource metadata 发现 OAuth 授权服务器，启动本地
+> loopback 回调，使用 PKCE 授权码流程打开浏览器登录；成功后自动把
+> `Authorization: Bearer <access_token>` 写入 `~/.tyc/config.json`。
 > `tyc init` 保存配置后会立即向 MCP 发一次 `initialize`：成功则打印 `已建立 MCP session`，
 > 失败则退出码 1 并提示连通性问题。加 `--no-verify` 可跳过校验。
 
@@ -66,9 +78,9 @@ tyc init --authorization "YOUR_API_TOKEN" --no-verify
 
 ```json
 {
-  "url": "https://mcp.tianyancha.com/v1",
+  "url": "https://mcp.tianyancha.com/mcp",
   "headers": {
-    "Authorization": "YOUR_API_TOKEN"
+    "Authorization": "Bearer <OAuth_ACCESS_TOKEN>"
   }
 }
 ```
@@ -89,6 +101,8 @@ tyc executive personnel-dishonest "..." --humanName "张三"
 
 | 命令 | 说明 |
 |------|------|
+| `tyc login` | 浏览器 OAuth 登录；自动发现 metadata、使用 PKCE 获取 access token 并写入配置 |
+| `tyc login --url <url>` | 对指定 MCP endpoint 发起 OAuth 登录 |
 | `tyc init --authorization <token>` | 写入 `headers.Authorization`；保存后会立即向 MCP 发一次 `initialize` 校验连通性 |
 | `tyc init --url <url>` | 设置 MCP endpoint |
 | `tyc init --header K=V` | 注入自定义 header（可重复）；值留空则删除该 key |
@@ -164,7 +178,7 @@ tyc company registration-info "百度" --compact | jq .name
 
 ## 📚 查询指令手册
 
-### 企业基础信息（company，50）
+### 企业基础信息（company，49）
 
 ```bash
 tyc company registration-info "北京百度网讯科技有限公司"   # 工商登记
@@ -173,13 +187,13 @@ tyc company beneficial-owners "..."                       # UBO
 tyc company key-personnel "..."                           # 主要人员
 tyc company annual-reports "..."                          # 企业年报
 tyc company financial-data "..."                          # 财务数据（上市/非上市自动回退）
-tyc company accuracy "..." --legalPersonName "梁志祥"     # 三要素核验
+tyc company accuracy "北京百度网讯科技有限公司" --companyCode "91110000802100433B" --legalPersonName "梁志祥"  # 三要素核验
 tyc company equity-tree "..."                             # 股权图谱
 tyc company relation-path "A" --searchKey2 "B"            # 双企业最短路径
 tyc company group-info "..."                              # 集团信息（serial 串行执行）
 ```
 
-### 风险合规（risk，36）
+### 风险合规（risk，35）
 
 ```bash
 tyc risk dishonest-info "..."                  # 失信被执行
@@ -214,7 +228,7 @@ tyc operation invest-agency-profile "红杉资本"         # 投资机构
 tyc operation private-fund-profile "..."               # 私募基金
 ```
 
-### 历史信息（history，18）
+### 历史信息（history，17）
 
 ```bash
 tyc history historical-registration "..."
@@ -241,7 +255,7 @@ tyc executive person-risk-overview "..." --humanName "张三"
 ```
 ┌─────────────┐         ┌─────────────────────────────┐         ┌─────────────────┐
 │   tyc-cli   │ ──JSON──▶│  天眼查 MCP Server           │ ──HTTP──▶│ tyc OpenAPI     │
-│ (npm / TS)  │ ◀───RPC──│  (mcp.tianyancha.com/v1) │ ◀───────│                 │
+│ (npm / TS)  │ ◀───RPC──│  (mcp.tianyancha.com/mcp) │ ◀───────│                 │
 └─────────────┘         └─────────────────────────────┘         └─────────────────┘
        │                              │
        │                              └─ 多源并发聚合 · 时间戳格式化 · _summary 注入 · 空结果归一化
@@ -254,7 +268,7 @@ tyc executive person-risk-overview "..." --humanName "张三"
 1. 解析命令行（commander）
 2. 组装 `tools/call` JSON-RPC 请求，透传 `Authorization` header
 3. Session 管理（`initialize` + 24h 缓存 + 失效重建）
-4. 解析 MCP Streamable HTTP 响应（纯 JSON 或 SSE）
+4. 解析 MCP Streamable HTTP 响应（当前服务端返回单包 JSON）
 5. 格式化输出（默认 pretty / `--compact` / `--md`），并可叠加 `--head/--tail/--full/--threshold/--output-file` 做截断与落盘
 
 **CLI 不做**：
@@ -282,10 +296,12 @@ tyc-cli/
     ├── config.ts             # ~/.tyc/config.json 读写 · 环境变量兜底
     ├── session.ts            # ~/.tyc/session.json 读写 · 24h TTL
     ├── mcpClient.ts          # MCP JSON-RPC client · SSE 解析 · 失效重建
+    ├── oauth.ts              # OAuth metadata discovery · PKCE · loopback callback
     ├── registry.ts           # 读取打包内 catalog.json（命令树元数据）
     ├── catalog.json          # 命令元数据：name / group / cliMethod / params
     ├── commands/
     │   ├── init.ts           # tyc init
+    │   ├── login.ts          # tyc login
     │   └── category.ts       # 动态注册 6 分类 × N 方法
     └── utils/
         ├── jsonToMarkdown.ts # --md 选项的 Markdown 渲染
@@ -308,7 +324,7 @@ tyc-cli/
 
 ```json
 {
-  "url": "https://mcp.tianyancha.com/v1",
+  "url": "https://mcp.tianyancha.com/mcp",
   "sessionId": "mcp-session-xxx",
   "initializedAt": 1777272039739,
   "protocolVersion": "2024-11-05"
@@ -342,7 +358,7 @@ tyc-cli/
 | 协议 | MCP client（JSON-RPC over Streamable HTTP） | MCP server |
 | 实现 | TypeScript | Go |
 | 职责 | 命令树 · 参数透传 · 格式化输出 | 多源聚合 · 时间戳格式化 · 元数据注入 · Authorization 透传至 OpenAPI |
-| 运维 | 用户本地安装 | 官方托管 `mcp.tianyancha.com`，或用户自建 |
+| 运维 | 用户本地安装 | 默认连接官方托管 `mcp.tianyancha.com`，也可切到本机 apimcp 或用户自建 |
 
 CLI 和 MCP Server 共享同一 162 工具清单；工具元数据从打包内的 `catalog.json`
 读取，保证命令树冷启动零网络开销。
@@ -367,7 +383,7 @@ bash test/t1_1/cli/run_t1_1.sh -o -v
 MCP_URL=https://my-mcp.example.com/mcp AUTH_TOKEN=xxx bash test/t1_1/cli/run_t1_1.sh
 ```
 
-`-o` = `--online`，切到 `https://mcp.tianyancha.com/v1`；`-v` = `--verbose`。
+`-o` = `--online`，切到 `https://mcp.tianyancha.com/mcp`；`-v` = `--verbose`。
 单分类脚本加 `-p` 可独立触发 preflight：`bash test/t1_1/cli/test_company.sh -p -o`。
 
 ---