Sanguok | 山月修改

本文介绍如何在Windows环境（笔者用的是Python 3.13 Microsoft Store版）安装Zotero MCP并配置给LM Studio使用。

前置准备

需要安装以下软件：

• Zotero 7+
• LM Studio 0.3.17+
• Python 3.10+

开启Zotero本地API

Zotero默认关闭此功能，需手动开启。

1. 打开Zotero，进入 Edit > Preferences。
2. 在 Advanced 标签页下，勾选 “Allow other applications on this computer to communicate with Zotero”。

安装Zotero MCP

在终端运行安装命令。

使用uv（官方推荐）：

# 如果尚未安装 uv
pip install uv

# 安装 zotero-mcp
uv tool install "git+https://github.com/54yyyu/zotero-mcp.git"

或使用pip：

pip install -U "git+https://github.com/54yyyu/zotero-mcp.git"

安装后若提示"The script zotero-mcp.exe is installed in ... which is not on PATH"，说明系统无法直接识别命令。复制提示信息中zotero-mcp.exe的完整路径（例如：C:\Users\[用户名]\AppData\...\Scripts\zotero-mcp.exe），后续配置需要用到。

配置LM Studio

打开LM Studio，点击+ Install以打开mcp.json。在 mcpServers 字段中加入以下配置：

{
  "mcpServers": {
    "zotero": {
      "command": "C:\\Users\\[你的用户名]\\AppData\\...\\Scripts\\zotero-mcp.exe",
      "args": [],
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    }
  }
}

• command：填入上一步获取的zotero-mcp.exe绝对路径。JSON中路径的反斜杠需写作双斜杠\\。
• env：ZOTERO_LOCAL设为true以启用本地全文检索支持。

验证与使用

1. 在LM Studio加载支持Tool Use的模型（如Llama 3.1 8B Instruct或Qwen 2.5）。
2. 确认MCP装载。
3. 输入测试指令，如：“Find the most recent paper I added to my library.”

启用语义搜索（可选）

默认仅支持关键词搜索。如需语义检索，需手动建立索引。

在命令提示符使用完整路径运行update-db命令（路径请按实际情况替换）：

C:\Users\[你的用户名]\AppData\...\Scripts\zotero-mcp.exe update-db

此指南适用于开发环境或通过Git管理的生产环境。Docker环境可用。

核心概念

MCP Adapter既可以作为Composer库被其他插件引用（推荐），也可以作为独立插件运行。

• 依赖管理：该插件不包含vendor目录（第三方库），必须在本地通过Composer生成。
• 运行环境：需要PHP 7.4+和WordPress 6.8+。

首次安装流程

步骤A：下载源码

进入WordPress的插件目录并克隆仓库：

cd /path/to/wp-content/plugins/
git clone https://github.com/WordPress/mcp-adapter.git
cd mcp-adapter

步骤B：安装依赖

此步骤用于生成vendor/autoload.php文件。若跳过此步，插件将无法运行。

Docker环境下的命令：

docker run --rm \
    -v $(pwd):/app \
    composer install

会下载wordpress/abilities-api等核心依赖并生成自动加载映射。

步骤C：激活插件

# 使用 WP-CLI 或在后台激活
wp plugin activate mcp-adapter

HTTPS协议一致性

配置WP_API_URL时，必须严格匹配站点的实际协议。

• ❌ 错误做法：站点强制 HTTPS，但填写http://yousite.com/...
• ✅ 正确做法：填写https://yousite.com/...

如果站点强制使用 HTTPS（生产环境标准配置），而在配置中填写了http://，WordPress或服务器（Nginx/Apache）会返回一个301 Redirect跳转到HTTPS。在这个跳转过程中，出于安全规范，客户端发送的Authorization标头（包含密码）通常会被丢弃。这将导致请求虽然到达了最终地址，但因丢失凭据而报401 Unauthorized错误。

后续更新流程

由于插件通过Git安装，勿使用WordPress后台的“更新”按钮，以免覆盖Git配置。应按照以下步骤进行更新：

第一步：同步代码

获取最新的功能和修复：

cd /path/to/wp-content/plugins/mcp-adapter
git pull origin trunk

第二步：同步依赖

代码更新可能包含依赖包版本的变化（composer.lock变更）。每次git pull后运行：

docker run --rm \
    -v $(pwd):/app \
    composer install

如果跳过此步，可能会因为缺少新引入的类文件导致网站出现Fatal Error。

常见问题

• Plugin could not be activated (Fatal Error):
  • 原因：忘记执行composer install，导致vendor/autoload.php缺失。
  • 解决：重新执行安装流程中的步骤B。
• 类名冲突:
  • 原因：如果有多个插件都使用了MCP Adapter。
  • 解决：文档建议使用Jetpack Autoloader来解决多版本冲突（composer require automattic/jetpack-autoloader），但在单插件模式下非必须。
• API 404 错误:
  • 解决：确保WordPress的固定链接（Permalinks）设置不是“朴素 (Plain)”，需要设置为“文章名 (Post name)”或其他结构。
• API 401 错误 (Unauthorized):
  • 现象：MCP error -32603: WordPress API error (401)，且确认密码无误。
  • 解决：检查mcp.json中的WP_API_URL是否误写为了http://。将其修改为https://以避免重定向导致的凭据丢失。

核心概念：所有权 (Ownership) > 权限 (Permissions)

在Linux中，权限（755/644）必须配合正确的所有权（User:Group）才能生效。换言之，PHP进程（即WordPress）必须是文件/目录的“所有者”，才能在755/644权限下进行写入（上传图片、升级插件、生成缓存）。

标准化操作流程

确保位于WordPress根目录（通常为/var/www/html或public_html）下执行。

第一步：修正所有权

对当前目录下所有文件的所有者和组，行统一之设定。兹以33 (www-data) 为例（后文同此）。

chown -R 33:33 .

第二步：批量重置目录权限

按：使用+模式代替\;可显著提高执行效率。

find . -type d -exec chmod 755 {} +

第三步：批量重置文件权限

find . -type f -exec chmod 644 {} +

第四步：关键文件安全加固 (Hardening)

针对敏感文件设置更严格的只读权限。

# wp-config.php 包含数据库密码，生产环境应设为 440 或 400
# 前提：文件所有者必须是 PHP 运行用户，否则设为 400 后 PHP 无法读取将导致网站无法访问
chmod 440 wp-config.php

# .htaccess 控制伪静态，通常设为 644，若不频繁修改可设为 604
chmod 644 .htaccess

针对部分具体插件的特殊分析

按，任何要求设置777权限的插件通常都存在设计缺陷与安全隐患。

但在应用上述“严格权限”时，以下插件模块可能会遇到权限阻碍：

缓存类：Super Cache (超级缓存)

• 冲突点：该插件需要向wp-config.php写入开启缓存的定义代码，并修改.htaccess。
• 问题现象：当wp-config.php被设置为440时，插件后台更新设置会报错或白屏。
• 运维策略：
  1. 配置/更新插件前：chmod 644 wp-config.php
  2. 完成配置后：chmod 440 wp-config.php

按：日常运行中，插件生成的静态文件在wp-content/cache，该目录保持755即可正常读写。

安全风险类：WP File Manager

• 风险评估：极高。如已经拥有SSH命令行权限，该插件会增加不必要的攻击面。
• 漏洞原理：如果该插件存在0-day漏洞，攻击者可绕过WordPress权限体系，直接以www-data身份操作服务器文件（上传Webshell），此时440或644设置将失效。

翻译与本地化：Loco Translate

• 依赖：直接写入wp-content/languages 目录生成.po/.mo文件。
• 注意：只要第一步的chown -R 33:33 .执行正确，标准755目录权限即可满足需求。如果无法保存翻译，通常是所有者变成了root。

联邦宇宙与导入类 (ActivityPub, Import/Export)

• 依赖：wp-content/uploads。
• 注意：导入大型XML/CSV或处理ActivityPub媒体流时，会产生临时文件。
• 排查：如果导入失败或头像不显示，通过ls -ld wp-content/uploads检查权限是否为drwxr-xr-x (755)且所有者为www-data。

常见故障排查清单

1. 错误：440 导致某些环境白屏

   • 如果服务器使用的不是PHP-FPM (User: www-data) 而是以CGI模式运行（User: 系统账户），将wp-config.php设为440且所有者为33可能导致文件无法被读取，引发HTTP 500错误。
   • 验证：执行完命令后，如果网站正常访问，说明配置正确。

2. 插件更新失败 / 无法创建目录

   • 现象：后台提示“无法创建目录”。
   • 原因：通常不是权限问题（755是对的），而是所有权问题。
   • 复查：运行ls -ld wp-content/plugins，确保输出包含www-data www-data（或33 33）。如果显示的是root root，插件将无法更新。

3. Git/开发环境

   • 如使用Git管理代码，.git目录的权限不要设置为755/644，且不应允许Web访问。
   • 建议在Nginx/Apache 配置中显式禁止访问.git目录。

推荐操作脚本

确认在WordPress根目录后，按顺序执行：

# 1. 修正所有权 (兹以www-data为例，即id 33)
chown -R 33:33 .

# 2. 修正目录权限
find . -type d -exec chmod 755 {} +

# 3. 修正文件权限
find . -type f -exec chmod 644 {} +

# 4. 加固配置文件 (注意：配置 Super Cache 插件时可能需临时改为 640/644)
chmod 440 wp-config.php

# 5. 确保 .htaccess 对 WP 可写但安全
chmod 644 .htaccess

GnuCash內置了「線上報價」(Finance::Quote) 功能，允許軟體自動從網路獲取股票、基金和貨幣的最新價格。

但在Windows系統上，安裝此功能時常因缺少依賴項或權限設定而導致失敗。本教程將說明完整的安裝步驟，以及如何修復常見的依賴安裝錯誤，以確保功能正常運作。

先決條件

1. 已經在Windows 上安裝了GnuCash（安裝包內含Strawberry Perl環境）。
2. 擁有電腦的管理員權限。

第1步：以管理員身份開啟PowerShell

安裝過程需要使用PowerShell操作。

1. 點擊「開始」選單。
2. 輸入PowerShell。
3. 在搜尋結果中，找到 “Windows PowerShell”。
4. 右鍵點擊它，選擇「以管理員身份執行」。
5. 開啟後應會看到標示為管理員的PowerShell視窗。

第2步：更改PowerShell執行策略

Windows預設可能會限制腳本執行。需要先為當前的PowerShell視窗解除限制。

• 在藍色窗口中，複製並貼上以下指令，然後按Enter鍵：

  Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
  

• 如出現提示，請輸入Y並按Enter鍵確認。

第3步：切換至GnuCash目錄並執行安裝

接下來執行GnuCash提供的安裝腳本。

1. 切換到GnuCash的程式目錄。複製並貼上以下指令，然後按Enter（一般來說是此路徑，但還是要確認下自己電腦內實際的安裝路徑）：

   cd "c:\Program Files (x86)\gnucash\bin"
   

2. 執行.ps1安裝腳本（注意是.ps1文件，不是.cmd）：

   .\install-fq-mods.ps1
   

第4步：處理依賴項安裝失敗的問題

執行上述腳本時，日誌中可能會出現Result: FAIL或NOT OK的錯誤訊息。這是因為Finance::Quote依賴許多Perl模組，若其中任何一個測試失敗，安裝過程就會受到影響。

即使安裝腳本最後顯示：

>> Installation succeeded <<

Press Enter to continue...

若前方的日誌中有報錯，代表並未真正安裝成功。必須手動修復這些失敗的依賴項。

例1：修復Date::Simple失敗

如果日誌顯示類似以下的錯誤：

Result: FAIL Failed 1/3 test programs. 1/233 subtests failed. gmake: *** [makefile:1034: test_dynamic] Error 1 IZUT/Date-Simple-3.03.tar.gz C:\STRAWB~1\c\bin\gmake.exe test -- NOT OK Stopping: 'install' failed for 'Date::Simple'.

這表示Date::Simple模組因測試未通過而中止安裝。

修復方法：

1. 在同一個管理員PowerShell視窗中，輸入以下指令啟動Perl的CPAN安裝環境（一般來說是此路徑，但還是要確認下自己電腦內實際的安裝路徑）：

   c:\Strawberry\perl\bin\cpan.bat
   

2. 提示符會變為cpan[1]>。
3. 輸入force install指令強制安裝該模組（跳過測試）：

   force install Date::Simple
   

4. 等待安裝完成。
5. 輸入exit並按Enter鍵，退回到PowerShell提示符。

例2：修復Module::CPANTS::Analyse失敗

修復完前一個模組後，必須重新執行安裝腳本：

.\install-fq-mods.ps1

此時可能會發現另一個模組失敗。例如：

Result: FAIL ［中略］ Stopping: 'install' failed for 'I/IS/ISHIGAKI/Module-CPANTS-Analyse-1.02.tar.gz'.

修復方法：

1. 再次啟動CPAN（一般來說是此路徑，但還是要確認下自己電腦內實際的安裝路徑）：

   c:\Strawberry\perl\bin\cpan.bat
   

2. 強制安裝這個失敗的模組：

   force install Module::CPANTS::Analyse
   

3. 安裝完成後，輸入exit退出。

重複此過程

重複上述步驟，即：

1. 執行.\install-fq-mods.ps1。
2. 檢查日誌是否有... NOT OK的錯誤。
3. 若有，進入cpan.bat使用force install [模組名]進行修復。
4. 直到最後一次執行安裝腳本（.\install-fq-mods.ps1）時，日誌顯示所有測試均為PASS和OK，並顯示：

BPSCHUCK/Finance-Quote-1.67.tar.gz C:\STRAWB~1\c\bin\gmake.exe install UNINST=1 -- OK >> Installation succeeded <<

此時才代表安裝真正成功。

第5步：驗證安裝

安裝完成後，需驗證GnuCash能否正確載入模組。

1. 關閉目前的管理員PowerShell視窗。
2. 以一般使用者身份開啟一個新的「命令提示字元」 (CMD) 視窗。
3. 輸入以下指令進行測試（一般來說是此路徑，但還是要確認下自己電腦內實際的安裝路徑）：

   "c:\Program Files (x86)\gnucash\bin\gnucash-cli.exe" --quotes info
   

4. 判斷結果：
   • 如果出現Failed to initialize... missing_modules，表示安裝仍未成功，需回頭檢查依賴項。
   • 如果出現一條警告（WARN），如下所示，則代表安裝成功：

   * 20:09:31  WARN <gnc.price-quotes> [GncFQQuoteSource::set_api_key()] No Alpha Vantage API key set...
   

此Alpha Vantage API key警告屬於正常現象，僅提示未設定特定數據源的API金鑰，但證明GnuCash已成功載入Finance::Quote模組。

總結

1. 開啟GnuCash。
2. 進入工具 (Tools) -> 證券編輯器 (Security Editor)。
3. 選擇一個證券（如股票），點擊「編輯」。
4. 勾選「獲取在線報價(G)」。
5. 此時原本顯示「Finance::Quote 未正確安裝」的警告訊息應已消失。

注意，Finance::Quote適用於獲取股票和主要貨幣匯率，但通常無法自動獲取——比方說中國的場外基金淨值等。對於此類基金，大概還是得定期前往 工具 -> 價格編輯器 (Price Editor) 手動更新淨值。