Scp Zim MCP Server

SCP-ZIM-MCP-Server

一个基于 MCP (Model Context Protocol) 的 SCP 基金会文档处理服务器，用于从 ZIM 文件中提取 SCP 文档并转换为 Markdown 格式。

概述

该项目提供了一个 MCP 服务器，能够：

• 从 SCP 基金会的 ZIM 离线文档中提取特定 SCP 项目内容
• 处理 HTML 内容并转换为 Markdown 格式
• 提取和保存图片资源
• 为 AI 助手和知识管理工具提供标准化的 SCP 文档访问接口

功能特性

• ZIM 文件读取: 支持读取 SCP 基金会离线计划提供的 ZIM 格式文档
• HTML 处理: 自动处理和清理 HTML 内容，提取核心文档内容
• Markdown 转换: 将 SCP 文档转换为结构化的 Markdown 格式
• 图片提取: 自动提取并保存文档中的图片资源
• MCP 协议支持: 通过 MCP 协议为 AI 助手提供工具接口

项目结构

SCP-ZIM-MCP-Server/
├── src/
│   ├── main.py                 # MCP 服务器主程序
│   ├── handle_zim/
│   │   └── readzim.py         # ZIM 文件读取处理
│   └── html_parser/
│       └── html_processor.py   # HTML 内容处理
├── .env.example               # 环境变量示例
├── .env                       # 环境变量配置
├── pyproject.toml            # 项目依赖配置
├── README.md                 # 项目文档
└── LICENSE                   # 许可证

安装与配置

环境要求

• Python 3.8+
• SCP 基金会 ZIM 文件（可从 SCP基金会离线计划 获取）

安装依赖

使用 uv 启动项目：

uv run src/main.py

环境配置

1. 复制环境变量示例文件：

cp .env.example .env

1. 编辑 .env 文件，设置必要的环境变量：

# SCP ZIM 文件路径
SCP_OFFLINE_ZIM_PATH=/path/to/scp-wiki_zh_all_2024-10.zim

# Markdown 输出目录
SCP_MD_OUTPUT_DIR=/path/to/output/directory

使用方法

启动 MCP 服务器

python src/main.py

服务器将在 http://0.0.0.0:8765 上启动，使用 SSE (Server-Sent Events) 传输协议。

MCP 工具

服务器提供以下 MCP 工具：

make_md(scp_id)

从 ZIM 文件中提取指定 SCP 项目的内容并生成 Markdown 文件。

参数：

• scp_id (str): SCP 项目 ID，如 "scp-001", "scp-173", "scp-8002"

返回：

• 生成的 Markdown 内容

示例：

# 提取 SCP-173 的文档
content = make_md("scp-173")

read_md(scp_id)

读取已生成的 SCP Markdown 文件。

参数：

• scp_id (str): SCP 项目 ID，如 "scp-001", "scp-173", "scp-8002"

返回：

• Markdown 文件的完整内容

示例：

# 读取 SCP-173 的 Markdown 文档
content = read_md("scp-173")

工作流程

1. 提取文档: 使用 make_md() 工具从 ZIM 文件中提取 SCP 文档
2. 生成 Markdown: 自动处理 HTML 内容并转换为 Markdown 格式
3. 保存资源: 提取并保存文档中的图片到指定目录
4. 读取文档: 使用 read_md() 工具读取生成的 Markdown 文件

核心组件

ReadZIM 类

负责 ZIM 文件的读取和内容提取：

zim = ReadZIM(zim_file_path)
zim.read_zim()
content = zim.get_content(scp_id)

SCPHtmlProcessor 类

处理从 ZIM 文件中提取的 HTML 内容：

html_processor = SCPHtmlProcessor()
html_processor.process_html(content)
img_sources = html_processor.extract_image_sources()

配置选项

相关项目

• SCP-Obsidian: 使用此 MCP 服务器构建 SCP 基金会 Obsidian 知识图谱的工具

许可证

本项目采用 LICENSE 许可证。

贡献

欢迎提交 Issue 和 Pull Request 来改进此项目。

支持

如果您遇到问题或有建议，请在 GitHub 上创建 Issue。