Metadata-Version: 2.4
Name: astron-zhihu-mcp
Version: 0.1.5
Summary: Astron-Zhihu-MCP: 基于知乎游客态公开接口的自包含 MCP Server，支持 MCP 协议和 uvx 一键启动。
Author: iFlytek Astron Team
License-Expression: Apache-2.0
Keywords: astron,zhihu,mcp
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: requests>=2.31.0
Dynamic: license-file

# 知乎公开内容 MCP Server

## 概述

`Astron-zhihu-mcp` 是一个基于 MCP 协议的知乎工具服务，直接调用知乎游客态公开接口获取公开内容，无需额外部署后端服务。

当前提供 5 个原子工具：
- `get_hot_list`
- `get_feed_list`
- `search_content`
- `get_content_detail`
- `get_author_profile`

## 工具列表

### 1. 获取热榜 `get_hot_list`
- 参数：`limit`、`refresh`

### 2. 获取信息流 `get_feed_list`
- 参数：`channel`、`cursor`、`limit`、`refresh`

### 3. 搜索内容 `search_content`
- 参数：`query`、`cursor`、`limit`、`real_only`、`allow_fallback`

### 4. 获取内容详情 `get_content_detail`
- 参数：`content_id`、`url`

### 5. 获取作者主页 `get_author_profile`
- 参数：`author_id`、`url`

## 环境变量

```bash
export ZHIHU_MCP_TIMEOUT_SECONDS="30"
export ZHIHU_MCP_USER_AGENT="Mozilla/5.0 ..."
export ZHIHU_MCP_COOKIE="z_c0=...; d_c0=...; q_c1=..."
export ZHIHU_MCP_PREWARM_HOME="1"
export ZHIHU_MCP_CACHE_PATH="/tmp/zhihu_mcp_cache.json"
export ZHIHU_MCP_CACHE_TTL_SECONDS="1800"
export ZHIHU_MCP_CACHE_MAX_ITEMS="800"
export ZHIHU_MCP_FALLBACK_FEED_SCAN_PAGES="4"
export ZHIHU_MCP_FALLBACK_FEED_PAGE_SIZE="20"
```

说明：
- `ZHIHU_MCP_COOKIE`：可选，知乎登录态 Cookie 原文（`key=value; key2=value2`），用于降低 401/403 风控概率。
- `ZHIHU_MCP_PREWARM_HOME`：是否启用首页预热（默认 `1`）。预热后再请求公开 API，降低风控触发概率。
- `ZHIHU_MCP_CACHE_PATH`：本地轻量缓存文件路径。
- `ZHIHU_MCP_CACHE_TTL_SECONDS`：缓存生存时间（秒）。
- `ZHIHU_MCP_CACHE_MAX_ITEMS`：缓存内容项上限。
- `ZHIHU_MCP_FALLBACK_FEED_SCAN_PAGES`：游客态 fallback 时扫描推荐流页数（1-12）。
- `ZHIHU_MCP_FALLBACK_FEED_PAGE_SIZE`：游客态 fallback 每页抓取条数（5-50）。

## 安装与启动

### 使用 uvx

```bash
uvx --from astron-zhihu-mcp astron-zhihu-mcp
```

### 使用 pip 安装

```bash
pip install astron-zhihu-mcp
zhihu-mcp
```

### 本地源码运行

```bash
cd MCP/zhihu-mcp
PYTHONPATH=src python3 -m zhihu_mcp.server
```

## 客户端配置

```json
{
  "mcpServers": {
    "zhihu-mcp": {
      "command": "python3",
      "args": ["-m", "zhihu_mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/MCP/zhihu-mcp/src",
        "ZHIHU_MCP_TIMEOUT_SECONDS": "30",
        "ZHIHU_MCP_COOKIE": "z_c0=...; d_c0=..."
      }
    }
  }
}
```

## 平台差异说明

1. 默认策略为 JSON API 优先，失败后回退 HTML 解析。
2. `search_content` 默认只返回真实搜索内容；搜不到时返回结构化空列表。
3. `allow_fallback` 当前仅保留兼容参数位，默认实现不再用 `suggest`、热榜/推荐流、缓存扫描等降级来源顶替搜索结果。
4. 作者内容列表回退链支持 `members/{id}/pins`（`raw.source=member_pins_api`）与热榜/推荐流作者聚合。
5. 内置轻量本地缓存（单文件 JSON），在风控场景下可用于回退返回历史公开数据。
6. 内容详情与作者内容列表在强风控下可能返回最小结构（如 `fallback_minimal` / `empty_fallback`），用于保证工具可调用与响应结构稳定。
7. 仅面向公开内容能力，不包含登录态与私有数据。

## License

Apache License 2.0. See `LICENSE`.
