MCP+Ollama迷你项目

该项目是用于学习LLM、MCP和Web抓取的Scapold。从URL中提取网页正文，并使用Ollama自动生成摘要和测验。

📖 💻 用户指南 ←在这里确认如何使用程序！

主要功能

✅ 提取HTML正文 — requests + BeautifulSoup通过自动提取网页标题和正文文本

- 选项：支持URL、本地文件和HTML字符串输入 - 输出：纯文本或JSON格式

✅ Ollama LLM集成 -将提取的文本自动摘要为韩文（2-3句）

- Flask API端点： /process （URL输入→提取+摘要）

✅ 自动生成测验 -自动生成5个O/X格式测验（完成）

- 断然的记叙文形式（禁止疑问型） - 纯韩文过滤（去除汉字、外来语） - 自动分配重要性/难度

💾 MCP文件服务器集成 -将标记结果保存到MCP文件系统（即将实施）
🐳 Docker Compose -在本地自动运行所有服务
🔄 GitHub操作CI -推送/PR时自动测试

项目结构

.
├── app/                          # 콘텐츠 추출 & 처리 서비스
│   ├── extract.py               # HTML 본문 추출 로직 (완성)
│   ├── main.py                  # Flask 서버 엔트리포인트
│   ├── requirements.txt
│   └── Dockerfile
├── mcp_server/                   # MCP 파일시스템 HTTP 서버
│   ├── server.py
│   ├── requirements.txt
│   └── Dockerfile
├── tests/                        # 단위 테스트
│   └── test_extract.py          # extract.py 테스트 (2개 케이스, 통과)
├── scripts/                      # 유틸리티 스크립트
│   ├── run_tests.py             # pytest 실행 및 결과 저장
│   └── dump_extract_samples.py  # 샘플 HTML로 추출 결과 확인
├── .github/workflows/
│   └── ci.yml                   # GitHub Actions CI (자동 테스트)
├── docker-compose.yml           # Docker 서비스 정의
├── CONTRIBUTING.md              # 커밋 및 PR 컨벤션
└── README.md                    # 이 파일

快速入门

1.运行本地测试

# 가상환경 생성 및 활성화
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate  # Windows

# 의존성 설치
pip install -r app/requirements.txt
pip install pytest

# 단위 테스트 실행
pytest -q tests/test_extract.py

结果：

.. [100%] 
2 passed

2.提取HTML正文（多种选项）

从URL提取：

cd app
python extract.py 'https://example.com'

从本地文件提取：

cd app
python extract.py --file /path/to/file.html

提取为HTML字符串：

cd app
python extract.py --html '
Hello
'

JSON格式输出：

cd app
python extract.py --file sample.html --json

输出示例：

{
  "title": "Example Domain",
  "text": "This domain is for use in examples...",
  "char_count": 1234
}

3.自动摘要到Ollama

首先，Ollama必须已安装并正在运行。

Ollama安装和型号下载：

# 설치 (macOS)
# 1) ollama.ai에서 다운로드 후 설치
# 2) 또는: brew install ollama

# 모델 다운로드 (처음 1회, ~3.8GB)
ollama pull llama2

# 서버 실행 (백그라운드)
ollama serve &

摘要测试：

# 로컬 HTML로 요약 테스트
python scripts/test_ollama_integration.py

输出示例：

==================================================
[1단계] HTML에서 본문 추출
==================================================
제목: 인공지능의 미래
본문 (처음 200자):
인공지능(AI)은 최근 몇 년간 놀라운 발전을 이루었습니다...

==================================================
[2단계] Ollama로 요약
==================================================
[요청] Ollama (llama2)로 요약 중...
요약:
인공지능(AI)은 최근 몇 년간 놀라운 발전을 이루었습니다. AI는 자연어 처리 기술과 함께 의료, 금융, 교육 등 다양한 분야에서 혁신을 일으키고 있습니다. 하지만, AI의 올바른 활용과 규제의 균형이 중요하다고 전문가들은 강조합니다.

결과 저장됨: .ollama_test.json

启动Flask API服务器后，可以一次处理提取+摘要。

# 루트 디렉토리에서 환경변수 설정
export OLLAMA_HOST=http://localhost:11434
export OLLAMA_MODEL=llama2

# Flask 서버 시작
cd app
python main.py

使用API端点：

健康检查：

curl http://localhost:8000/health

URL提取+摘要（整个管线）：

curl -X POST http://localhost:8000/process \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

示例响应：

{
  "url": "https://example.com",
  "title": "Example Domain",
  "text_length": 1234,
  "summary": "Example 도메인은 예시용으로 사용됩니다. 이 도메인은 인터넷 표준 문서에서 예제로 사용되도록 예약되어 있습니다."
}

仅提取URL（无摘要）：

curl -X POST http://localhost:8000/extract \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

创建O/X测验：

curl -X POST http://localhost:8000/quiz \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

示例响应：

{
  "url": "https://example.com",
  "title": "인공지능의 미래",
  "quiz_count": 4,
  "quiz": [
    {
      "question": "인공지능은 세상을 바꾸고 있다.",
      "answer": true,
      "difficulty": 3,
      "importance": "높음",
      "explanation": "본문의 내용을 근거로 합니다."
    },
    {
      "question": "AI는 의료에서 발전하고 있지 않다.",
      "answer": false,
      "difficulty": 2,
      "importance": "중간",
      "explanation": "본문의 내용을 근거로 합니다."
    }
  ]
}

5.使用Docker Compose运行整个服务

# 루트에서 실행
docker-compose up --build

app 服务：端口8000（Flask API）
mcp_server 服务：端口3000（文件系统HTTP服务器）

设置环境变量 .env.example请参考。

主要文件说明

`app/extract.py`

从网页HTML中提取标题和正文文本的核心模块。

函数：

fetch_html(url, timeout=10) -从URL导入HTML内容
extract_text(html, url=None) -返回HTML中的标题和正文提取（title，text）元组

提取策略：

, ` 搜索标记

搜索id/class包含“content”、“article”、“post”、“entry”和“main”的元素
没有胃的话，所有 `

` 收集标记以提取最长的连续块

最后一种方法：body全文

示例：

from app.extract import extract_text, fetch_html

# URL에서 추출
html = fetch_html('https://example.com')
title, text = extract_text(html)
print(f"제목: {title}")
print(f"본문: {text[:100]}...")

# 로컬 HTML 문자열에서 추출
html_string = '
Hello
'
title, text = extract_text(html_string)

`tests/test_extract.py`

extract_text 测试函数的单位。使用本地HTML示例验证提取逻辑。

测试案例：

test_extract_from_simple_html -使用基于id的选择器提取正文
test_extract_fallback_paragraphs -所有 `

` 提取标记回退

`scripts/test_ollama_integration.py`

测试Ollama联动的脚本。提取本地HTML后，验证用Ollama概括的管线。

动作：

提取用于测试的HTML正文
调用Ollama API进行韩文摘要
结果 .ollama_test.json另存为

运行：

python scripts/test_ollama_integration.py

`app/main.py`

基于Flask的HTTP API服务器。提取网页正文后，自动摘要为Ollama。

函数：

summarize_with_ollama(text) -调用Ollama API，总结2-3句韩文
POST /health -检查服务器状态
POST /process -输入URL→提取+摘要（整个管线）
POST /extract -输入URL→仅提取（无摘要）

环境变量：

OLLAMA_HOST -Ollama服务器地址（默认： http://localhost:11434)
OLLAMA_MODEL -要使用的模型名称（缺省值： llama2)
PORT -Flask端口（默认： 8000)

`.github/workflows/ci.yml`

GitHub Actions自动测试管道。

动作：

生命周期： main 创建分支推送或PR时
환경:Ubuntu最新版本，Python 3.11
步骤：

1. 签出代码 1. 安装Python 3.11 1. 依赖性安装（pip缓存） 1. pytest -q 执行

结果：在GitHub UI中显示/

下一步

优先级	任务状态	说明
1	创建测验	完成	O/X格式5个，汉字过滤，重要度/难度自动分配
2	API测试	📝 正在进行中Flask `/quiz` 端点本地测试
3	MCP集成	计划	将结果保存为标记并上传到MCP文件服务器
4	Stage2增强功能	计划	提取更准确的关键词，检测核心概念，改进JSON响应
5	测试扩展	预定	韩文编码、空白正文、脚本删除等Edge案例

Stage1完成项目：

提取HTML（URL，文件，HTML字符串）
Ollama摘要（韩文2-3个句子）
生成O/X测验（4-5个）

- 只有坚决的陈述句（消除疑问句） - 仅纯韩文（过滤汉字/外来语） - 自动分配重要性/难度

✅ API弗拉斯克(/health, /extract, /process, /quiz)
✅ GitHub操作CI
单位测试

______________________________________________________________________

📋 改进（基于用户反馈）

🔴 高优先级（Core UX增强）

1. 隐藏测验答案（必需）

问题： 直接显示当前答案（用户无法先解答）
解决方案： 添加正确答案按钮→点击时公开正确答案
影响： 测验功能的关键改进
预计难度： 中间（React状态管理）

2. 删除提取功能并简化UI

问题： 不需要提取功能，容易混淆
解决方案： /extract 删除端点，删除前端“提取”按钮
更改后： 摘要→只显示2个测验
影响： 简化UI，消除用户混淆
预计难度： 低（简单的删除操作）

3. 正确答案消除重复标记

问题： 以“正确答案：⭕O”格式显示双重
解决方案： 实施“公开答案”按钮时，只显示“O”或“X”之一
影响： UX改进
预计难度： 低

4. 明确“高/中/低”标签

问题： 用户不知道意义（“高”是什么？）
解决方案： 在标签上添加说明（鼠标悬停时显示“重要程度：本文讨论的程度”）
替代方案： 向徽章添加“重要性”标签文本
预计难度： 低

🟡 中优先级（质量改进）

5. 改善解释（Explanation）质量

问题： “以本文内容为依据”等简陋的解说
解决方案： AI提示改进

- 引用具体的正文句子 - “为什么这个答案是对的”解释 - 如“句子‘~是~’中所示……”

影响： 提高学习效果
预计难度： 高（Ollama提示工程）

6. 优化PC屏幕

问题： UI以移动为中心设计
解决方案：

- 桌面（1200px+）：两级布局（输入+结果并排） - 答题卡：更大的字体，宽松的羽绒服 - 调整按钮大小

预计难度： 中间（添加CSS媒体查询）

7. 修改说明文本

问题： “网络文章”→需要更改为一般内容
解决方案：

- 标题：“网络文章→自动摘要&测验”→“内容→自动摘要&测验” - 指南文本：“网站”、“网页”→“内容”、“URL”

预计难度： 低

🟢 低优先级（技术审查）

8. Rolldown-Vite技术堆栈审查

问题： 正在使用新的滚动（Rolldown），长期支持不确定
审阅：

- 可能需要迁移到标准Vite - 监控未来兼容性问题

预计难度： 高（转换为捆绑包）
时间： 稳定后Stage2

______________________________________________________________________

开发路线图

第1阶段：必要的UX改进（本次Sprint）

1순위: 퀴즈 정답 숨기기 & 공개 버튼 → [정답 보기]
2순위: 추출 기능 제거 (간단함)
3순위: PC UI 최적화
4순위: 라벨 명확화 ("중요도", "관련도" 추가)

第2阶段：提高质量（下一步冲刺）

- AI 해설 프롬프트 개선
- 설명 텍스트 일관성 수정
- 모바일/PC 최종 테스트

第3阶段：高级功能（第2阶段）

- MCP 파일서버 연동
- 퀴즈 풀이 기능 (정답 저장, 점수 계산)
- 히스토리/통계
- 데이터베이스 연동

贡献

贡献.md请参考。主要会议：

提交格式： 유형(범위): 설명 （例如： 기능(extract): 인코딩 개선)
测试：PR之前 pytest -q 执行
分支：创建功能性分支后PR

设置环境变量

.env.example的 .env请复制到进行设置。

cp .env.example .env

主要环境变量：

OLLAMA_HOST=http://localhost:11434 -Ollama服务器地址
OLLAMA_MODEL=llama2 -要使用的模型
PORT=8000 -Flask端口
MCP_HOST=http://localhost:3000 -MCP服务器地址（未来）

许可证

MIT（或项目许可证）

MCP LLM Project

快速接入

详细介绍