Veritable Records Of The Joseon Dynasty Search Tool

朝鲜王朝实录检索工具

项目背景

该项目提供了一个模型上下文协议（MCP）服务器，用于搜索 Veritable Records of the Joseon Dynasty（朝鲜王朝实录），韩国最重要的历史文献之一。它充当着包裹 韩国经典数据库（DB.itkc.or.kr），使现代人工智能助手和其他编程工具能够访问这一宝贵资源。

研究人员、历史学家和爱好者可以使用此服务器执行查询、检索全文文章，并将年鉴数据集成到自己的工作流程中，而无需直接抓取网站。

工具：

• search_joseon_annals_tool：按关键字搜索文章，并使用特定国王的过滤器。
• fetch_joseon_annals_article_tool：检索一篇文章的全文，包括现代韩语翻译和文言文原文。

项目结构

.
├── src/
│   ├── config/
│   │   └── settings.py      # Configuration settings
│   ├── schemas.py           # Pydantic data models
│   ├── server.py            # Main FastMCP server
│   └── tools/
│       └── silloc_search.py # Core search and fetch logic
├── docker-compose.yaml      # Docker Compose configuration
├── Dockerfile               # Docker container definition
├── Makefile                 # Make commands for development
├── pyproject.toml           # Python dependencies
├── requirements.txt         # Python dependencies for Render deployment
├── runtime.txt              # Python version for Render deployment
└── README.md

工具

1. search_joseon_annals_tool

此工具允许您在年鉴中搜索文章。

• 功能：按韩语关键字搜索。您可以选择将搜索筛选到特定国王的编年史。
• 输入: query （str）， search_field （str，可选）， king_name （str，可选）， start （int，可选）， rows （int，可选）。
• 输出：列表 ClassicDocument 对象，包括标题、片段，最重要的是 document_id 对于每一篇文章。

2. fetch_joseon_annals_article_tool

一旦你有一个 document_id 从搜索工具中，您可以使用此工具获取完整内容。

• 功能：检索单个文章的完整文本。
• 输入: document_id （str）。
• 输出A. ClassicDocumentDetail 对象包含：

- translation_paragraphs：现代朝鲜语段落列表。 - original_paragraphs：文言文原文段落列表。 - text_url 和 image_url：直接链接到源网站上的文章。

工作流示例

1. 呼叫 search_joseon_annals_tool 使用类似的查询 "정도전".
2. 从结果中选择一个文档并获取其 document_id.
3. 呼叫 fetch_joseon_annals_article_tool 说完这个 document_id 阅读全文。

托管版本

此MCP服务器的可流式HTTP版本公开托管在Render上：

统一资源定位符: https://veritable-records-of-the-joseon-dynasty.onrender.com/mcp

请注意，这是在免费层上运行的，这意味着如果服务处于空闲状态，启动速度可能会很慢。

入门指南

先决条件

• 码头工人:
• 制造：应预先安装在macOS/Linux上。

运行服务器

所有命令都从主机的终端运行。

1. 构建Docker镜像

   make build

1. 在HTTP模式下运行（用于生产/本地web访问）

服务器将在以下时间以HTTP模式启动 http://localhost:8000.

   make run

1. 在STDIO模式下运行（用于使用MCP检查器进行本地测试）

此模式允许使用以下工具进行交互式测试 MCP检查员. 首先，确保Docker容器正在运行（例如，通过运行 make run 或 make run-interactive 在单独的终端中）。 然后，执行 run_server.sh 附加到正在运行的容器并在STDIO模式下启动服务器的脚本：

   ./run_server.sh

（您可能需要使脚本可执行： chmod +x run_server.sh) （新闻 Ctrl+F 如果使用交互式客户端，则专注于终端并与STDIO流交互。)

使用与测试

运行测试

目前，该项目还没有自动化测试。

Docker&Make

我们使用 docker 和 make 简化发展。共同 make 命令：

• make build：构建Docker镜像。
• make run：以HTTP模式启动MCP服务器。
• make run-interactive：在容器中启动交互式bash会话。
• make clean：清理Docker镜像和容器。

这 Makefile 包含每个命令的详细信息。

技术细节

环境

开发完全在Docker容器中完成，以确保一致性。

包管理

我们使用 紫外线 用于Python环境和包管理 _集装箱内_.关键依赖关系定义见 pyproject.toml:

• fastmcp
• pydantic
• beautifulsoup4
• requests