Notanda (Beta)

Notanda 本地 MCP 服务 — Beta

每次 OpenAlex 搜索都会保存请求、响应和校验和，以便日后核查来源。

Beta：外部开发者在无人协助的情况下完成验收测试仍待进行。 技术测试不能替代这项外部可用性与安装检查。

此目录将 Notanda 的来源可追溯 OpenAlex 检索功能提供给本地 MCP 客户端。这是一个独立的 notanda-mcp 软件包，不是托管服务，也不属于 notanda 1.3.2 软件包。它依赖该已发布的核心软件包。

此组件恰好提供两个工具：

• search_literature：在 OpenAlex 中搜索带有 DOI 的 OA 作品，并将请求、提供方观测记录、返回结果和哈希值保存在同一个证据 ID 下；返回的 receipt 是 manifest.json 的 SHA-256。
• get_evidence：验证这些哈希值，并按证据 ID 返回原始结果，而不重复发送提供方请求。调用方可选传入自己保存的 receipt，以便检测载荷及其清单是否被替换。

两个工具的描述以及每个成功响应都会警告：标题和元数据是未经验证的第三方内容，不是指令。

它不会下载全文、写入 Notanda 语料库或 Evidence Ledger、修改 Web UI、开放网络服务，也不提供通用 Agent 推理功能。

来源可追溯性与状态

该实现改编自隔离分支 experiment/local-mcp，提交为 366bc2d4827aa915e2e58a82cd567163ed63d4be。封存的交接包将该源代码与 20 项通过的 MCP 测试及一次成功的 OpenAlex 实时运行绑定在一起。为了集成到公开仓库，重复的 Notanda 运行时已替换为已发布的 notanda==1.3.1 PyPI 依赖。Beta 3 将该固定版本更新为 notanda==1.3.2；MCP 仍固定为经测试的 SDK 版本 1.30.0。SOURCE_PROVENANCE.json 以机器可读的形式记录了源代码哈希值和有意进行的集成更改。

原始六项验收标准中，有五项已通过技术验证。第六项——一名不了解 Notanda 的外部开发者在无人协助的情况下完成安装、搜索、重启和独立验证——在收到验证结果之前仍有待外部验证。

安装 Beta 软件包

使用 Python 3.11 或 3.12。建议使用专用虚拟环境：

python -m venv .venv-mcp
# Linux/macOS:
. .venv-mcp/bin/activate
# Windows PowerShell instead:
# .venv-mcp\Scripts\Activate.ps1
python -m pip install "notanda-mcp==0.1.0b3"

Beta 3 要求版本必须为 notanda==1.3.2。在已包含该版本的环境中安装，可保留核心软件包的版本。Beta 2 要求 notanda==1.3.1，pip 可能会为满足该固定版本要求而将现有的 1.3.2 安装降级。如果需要 Beta 2 或其他 Notanda 核心版本，请使用单独的环境；不要绕过依赖检查。精确固定版本可确保经测试的核心软件包与服务组合可复现；但这并不代表它兼容未来的核心版本。

对于使用 uvx 的客户端，请配置以下命令和参数（将证据目录替换为计算机上具有写入权限的绝对路径）：

uvx --python 3.12 [email protected] --evidence-dir ABSOLUTE_LOCAL_EVIDENCE_PATH

在 MCP 客户端的本地环境中设置 HARVESTER_OPENALEX_API_KEY。搜索需要此密钥，且不得将其放在命令参数中。注册表清单将此变量声明为机密，并将证据路径声明为必需输入。

从此仓库安装

使用 Python 3.11 或 3.12。在仓库根目录下：

python -m venv .venv-mcp
# Linux/macOS:
. .venv-mcp/bin/activate
# Windows PowerShell:
# .venv-mcp\Scripts\Activate.ps1
python -m pip install -e ./mcp

此命令会从当前检出版本安装 MCP 组件，并从 PyPI 获取经审查的 Notanda 核心软件包 notanda==1.3.2。

在本地配置 OpenAlex API 密钥。例如，在 PowerShell 中，不将密钥写入终端历史记录：

$mcpSecureKey = Read-Host 'OpenAlex API key' -AsSecureString
$env:HARVESTER_OPENALEX_API_KEY = [System.Net.NetworkCredential]::new('', $mcpSecureKey).Password

现有的 Notanda 配置机制也适用：HARVESTER_CONFIG 或 HARVESTER_OPENALEX_API_KEY。切勿将凭据放入证据目录、Git、屏幕截图或返回的测试报告中。

运行和验证

提供的真实 stdio 客户端会启动服务、初始化 MCP、验证两个工具名称并执行搜索：

python mcp/tools/mcp_client.py \
  --evidence-dir ./tmp/mcp-evidence \
  --query "scientific reproducibility" \
  --limit 2

响应包含一个 evidence_id 和一个 receipt。请将两者保存在证据目录之外。第二个进程可以验证该回执并检索存储的响应，而无需再次请求提供方：

python mcp/tools/mcp_client.py \
  --evidence-dir ./tmp/mcp-evidence \
  --id EVIDENCE_ID \
  --receipt RECEIPT

为保持兼容性，get_evidence 也可以在不提供 receipt 的情况下使用，并执行原有的载荷哈希和身份检查。这些检查可以检测损坏，但只有提供原始回执时，才能检测载荷和清单被协同替换的情况。

独立验证器仅使用 Python 标准库：

python -S mcp/tools/verify_mcp_evidence.py \
  ./tmp/mcp-evidence/EVIDENCE_ID

如需使用其他本地 MCP 客户端，请使用以下参数配置虚拟环境中的 notanda-mcp 可执行文件：

--evidence-dir ABSOLUTE_LOCAL_EVIDENCE_PATH

传输方式为 stdio。该服务没有用户界面，也不会打开监听端口。

证据约定

每次搜索都会创建一个以 32 个字符的证据 ID 命名的目录：

文件	内容
request.json	提供的查询和实际使用的查询、限制、MCP 客户端名称/版本、源实验提交、已安装的 Notanda 版本和服务哈希
provider.json	脱敏后的 OpenAlex 请求 URL、时间戳、HTTP 状态和捕获的已解析 JSON
response.json	持久化的结果，包括结构化错误和不可信内容提示；封存后，会将分离的回执添加到 MCP 响应中
manifest.json	三个载荷文件的字节长度和 SHA-256

仅凭清单即可检测损坏或单个文件被修改。它不是数字签名；如果调用方没有持有回执，则无法检测载荷和清单被协同替换的情况。比对可选回执可以锚定原始搜索期间观察到的确切清单。

限制和错误行为

• 查询长度：1–1000 个字符。结果限制：整数 1–10。
• 仅请求 OpenAlex 一次，不进行分页，不自动重试。
• 操作超时为 20 秒，连接超时为 10 秒，响应上限为 4 MiB。
• 仅接受 https://api.openalex.org/works 作为提供方端点。
• 缺少密钥：configuration_error；输入无效：invalid_arguments。
• 提供方/传输失败：provider_error；不会存储提供方异常文本。
• 写入中断：incomplete；哈希或身份不匹配：integrity_failure； 提供的回执不匹配：receipt_mismatch。
• 提供方文本会作为不可信数据持久化，绝不作为指令进行解释。

测试

安装开发扩展并运行 23 项确定性检查：

python -m pip install -e "./mcp[dev]"
python -m pytest mcp/tests

测试涵盖成功检索、重启、独立验证、损坏、无效输入、HTTP 401/429/500、超时、格式错误和超大响应、存储故障、进程终止、密钥脱敏，以及真实的双进程 stdio MCP 操作。