Harvard Library MCP

哈佛图书馆MCP服务器

哈佛大学图书馆API目录的模型上下文协议（MCP）服务器，为人工智能助手提供全面的书目搜索和元数据检索功能。

✨ 特性

• 🔍 综合搜索：免费文本搜索、高级现场搜索、特定收藏查询
• 📚 元数据：具有结构化JSON转换的原生MODS XML格式
• 🔌 通用集成：用于Claude Desktop、Cherry Studio和其他AI助手的stdio MCP传输
• ⚡ 高性能：异步HTTP客户端，内置速率限制和错误处理
• 🌐 访问超过2000万条记录：搜索哈佛大学全部学术图书馆藏书
• 📖 完整元数据：访问书目记录、主题标题和馆藏信息

🚀 快速开始

从PyPI安装

pip install harvard-library-mcp

使用AI助手

樱桃工作室集成

Cherry Studio提供原生MCP服务器支持，可与哈佛图书馆目录无缝集成。

先决条件：

• Cherry Studio已安装在您的系统上
• harvard-library-mcp 通过安装的软件包 pip install harvard-library-mcp

步骤1：安装MCP环境

1. 开放樱桃工作室→ 设置→ MCP服务器
2. 点击“安装”以自动安装所需的依赖项
3. 如果安装失败，请手动安装到Cherry Studio目录：

- 视窗: C:\Users\{username}\.cherrystudio\bin - macOS/Linux: ~/.cherrystudio/bin

步骤2：配置哈佛图书馆MCP服务器 Cherry Studio可以使用标准的MCP配置格式。将以下内容添加到Cherry Studio MCP设置中：

{
  "mcp": {
    "servers": {
      "harvard-library": {
        "command": "uvx",
        "args": ["harvard-library-mcp"],
        "env": {}
      }
    }
  }
}

步骤3：开始使用

1. 重新启动Cherry工作室
2. 哈佛图书馆的工具将在您的聊天界面中提供
3. 尝试以下查询：

- “搜索有关机器学习的书籍” - “在哈佛收藏中找到莎士比亚的作品” - “给我看看哈佛美术图书馆的记录”

Claude桌面集成

添加到您的 claude_desktop_config.json:

{
  "mcp": {
    "servers": {
      "harvard-library": {
        "command": "uvx",
        "args": ["harvard-library-mcp"]
      }
    }
  }
}

配置文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

标准MCP配置

对于任何兼容MCP的客户端，请使用以下JSON配置格式：

{
  "mcp": {
    "servers": {
      "harvard-library": {
        "command": "uvx",
        "args": ["harvard-library-mcp"],
        "env": {}
      }
    }
  }
}

配置选项：

• command：要运行的命令(uvx 用于从PyPI包运行）
• args：包名称和其他参数(["harvard-library-mcp"])
• env：服务器进程的环境变量（可选）

自定义设置示例：

{
  "mcp": {
    "servers": {
      "harvard-library": {
        "command": "uvx",
        "args": ["harvard-library-mcp"],
        "env": {
          "LOG_LEVEL": "DEBUG",
          "RATE_LIMIT_REQUESTS_PER_SECOND": "5"
        }
      }
    }
  }
}

注： 使用 uvx harvard-library-mcp 是推荐的方法，因为它自动处理虚拟环境和PyPI的依赖关系。

地方发展

# Clone and install in development mode
git clone https://github.com/kltng/harvard-library-mcp.git
cd harvard-library-mcp
pip install -e .

# Run as MCP server (stdio)
python -m harvard_library_mcp.server

🛠️ 可用的MCP工具

🔍 搜索工具

• search_catalog(query) -在整个哈佛图书馆目录中进行免费文本搜索
• search_by_title(title) -按标题字段专门搜索
• search_by_author(author) -按作者/创作者姓名搜索
• search_by_subject(subject) -按主题标题和关键字搜索
• advanced_search(filters) -具有特定过滤器（标题、作者、主题、日期等）的多字段搜索
• search_by_collection(collection_id) -在哈佛图书馆的特定馆藏中搜索
• search_by_date_range(start_date, end_date) -按发布日期范围搜索
• search_by_geographic_origin(location) -按出版物位置搜索

📊 实用工具

• get_record_details(record_id) -通过哈佛ID获取完整的书目记录
• get_collections_list() -列出所有可用的集合及其元数据
• parse_mods_metadata(mods_xml) -将MODS XML转换为结构化JSON

📝 用法示例

基本搜索

Search for books about artificial intelligence published after 2020

学术研究

Find works by Noam Chomsky in the linguistics collection
Show me details for Harvard record ID: 12345678

收藏发现

List all Harvard Library collections
Search within the Fine Arts Library collection for Renaissance art

⚙️ 配置

环境变量

• HARVARD_API_BASE_URL：哈佛图书馆API的基本URL（默认值： https://api.lib.harvard.edu/v2)
• RATE_LIMIT_REQUESTS_PER_SECOND：API费率限制（默认值： 10)
• LOG_LEVEL：日志记录级别（默认值： INFO)

高级配置

对于自定义部署，您可以配置其他设置：

# Custom rate limiting
export RATE_LIMIT_REQUESTS_PER_SECOND=5

# Debug logging
export LOG_LEVEL=DEBUG

# Custom API endpoint (for development/testing)
export HARVARD_API_BASE_URL=https://api.lib.harvard.edu/v2

🏗️ 建筑

核心组件

• 服务器(server.py)：MCP stdio接口实现
• API客户端(api/client.py)：哈佛图书馆API的异步HTTP客户端
• 工具(tools/search_tools.py)：MCP工具实现
• 型号(models/harvard_models.py)：用于数据验证的Pydantic模型
• 配置(config.py)：基于环境的配置管理

数据流

AI Assistant → MCP Server → Harvard Library API → Bibliographic Records

服务器处理：

• ✅ 速率限制（默认为10要求/秒）
• ✅ 错误处理和重试
• ✅ MODS XML解析和JSON转换
• ✅ 响应验证和键入

👨‍💻 发展

先决条件

• Python 3.11或更高版本
• Git

设置开发环境

# Clone the repository
git clone https://github.com/kltng/harvard-library-mcp.git
cd harvard-library-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with dependencies
pip install -e ".[dev]"

# Set up pre-commit hooks (optional)
pre-commit install

运行测试

# Run all tests
make test
pytest tests/ -v

# Run tests with coverage
make test-coverage
pytest tests/ --cov=src --cov-report=html

# Run specific test categories
pytest tests/ -m unit        # Unit tests only
pytest tests/ -m integration # Integration tests only

代码质量

# Run all linting checks
make lint
mypy src/
ruff check src/
black --check src/
isort --check-only src/

# Format code automatically
make format
black src/
isort src/
ruff check --fix src/

🐳 Docker支持

构建并运行

# Build Docker image
docker build -t harvard-library-mcp:latest .

# Run container
docker run -d --name harvard-library-mcp harvard-library-mcp:latest

# Using Docker Compose
docker-compose up -d
docker-compose logs -f

📦 安装选项

来自PyPI（推荐）

pip install harvard-library-mcp

来源

git clone https://github.com/kltng/harvard-library-mcp.git
cd harvard-library-mcp
pip install -e .

开发版本

pip install git+https://github.com/kltng/harvard-library-mcp.git

🔄 发布过程

该项目使用GitHub Actions和PyPI Trusted Publishing的自动发布。

对于用户

安装最新版本：

pip install harvard-library-mcp

安装特定版本：

pip install harvard-library-mcp==0.1.0

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🔗 链接和资源

• PyPI包: https://pypi.org/project/harvard-library-mcp/
• GitHub存储库: https://github.com/kltng/harvard-library-mcp
• 错误报告: https://github.com/kltng/harvard-library-mcp/issues
• 哈佛图书馆API文档:

- LibraryCloud API - 图书馆云概述

• MODS XML模式: http://www.loc.gov/standards/mods/

🤝 贡献

欢迎投稿！请看 贡献.md 作为指导方针。

快速贡献指南

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📊 项目统计

• 记录总数：2000多万条书目记录
• 集合：100多个专业图书馆藏书
• API费率限制：10个请求/秒（可配置）
• 响应格式：JSON、MODS-XML
• Python版本: 3.11, 3.12, 3.13
• 许可证：MIT

______________________________________________________________________

⭐ 如果你觉得这个仓库有用，请在GitHub上标记它！

由以下材料制成❤️ 学术研究界