内容
<a id="readme-top"></a>
<div align="center">
[![Python][python-shield]][python-url]
[![FastAPI][fastapi-shield]][fastapi-url]
[![MCP][mcp-shield]][mcp-url]
[![LangChain][langchain-shield]][langchain-url]
[![Playwright][playwright-shield]][playwright-url]
[![Ollama][ollama-shield]][ollama-url]
[![License][license-shield]][license-url]
</div>
<br />
<div align="center">
<h3 align="center">Hanime1 MCP</h3>
<p align="center">
面向 AI 编程助手的 Hanime1 资源 MCP/Agent。
<br />
支持自然语言搜索、候选确认、视频解析、下载队列、断点续传、持久化记录和向量记忆。
<br />
<br />
<a href="#在-claude-code-中使用"><strong>Claude Code 接入</strong></a>
·
<a href="#在-cursor--trae--opencode-中使用">Cursor / Trae / opencode</a>
·
<a href="#mcp-工具">MCP 工具</a>
</p>
</div>
## 主要能力
- MCP Server：可接入 Claude Code、Cursor、Trae、opencode 等支持 MCP 的编程助手。
- LangChain Agent：使用 Ollama 本地模型做结构化意图解析和候选排序。
- 搜索与解析：站内搜索、分类/排序搜索、播放页视频源解析。
- 下载队列：并发下载、`.part` 断点续传、完成后自动落盘为 `.mp4`。
- 本地记忆：SQLite 保存资源、任务和事件；向量索引用于历史语义检索。
## 环境准备
需要：
- Python 3.10+
- [uv](https://docs.astral.sh/uv/)
- [Ollama](https://ollama.com/)
安装依赖：
```powershell
cd F:\MyProject\AI-Mcp\hanime\hanime-agent
uv sync --extra all
uv run playwright install chromium
```
准备本地模型：
```powershell
ollama pull qwen3:1.7b
ollama pull nomic-embed-text
```
复制配置：
```powershell
Copy-Item .env.example .env
```
默认配置使用：
```env
HANIME_AGENT_LLM_PROVIDER=ollama
HANIME_AGENT_LLM_MODEL=qwen3:1.7b
HANIME_AGENT_EMBEDDING_MODEL=ollama:nomic-embed-text
HANIME_AGENT_OLLAMA_BASE_URL=http://127.0.0.1:11434
```
## 在 Claude Code 中使用
先删除旧配置，再添加新的 MCP：
```powershell
claude mcp remove hanime-agent
claude mcp add -s user -t stdio hanime-agent "F:\MyProject\AI-Mcp\hanime\hanime-agent\run-mcp.cmd"
```
检查：
```powershell
claude mcp list
claude mcp get hanime-agent
```
进入 Claude Code 后输入：
```text
/mcp
```
确认 `hanime-agent` 已连接后即可自然语言调用：
```text
用 hanime-agent 帮我找”告白…… 1”相关资源，列出候选让我确认。
```
确认下载：
```text
下载第 1 个，1080p。
```
也可以明确指定 MCP 工具：
```text
调用 hanime-agent 的 chat_hanime_agent，message 为“帮我找最近的 3DCG 资源，列出前 8 个”。
```
## 在 Cursor / Trae / opencode 中使用
把下面的 MCP 配置加入对应客户端的 MCP 配置文件：
```json
{
"mcpServers": {
"hanime-agent": {
"command": "F:/MyProject/AI-Mcp/hanime/hanime-agent/run-mcp.cmd"
}
}
}
```
如果客户端不接受 `.cmd` 作为 command，可以改用：
```json
{
"mcpServers": {
"hanime-agent": {
"command": "uv",
"args": ["run", "--extra", "mcp", "--extra", "langchain", "hanime-agent", "mcp"],
"cwd": "F:/MyProject/AI-Mcp/hanime/hanime-agent"
}
}
}
```
## MCP 工具
- `chat_hanime_agent`：主入口，多轮自然语言搜索、候选确认、下载。
- `search_hanime`：直接搜索资源。
- `inspect_hanime_video`：解析单个播放页。
- `download_hanime_video`：直接创建下载任务。
- `semantic_history_search`：搜索本地向量化历史记录。
## 本地调试
启动 MCP Server：
```powershell
.\run-mcp.cmd
```
启动 FastAPI：
```powershell
uv run hanime-agent serve-api
```
CLI 示例：
```powershell
uv run hanime-agent ask "帮我找 MMD 最近资源，列出前 5 个"
uv run hanime-agent download "https://hanime1.me/watch?v=406271" --resolution 1080p
```
运行测试：
```powershell
uv run --extra dev pytest -q
uv run --extra dev ruff check .
```
## 许可证
MIT License，详见 [LICENSE](LICENSE)。
## 免责声明
本项目仅供技术学习与个人自动化研究。请遵守目标站点条款、版权要求和所在地法律法规，只下载你有权保存的内容。
[python-shield]: https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white
[python-url]: https://www.python.org/
[fastapi-shield]: https://img.shields.io/badge/FastAPI-API-009688?logo=fastapi&logoColor=white
[fastapi-url]: https://fastapi.tiangolo.com/
[mcp-shield]: https://img.shields.io/badge/MCP-Server-111827
[mcp-url]: https://modelcontextprotocol.io/
[langchain-shield]: https://img.shields.io/badge/LangChain-Agent-1C3C3C
[langchain-url]: https://www.langchain.com/
[playwright-shield]: https://img.shields.io/badge/Playwright-Chromium-2EAD33?logo=playwright&logoColor=white
[playwright-url]: https://playwright.dev/python/
[ollama-shield]: https://img.shields.io/badge/Ollama-qwen3%3A1.7b-000000
[ollama-url]: https://ollama.com/
[license-shield]: https://img.shields.io/badge/License-MIT-green
[license-url]: LICENSE
