mcp_library_search 0.1.0__tar.gz

mcp_library_search-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+*.egg-info/
+.DS_Store

mcp_library_search-0.1.0/AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS.md
+
+给在本仓库工作的 AI 编码助手和贡献者的指南。面向使用者的文档见 [README.md](README.md)。
+
+## 架构约束（改代码前必读）
+
+- `server.py` 是薄层：只做参数传递和异常包装。业务逻辑、对方代码的 import 一律不进这一层。
+- 对方代码只允许在 `adapters/` 和 `vendor/` 中出现。适配层把对方接口收敛成干净函数，返回给 LLM 的字段在适配层裁剪，不透传原始 dataclass。
+- 新增一座城市 = `adapters/<city>.py` 实现 `search_books` / `get_holdings` / `get_book_detail` 三个原语（返回结构对齐 `base.py` 的 TypedDict，由 `tests/test_adapter_contract.py` 强制校验），再在 `adapters/__init__.py` 的 `_ADAPTERS` 注册一行。server 和 tool 接口不动，README 的支持情况表加一行。
+
+## vendor 目录（`src/mcp_library_search/vendor/`）
+
+收录第三方项目代码（vendored），一个组件一个子目录，各目录保留其原始 LICENSE。
+
+**NOTICE 约定**：根目录的 [NOTICE](NOTICE) 是所有第三方组件的唯一事实来源——每个组件一整块，记录主页、许可证、位置、变更。
+
+- 新增组件：除放入 vendor/ 外，必须在 NOTICE 追加一块。
+- 本地修改 vendored 代码：必须在 NOTICE 对应组件块的"变更"里补一条。
+- 不要在 vendor 目录里放单独的 NOTICE 文件；README 致谢只点到为止，细节一律指向 NOTICE。
+
+当前组件：shanghai-library-book-search-python（[仓库](https://github.com/ZedeX/shanghai-library-book-search-python)，Apache-2.0，位于 `vendor/shanghai_library/`）。
+
+- 保持原样，bug 优先提给上游。
+- 上游是平铺 import，已改为包内相对导入（仅 `library_client.py` 三行）；**同步上游（覆盖同名文件）后必须重新应用相对导入修改**，否则包无法导入。同步后记得在 NOTICE 的变更里记一笔。
+- 检索总条数：站点统计区已不再输出该信息（`total_results` 恒为 0），adapter 按"0 且当前页有结果 → 视为未知（null）"处理，不属于代码 bug。
+- 图书简介：站点没有独立简介区块，内容简介以书目"附注"字段（MARC 500）形式给出，vendor 补丁将 summary 回退到附注（见 NOTICE 变更）。
+- 预计归还时间：馆藏页不直接渲染归还日期，已借出馆藏的 `<a class="item-return-date">` 只带单册 `data-itemid`，需按条调用 `AJAX/JSON?method=itemReturnDate` 接口（vendor 提供 `get_return_date`，adapter 负责逐个补 `due_date`）。
+- 本地补丁：`parser.py` 解析 has_next（下一页链接）、`library_client.py` 的 statistics 附带 has_next（见 NOTICE 变更）。同步上游覆盖文件后，检查这些补丁是否仍需重新应用。
+
+## 测试
+
+- `uv run pytest`。单测必须 mock 外部依赖，**不打真实图书馆网站**。
+- 真网验证走手工 smoke，不进测试套件。
+
+## 开发环境
+
+- uv 管理。PyPI 不通时用镜像：`uv sync --default-index https://pypi.tuna.tsinghua.edu.cn/simple`。
+- 调试 MCP：`uv run fastmcp dev src/mcp_library_search/server.py`（带 inspect 界面）。
+
+## 发布
+
+- 入口是 console script `mcp_library_search`（定义在 pyproject 的 `[project.scripts]`，转发到 `server:main`）。改动入口要同步检查 README 里的 uvx 用法。
+- `uv build && uv publish`（需 PyPI token）。发布后 `uvx mcp_library_search` 生效。
+- 改了 tool 的名称/参数/描述，同步更新 README 的 tool 表。

mcp_library_search-0.1.0/LICENSE

@@ -0,0 +1,203 @@
+Copyright 2026 mcp_library_search contributors
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mcp_library_search-0.1.0/NOTICE

@@ -0,0 +1,27 @@
+mcp_library_search
+Copyright 2026 mcp_library_search contributors
+
+本产品包含以下第三方项目的软件，以 vendored 方式收录于 src/mcp_library_search/vendor/。
+各组件仍沿用其原始许可证，许可证文本随代码一并包含在对应目录中。
+各组件的本地变更记录也一并列于下方。
+
+组件：shanghai-library-book-search-python
+  主页：https://github.com/ZedeX/shanghai-library-book-search-python
+  许可证：Apache License 2.0
+  位置：src/mcp_library_search/vendor/shanghai_library/
+  变更：
+    - 保留核心检索模块（client.py、library_client.py、parser.py、models.py），
+      未引入其 Flask Web 层与 CLI 层。
+    - library_client.py 的 3 行平铺 import 改为包内相对导入，使其可作为包导入。
+    - parser.py：新增 has_next（"下一页"链接）解析，随解析结果返回。
+    - library_client.py：statistics 增加 has_next 字段。
+    - parser.py：书目表新增"附注"字段提取（book_info["notes"]）。
+    - library_client.py：summary 为空时回退取"附注"字段（站点无独立简介区块，
+      内容简介通常以 MARC 500 附注形式给出）。
+    - 说明：检索总条数（total_results）恒为 0 系站点不再输出该信息，由 adapter
+      按"总数为 0 且当前页有结果视为未知"规则处理，非代码缺陷。
+    - parser.py：馆藏行新增单册 item_id 提取（item-return-date 锚点的
+      data-itemid 属性，仅"已借出"馆藏有）。
+    - models.py：Availability 新增 item_id、due_date 字段。
+    - library_client.py：get_holdings 透传 item_id；新增 get_return_date
+      方法，按单册调用 AJAX itemReturnDate 接口查预计归还时间。

mcp_library_search-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: mcp_library_search
+Version: 0.1.0
+Summary: MCP server for finding books in city library systems (Shanghai supported; more cities coming)
+Project-URL: Homepage, https://github.com/cnderrick/mcp_library_search
+Project-URL: Repository, https://github.com/cnderrick/mcp_library_search
+Project-URL: Issues, https://github.com/cnderrick/mcp_library_search/issues
+Author-email: Derrick Huang <cnderrick.huang@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: availability,books,library,mcp,shanghai
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.0
+Description-Content-Type: text/markdown
+
+# mcp_library_search
+
+MCP server：查询城市图书馆的馆藏与可借状态——回答"这本书在哪些馆能借到"。
+
+## 支持情况
+
+| 城市 | 标识 | 状态 | 数据源 |
+|---|---|---|---|
+| 上海 | `shanghai` | ✅ 已接入 | 上海中心图书馆"一卡通"总分馆体系（900+ 网点，含地铁站 24 小时自助机） |
+| 深圳 | `shenzhen` | 🔜 待接入 | — |
+| 更多城市 | — | 欢迎提需求或贡献适配器 | — |
+
+## 安装
+
+### Claude Code
+
+```bash
+claude mcp add mcp-library-search -- uvx mcp_library_search
+```
+
+### Claude Desktop
+
+在 `claude_desktop_config.json` 里加：
+
+```json
+"mcpServers": {
+  "mcp-library-search": {
+    "command": "uvx",
+    "args": ["mcp_library_search"]
+  }
+}
+```
+
+改完重启桌面版。
+
+## 使用
+
+接入后提供 3 个 tool，查询链路为：先 `search_books` 按关键字找到 `book_id`，再用它查馆藏或详情。都带 `city` 参数（默认 `shanghai`，未接入的城市会返回明确提示）：
+
+| tool | 作用 |
+|---|---|
+| `search_books(keyword, city, page, limit)` | 按关键字（书名、ISBN、作者等）搜书，返回分页列表，每条带 `book_id` 和可借概况 |
+| `find_book_availability(book_id, city, only_available)` | 查这本书在哪些馆有、是否可借，可借的馆排前面；`only_available=False` 时已借出的馆藏带预计归还时间（`due_date`） |
+| `get_book_detail(book_id, city)` | 查这本书的完整介绍（ISBN、索书号、内容简介） |
+
+典型用法：对 Claude 说"帮我查《三体》在哪个馆能借到" → 搜书拿到 `book_id` → 查各馆可借状态 → 就近推荐。
+
+## 致谢
+
+- [shanghai-library-book-search-python](https://github.com/ZedeX/shanghai-library-book-search-python)——上海图书馆检索能力的来源（Apache-2.0）。
+
+完整的第三方组件列表、归属与变更说明见 [NOTICE](NOTICE)。

mcp_library_search-0.1.0/README.md

@@ -0,0 +1,52 @@
+# mcp_library_search
+
+MCP server：查询城市图书馆的馆藏与可借状态——回答"这本书在哪些馆能借到"。
+
+## 支持情况
+
+| 城市 | 标识 | 状态 | 数据源 |
+|---|---|---|---|
+| 上海 | `shanghai` | ✅ 已接入 | 上海中心图书馆"一卡通"总分馆体系（900+ 网点，含地铁站 24 小时自助机） |
+| 深圳 | `shenzhen` | 🔜 待接入 | — |
+| 更多城市 | — | 欢迎提需求或贡献适配器 | — |
+
+## 安装
+
+### Claude Code
+
+```bash
+claude mcp add mcp-library-search -- uvx mcp_library_search
+```
+
+### Claude Desktop
+
+在 `claude_desktop_config.json` 里加：
+
+```json
+"mcpServers": {
+  "mcp-library-search": {
+    "command": "uvx",
+    "args": ["mcp_library_search"]
+  }
+}
+```
+
+改完重启桌面版。
+
+## 使用
+
+接入后提供 3 个 tool，查询链路为：先 `search_books` 按关键字找到 `book_id`，再用它查馆藏或详情。都带 `city` 参数（默认 `shanghai`，未接入的城市会返回明确提示）：
+
+| tool | 作用 |
+|---|---|
+| `search_books(keyword, city, page, limit)` | 按关键字（书名、ISBN、作者等）搜书，返回分页列表，每条带 `book_id` 和可借概况 |
+| `find_book_availability(book_id, city, only_available)` | 查这本书在哪些馆有、是否可借，可借的馆排前面；`only_available=False` 时已借出的馆藏带预计归还时间（`due_date`） |
+| `get_book_detail(book_id, city)` | 查这本书的完整介绍（ISBN、索书号、内容简介） |
+
+典型用法：对 Claude 说"帮我查《三体》在哪个馆能借到" → 搜书拿到 `book_id` → 查各馆可借状态 → 就近推荐。
+
+## 致谢
+
+- [shanghai-library-book-search-python](https://github.com/ZedeX/shanghai-library-book-search-python)——上海图书馆检索能力的来源（Apache-2.0）。
+
+完整的第三方组件列表、归属与变更说明见 [NOTICE](NOTICE)。

mcp_library_search-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "mcp_library_search"
+version = "0.1.0"
+description = "MCP server for finding books in city library systems (Shanghai supported; more cities coming)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "Derrick Huang", email = "cnderrick.huang@gmail.com" }]
+keywords = ["mcp", "library", "shanghai", "books", "availability"]
+dependencies = ["fastmcp>=2.0"]
+
+[project.urls]
+Homepage = "https://github.com/cnderrick/mcp_library_search"
+Repository = "https://github.com/cnderrick/mcp_library_search"
+Issues = "https://github.com/cnderrick/mcp_library_search/issues"
+
+[project.scripts]
+mcp_library_search = "mcp_library_search.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_library_search"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mcp_library_search-0.1.0/src/mcp_library_search/adapters/__init__.py

@@ -0,0 +1,32 @@
+"""适配层统一入口：按城市分派到具体适配器。
+
+新增一座城市 = 在 adapters/ 下新建一个模块，实现 search_books / get_holdings /
+get_book_detail 三个原语（返回结构对齐 base.py 的 TypedDict，由契约测试强制），
+然后在本文件 _ADAPTERS 里注册一行。server 层与具体城市解耦。
+"""
+from . import shanghai
+
+_ADAPTERS = {
+    "shanghai": shanghai,
+}
+
+_SUPPORTED = "、".join(sorted(_ADAPTERS))
+
+
+def _get(city: str):
+    adapter = _ADAPTERS.get(city.lower())
+    if adapter is None:
+        raise RuntimeError(f"该城市暂未接入：{city}。当前支持：{_SUPPORTED}")
+    return adapter
+
+
+def search_books(city: str, keyword: str, page: int = 1, limit: int = 20) -> dict:
+    return _get(city).search_books(keyword, page=page, limit=limit)
+
+
+def get_holdings(city: str, book_id: str, only_available: bool = True) -> list[dict]:
+    return _get(city).get_holdings(book_id, only_available=only_available)
+
+
+def get_book_detail(city: str, book_id: str) -> dict:
+    return _get(city).get_book_detail(book_id)

mcp_library_search-0.1.0/src/mcp_library_search/adapters/base.py

@@ -0,0 +1,102 @@
+"""统一返回模型：所有城市适配器的输出必须对齐这里的 TypedDict。
+
+字段语义以注释为准。tests/test_adapter_contract.py 会对 _ADAPTERS 里每个
+适配器做契约校验——新增城市对齐不对齐，测试直接红。
+"""
+import types as _types
+import typing
+from typing import Optional, TypedDict, get_type_hints
+
+
+class BookSummary(TypedDict):
+    """search_books 的列表条目：轻量书目信息，不带简介和馆藏明细。"""
+    book_id: str               # 城市内稳定的不透明 ID，原样传给 find_book_availability / get_book_detail
+    title: str
+    author: str                # 没有则为空串
+    publisher: str             # 没有则为空串
+    publish_year: str          # 没有则为空串
+    availability_summary: str  # 可借概况的简短文本，没有则为空串
+
+
+class SearchPage(TypedDict):
+    total_results: Optional[int]  # 匹配总数；None 表示数据源不提供总数
+    page: int                     # 当前页码（从 1 开始）
+    total_pages: int              # 总页数
+    has_next: bool                # 是否还有下一页
+    books: list[BookSummary]
+
+
+class Holding(TypedDict):
+    """单条馆藏记录。"""
+    library: str      # 分馆名称
+    location: str     # 馆内位置（楼层/室），没有则为空串
+    call_number: str  # 索书号，没有则为空串
+    status: str       # 原始状态文本，如"可借"、"已借出"
+    available: bool   # 可借与否的归一化结果
+    due_date: str     # 预计归还时间（YYYY-MM-DD），仅已借出馆藏可能非空
+
+
+class BookDetail(TypedDict):
+    book_id: str
+    title: str
+    author: str
+    publisher: str
+    publish_year: str
+    isbn: str         # 没有则为空串
+    call_number: str  # 没有则为空串
+    summary: str      # 内容简介，没有则为空串
+
+
+# ---------- 契约校验（测试用） ----------
+
+
+def _check(value, ann, where: str) -> None:
+    origin = typing.get_origin(ann)
+    if origin is typing.Union or origin is _types.UnionType:  # Optional[X] / X | None
+        if value is None:
+            return
+        for arg in typing.get_args(ann):
+            if arg is not type(None):
+                _check(value, arg, where)
+        return
+    if origin is list:
+        if not isinstance(value, list):
+            raise AssertionError(f"{where}: 期望 list，实际 {type(value).__name__}")
+        (item_ann,) = typing.get_args(ann)
+        for i, item in enumerate(value):
+            _check(item, item_ann, f"{where}[{i}]")
+        return
+    if ann is int:
+        if not (isinstance(value, int) and not isinstance(value, bool)):
+            raise AssertionError(f"{where}: 期望 int，实际 {type(value).__name__}")
+        return
+    if typing.is_typeddict(ann):  # 嵌套模型，如 list[BookSummary] 里的 BookSummary
+        if not isinstance(value, dict):
+            raise AssertionError(f"{where}: 期望 {ann.__name__}（dict），实际 {type(value).__name__}")
+        _check_model(value, ann, where)
+        return
+    if not isinstance(value, ann):
+        raise AssertionError(f"{where}: 期望 {ann.__name__}，实际 {type(value).__name__}")
+
+
+def _check_model(obj: dict, model: type[TypedDict], where: str) -> None:
+    hints = get_type_hints(model)
+    expected, actual = set(hints), set(obj)
+    if expected != actual:
+        raise AssertionError(
+            f"{where}: 字段不匹配，缺 {sorted(expected - actual)}，多 {sorted(actual - expected)}"
+        )
+    for key, ann in hints.items():
+        _check(obj[key], ann, f"{where}.{key}")
+
+
+def validate_search_page(page: SearchPage) -> None:
+    _check_model(page, SearchPage, "search_books")
+
+
+def validate_holdings(holdings: "list[Holding]") -> None:
+    _check(holdings, list[Holding], "get_holdings")
+
+
+def validate_book_detail(detail: BookDetail) -> None:
+    _check_model(detail, BookDetail, "get_book_detail")

mcp_library_search-0.1.0/src/mcp_library_search/adapters/shanghai.py

@@ -0,0 +1,74 @@
+"""上海适配器：vendor 的 LibraryClient → base.py 统一模型。"""
+from ..vendor.shanghai_library.library_client import LibraryClient
+from .base import BookDetail, BookSummary, Holding, SearchPage
+
+_client = LibraryClient()
+
+
+def search_books(keyword: str, page: int = 1, limit: int = 20) -> SearchPage:
+    """按关键词搜索馆藏。上游报错抛 RuntimeError。"""
+    result = _client.search(keyword=keyword, page=page, limit=limit)
+    if not result.success:
+        raise RuntimeError(f"上海图书馆搜索失败：{result.error}")
+
+    books: list[BookSummary] = [
+        {
+            "book_id": b.record_id,
+            "title": b.title,
+            "author": b.author,
+            "publisher": b.publisher,
+            "publish_year": b.publish_year,
+            "availability_summary": b.availability_summary,
+        }
+        for b in (result.books or [])
+    ]
+    raw_total = result.statistics.get("total_results", 0)
+    return {
+        # 站点统计区不再输出总条数（解析结果恒为 0）：
+        # 总数为 0 且当前页有结果 → 视为未知（null）；当前页无结果 → 真的为 0
+        "total_results": raw_total if raw_total > 0 else (None if books else 0),
+        "page": result.statistics.get("page", page),
+        "total_pages": result.statistics.get("total_pages", 1),
+        "has_next": result.statistics.get("has_next", False),
+        "books": books,
+    }
+
+
+def get_holdings(book_id: str, only_available: bool = True) -> list[Holding]:
+    """指定图书在各分馆的馆藏与可借状态，可借的排前面。"""
+    holdings = _client.get_holdings(book_id) or []
+    kept = [h for h in holdings if (not only_available or h.is_available())]
+    items: list[Holding] = []
+    for h in kept:
+        available = h.is_available()
+        item: Holding = {
+            "library": h.library,
+            "location": h.location,
+            "call_number": h.call_number,
+            "status": h.status,
+            "available": available,
+            "due_date": "",
+        }
+        # 已借出的馆藏带单册 item_id，逐个查预计归还时间（单册级接口），失败留空串
+        if not available and getattr(h, "item_id", ""):
+            item["due_date"] = _client.get_return_date(h.item_id)
+        items.append(item)
+    items.sort(key=lambda h: (not h["available"], h["library"]))
+    return items
+
+
+def get_book_detail(book_id: str) -> BookDetail:
+    """指定图书的完整书目信息（含 ISBN、内容简介）。查不到抛 RuntimeError。"""
+    book = _client.get_book_detail(book_id)
+    if book is None:
+        raise RuntimeError(f"未找到该书的详情：{book_id}")
+    return {
+        "book_id": book.record_id,
+        "title": book.title,
+        "author": book.author,
+        "publisher": book.publisher,
+        "publish_year": book.publish_year,
+        "isbn": book.isbn,
+        "call_number": book.call_number,
+        "summary": book.summary,
+    }