内容
# 亚美尼亚国家图书馆 MCP 服务器（非官方）
一个独立的、与提供商无关的、只读的研究 MCP 集成，适用于亚美尼亚国家图书馆的公共 DSpace 9 仓库。
> [!IMPORTANT]
> 本项目是由 Suren Karapetyan 创建的非官方项目。它与亚美尼亚国家图书馆无关，也没有得到图书馆的认可、赞助或运营。NLA 名称仅标识互操作的公共仓库。MIT 许可证涵盖了本项目的软件，但不涵盖 NLA 的元数据、提取的文本、扫描件、出版物或其他第三方材料。请在使用仓库内容之前查看 [数据和内容权利](DATA_AND_CONTENT_RIGHTS.md)。
## 您可以使用
- 在亚美尼亚、英语或俄语中查找书籍、期刊、 manuscrits 和其他目录记录。
- 在不知道 DSpace API 的情况下，按作者、主题、年份、语言、类型或收藏来细化搜索。
- 检查完整的元数据、标识符、层次结构、访问状态和来源声明的权利证据。
- 当存在公共 `TEXT` 包时，读取 NLA 提供的提取文本，分为有限的块。
- 获取公共原始文件的规范 NLA 链接，而无需将 PDF 或其他复杂文档置于模型上下文中。
连接服务器后尝试以下提示：
- 英语：“查找 Hovhannes Tumanyan 的作品，显示三个最相关的记录，并引用它们的 NLA 目录页面。”
- 亚美尼亚语：「Գտիր Հովհաննես Թումանյանի ստեղծագործությունները, ցույց տուր երեք համապատասխան գրառում և նշիր ՀԱԳ-ի աղբյուրները」。
- 俄语：「Найди материалы об истории Армении, уточни поиск по теме и покажи ссылки на записи библиотеки」。
## 当前可用性
`1.0.1` 版本可从 npm 以 `@suren-kk/armenian-national-library-mcp` 的形式获取。使用下面的客户端命令或可复制的 [源代码设置](#build-from-source)。有关简明的亚美尼亚语快速入门，请参阅 [亚美尼亚语快速入门](docs/quickstart-hy.md)。
## 工作原理
实现包括：
- 具有稳定的官方 MCP SDK、验证的配置、JSON 标准错误日志记录和 stdio 传输的严格 TypeScript 基础。
- 具有同源强制执行、取消、超时、安全重定向、重试/回退、响应限制、条件缓存、可行错误和元数据规范化的有界 NLA HTTP/HAL 客户端。
- 适用于代理的搜索、方面、浏览、层次结构、项目和标识符工具，具有结构化输出和出处。
- 包分类、验证的比特流元数据/访问/下载链接、有界的 NLA 提供的文本提取、显式 MIME 验证状态和 `nla://` 资源仅限于 UTF-8 文本和验证的栅格图像。
- 每个 API 根关系的验证目录、受控的 JSON/纯文本原始读取和实时根漂移检测。
- 与提供商无关的 stdio 和无状态 Streamable HTTP 传输，具有主机/来源检查、速率限制、请求大小限制和健康探测。
## 要求
- Node.js 24（存储库固定为 `24.15.0` 以适应 asdf）
- npm
## 安装和连接客户端
npm 包名称为 `@suren-kk/armenian-national-library-mcp`。
将其添加到 Codex：
```bash
codex mcp add nla -- npx -y @suren-kk/armenian-national-library-mcp
```
等效的 Codex 配置：
```toml
[mcp_servers.nla]
command = "npx"
args = ["-y", "@suren-kk/armenian-national-library-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 60
```
将其添加到 Claude Code：
```bash
claude mcp add --transport stdio nla -- \
npx -y @suren-kk/armenian-national-library-mcp
```
在添加服务器后重启或重新连接客户端。新用户的使用流程为：
1. 使用 `search_catalog` 搜索 NLA 记录。
2. 将其项目标识符传递给 `get_item_text`，并将返回的 `nextOffset` 值作为 `offset_chars` 传回，当文本被分块时。
3. 查看记录的权利和访问字段。当访问是公共的且您的预期用途被允许时，调用 `list_item_files` 或 `get_file_download` 以获取规范的 NLA URL。
## 从源代码构建
```bash
npm install
cp .env.example .env
npm run ci
```
构建并启动 stdio 服务器：
```bash
npm run build
npm start
```
服务器仅将协议消息写入 stdout。结构化操作日志写入 stderr。
## 工具
- `get_repository_info`
- `search_catalog`, `get_search_facets`, `browse_catalog`
- `list_communities`, `get_community`, `list_subcommunities`, `list_community_collections`
- `list_collections`, `get_collection`, `list_collection_items`
- `get_item`, `get_item_access_status`, `list_item_files`, `get_item_relationships`, `get_item_version`, `get_item_identifiers`
- `get_item_text`, `get_bitstream`, `get_file_download`
- `resolve_identifier`
- `get_api_capabilities`, `nla_api_get`
## 测试
```bash
npm test
npm run lint
npm run typecheck
npm run build
```
## 容器
镜像使用基于摘要的 Node 基础，从锁定文件安装依赖项，不包含生命周期脚本，仅包含生产依赖项，并以非 root 用户身份运行。使用以下命令启动强化本地 HTTP 配置文件：
```bash
docker compose up --build
```
## 配置
参见 `.env.example`。最重要的安全边界是以下配对：
```text
NLA_API_BASE_URL=https://api.nla.am/server/api
NLA_ALLOWED_HOST=api.nla.am
```
所有后续链接和重定向必须保持在该确切主机和配置的 API 基本路径上的 HTTPS。文件写入被禁用，本服务器不实现文件写入。
## 隐私简要
请求搜索文本、标识符、筛选器和分页所需的文本会发送到 `https://api.nla.am`。然后，结果可能会发送到您配置的 AI 提供商。服务器没有分析或遥测服务；其有界缓存和速率限制状态在内存中，其默认日志省略查询和文档内容。自托管的 HTTP 操作员及其反向代理仍然可以观察传输元数据并定义自己的保留策略。在操作共享端点之前，请阅读完整的 [隐私声明](PRIVACY.md)。
## 版本和支持
- [更新日志](CHANGELOG.md)
- [MIT 软件许可](LICENSE)
- [非官方状态和通知](NOTICE)
- [数据和内容权利](DATA_AND_CONTENT_RIGHTS.md)
- [隐私声明](PRIVACY.md)
- [权利、删除和更正请求](TAKEDOWN.md)
- [第三方通知](THIRD_PARTY_NOTICES.md)
- [贡献和出处要求](CONTRIBUTING.md)
- [搜索和细化指南](docs/searching.md)
- [产品范围和故意延迟](docs/product-scope.md)
- [性能预算](docs/performance.md)
- [文本和原始文件覆盖方法](docs/content-coverage.md)
- [产品成功和反馈](docs/product-success.md)
- [亚美尼亚语快速入门](docs/quickstart-hy.md)
- [中立客户端和托管验收门](docs/client-acceptance.md)
- [法律、隐私和权利事件手册](docs/legal-incident-response.md)
- [版本和工件验证指南](docs/releasing.md)
- [支持和上游中断手册](docs/support.md)
- [安全报告政策](SECURITY.md)
