Research Zine Generator

锌发生器研究

一个自包含的web界面，用于使用MCP（模型上下文协议）服务器创建精美的杂志。上传图像，与AI代理聊天，并生成可打印的PDF杂志。

特性

• 📸 图片库：通过web界面上传和管理图像
• 💬 AI聊天界面：与LLM代理的自然语言交互
• 📄 PDF生成：使用Typst创建可打印的杂志
• 🎨 灵活的布局：支持文本、图像、网格和图像文本组合
• 🔧 MCP集成：使用模型上下文协议服务器实现可扩展性

快速开始

先决条件

在设置项目之前，请确保已安装以下内容：

• Python 3.8-3.13 （由于依赖兼容性问题，尚未支持Python 3.14+）

- 下载：https://www.python.org/downloads/ - 初学者指南：https://wiki.python.org/moin/BeginnersGuide/Download - 推荐：Python 3.11或3.12以获得最佳兼容性 - 最小Python 3.8（部分功能可能受限） - 备注：Python 3.14及更高版本还不支持像这样的包 pydantic-core 不要支持他们。如果您安装了Python 3.14+，安装脚本将尝试查找Python 3.13或3.12（如果可用）。

• Node.js 18或更高版本

- 下载：https://nodejs.org/en/download - 推荐：Node.js 18或更高版本，与exif mcp服务器完全兼容

• 虚拟环境 （将由安装脚本自动创建）

设置（3个步骤）

1. 下载或获取项目文件:

- 将项目文件解压缩到您选择的目录中 - 导航到项目目录： cd research-zine-generator

1. 运行安装脚本:

Linux/macOS：

   chmod +x setup.sh
   ./setup.sh

Windows（PowerShell）：

   # Note: The setup script is a bash script. On Windows, you may need to:
   # 1. Use Git Bash, WSL, or Cygwin to run the script
   # 2. Or follow the Manual Setup instructions below

1. 设置环境变量 （发射前需要）：

Linux/macOS：

   export AZURE_INFERENCE_ENDPOINT="https://your-resource.services.ai.azure.com/models"
   export AZURE_INFERENCE_CREDENTIAL="your-api-key-here"

Windows（PowerShell）：

   $env:AZURE_INFERENCE_ENDPOINT="https://your-resource.services.ai.azure.com/models"
   $env:AZURE_INFERENCE_CREDENTIAL="your-api-key-here"

> 注： 应用程序使用控制台环境变量，而不是 .env 文件夹。看 .env.example 有关详细的设置说明。

> LLM集成说明：此项目使用 LangChain 和 mcp使用 作为创建代理/客户端和编排多个LLM和MCP服务器的框架。当前设置是为Azure AI Foundry配置的，但也支持其他LLM提供程序： > > - Azure人工智能：安装指南：https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/develop/langchain > - 其他LLM选项：OpenAI、Anthropic、谷歌和开源模型（如Ollama）通过mcp使用得到支持。请参阅 mcp使用LLM集成文档 用于配置选项。 > - 重要：切换到其他LLM提供商将需要修改中的代码 agent/ui-agent.py 使用适当的LangChain适配器和配置。

1. 激活虚拟环境 （发射前需要）：

Linux/macOS：

   source .venv/bin/activate

Windows（PowerShell）：

   .venv\Scripts\activate

Windows（命令提示符）：

   .venv\Scripts\activate.bat

> 备注：安装脚本在安装过程中自动激活虚拟环境。关闭终端或启动新会话后，您需要在运行应用程序之前再次激活它。

1. 启动应用程序:

   python agent/ui-agent.py

web界面将在 http://localhost:7860

详细的设置说明

手动设置（如果不使用Setup.sh）

如果您更喜欢手动设置或在没有bash支持的Windows上设置，请按照以下步骤操作：

1. 创建Python虚拟环境:

Linux/macOS：

   python3 -m venv .venv
   source .venv/bin/activate

Windows（PowerShell）：

   python -m venv .venv
   .venv\Scripts\activate

Windows（命令提示符）：

   python -m venv .venv
   .venv\Scripts\activate.bat

1. 升级pip:

   pip install --upgrade pip

1. 安装Python依赖项:

   pip install -r agent/requirements.txt

1. 安装服务器依赖项:

   # Image Resources MCP
   pip install -r servers/image-resources-mcp/requirements.txt

   # Typst MCP Server
   pip install -r servers/typst-mcp-server/requirements.txt

   # Image Analyzer MCP (optional, only if you plan to use it)
   pip install -r servers/image-analyzer-mcp/requirements.txt

1. 安装其他Python包:

   # Typst (required by typst-mcp-server)
   pip install typst==0.14.1

   # gradio-pdf (optional but recommended for PDF preview)
   pip install gradio-pdf

1. 安装并构建exif mcp （Node.js服务器）：

   cd servers/exif-mcp
   npm install
   npm run build
   cd ../..

> 备注：如果未安装Node.js，exif mcp服务器将无法工作。请从以下位置安装Node.js 18+https://nodejs.org/如果需要的话。

1. 设置环境变量 （必填）：

应用程序使用 控制台环境变量，不 .env 文件夹。在运行应用程序之前，您必须在终端中导出它们。

Linux/macOS：

   export AZURE_INFERENCE_ENDPOINT="https://your-resource.services.ai.azure.com/models"
   export AZURE_INFERENCE_CREDENTIAL="your-api-key-here"

Windows（PowerShell）：

   $env:AZURE_INFERENCE_ENDPOINT="https://your-resource.services.ai.azure.com/models"
   $env:AZURE_INFERENCE_CREDENTIAL="your-api-key-here"

> 注： 看 .env.example 有关详细说明和永久设置选项。

环境变量

必需（必须设置为控制台环境变量）

• AZURE_INFERENCE_ENDPOINT：您的Azure AI端点URL

- 从Azure AI Studio或Azure门户获取此信息 - 格式： https://your-resource.services.ai.azure.com/models - 如果端点在“/models”后面有任何内容，请将其删除

• AZURE_INFERENCE_CREDENTIAL：您的Azure AI API密钥

- 从Azure AI Studio或Azure门户获取此信息

可选的

备注：这些环境变量在项目代码中是硬编码的。如果你想使用不同的值，你需要修改中的代码 agent/ui-agent.py 直接。

• OLLAMA_BASE_URL：ollama服务器URL（默认值： http://localhost:11434)
• OLLAMA_MODEL：Ollama型号名称（默认值： llama3.2-vision:11b)

只有当您想使用可选的图像分析器MCP服务器时，才需要这些。如果你想使用不同的Ollama型号或服务器，你需要在中更新服务器配置 agent/ui-agent.py.

MCP服务器

主服务器（始终启用）

• 图像资源MCP：提供对图像的访问 assets/images/input 目录
• 打字杂志服务器：从JSON配置生成zines
• exif mcp：提取图像元数据

可选服务器

默认情况下，这些服务器在 agent/ui-agent.py。要启用它们，请执行以下操作：

1. 图像分析器MCP服务器：需要安装并运行Ollama

> 备注：此服务器基于以下代码 lucoo01/图像分析仪mcp，但已为该项目进行了改编和翻译。

设置步骤：

- 安装Ollama：https://ollama.ai - 拉一个视觉模型（模型必须支持视觉/图像理解）：

     ollama pull llama3.2-vision:11b

- 默认Ollama服务器地址为 http://localhost:11434 （如果使用默认值，则不需要配置） - 重要：如果你想使用不同的视觉模型，你必须： 1. 拉动模型： ollama pull 1. 更新中的模型名称 agent/ui-agent.py 在Image Analyzer服务器配置中 1. 确保您选择的模型支持视觉功能 - 取消注释中的服务器配置 agent/ui-agent.py

1. 意象魔术mcp：需要单独安装

> 备注: imagesorcery-mcp 无法通过常规安装 pip。必须使用以下方式安装 pipx 或其他替代方法。

用管道安装 （推荐）：

   pipx install imagesorcery-mcp

安装后设置 （必填）：

   imagesorcery-mcp --post-install

这一步至关重要——它下载所需的模型，并尝试从GitHub安装clip Python包。

替代安装方法：参见 imagemagicy mcp存储库 其他安装选项。

安装后，在中取消注释服务器配置 agent/ui-agent.py

用法

1. 上传图像：使用上传按钮将图像添加到图库
2. 与AI聊天：请AI创建一个杂志，例如：

- “用我的所有图片创建一个杂志” - “制作一本带标题的摄影随笔杂志” - “生成具有网格布局的杂志”

1. 下载PDF：生成后，PDF将出现在预览面板中供下载

项目结构

research-zine-generator/
├── agent/
│   ├── ui-agent.py          # Main Gradio application (Python)
│   └── requirements.txt     # Python dependencies
├── assets/
│   └── images/
│       └── input/           # Upload images here (or via UI)
├── servers/
│   ├── image-resources-mcp/ # Image resource server (Python)
│   ├── typst-mcp-server/    # Zine generation server (Python)
│   ├── exif-mcp/            # Image metadata server (TypeScript/Node.js)
│   └── image-analyzer-mcp/  # Image analysis server (Python, optional)
├── examples/                # Example zine configurations (JSON)
├── logs/                    # Log files from MCP servers
├── .env.example            # Environment variable template (reference only)
├── setup.sh                # Automated setup script (Bash)
└── README.md               # This file

Language Breakdown:
- Python: agent/, servers/image-resources-mcp/, servers/typst-mcp-server/, servers/image-analyzer-mcp/
- TypeScript/Node.js: servers/exif-mcp/
- Bash: setup.sh
- JSON: examples/

故障排除

“找不到Python虚拟环境”

• 跑 python3 -m venv .venv 创建虚拟环境
• 确保您位于项目根目录中

“找不到服务器”错误

• 确保所有服务器目录都存在于 servers/
• 运行安装脚本以安装依赖项
• 对于exif mcp，请确保 npm run build 成功了

“未设置AZURE_INFERENCE_ENDPOINT”

• 重要：此应用程序使用 控制台环境变量，不 .env 文件
• 在运行应用程序之前，在终端中设置环境变量：

- Linux/macOS: export AZURE_INFERENCE_ENDPOINT="..." 和 export AZURE_INFERENCE_CREDENTIAL="..." - Windows（PowerShell）: $env:AZURE_INFERENCE_ENDPOINT="..." 和 $env:AZURE_INFERENCE_CREDENTIAL="..."

• 验证值是否正确（在export/set命令中使用引号）
• 有关详细说明，请参阅上面的“环境变量”部分

PDF生成后未显示

• 检查 servers/typst-mcp-server/output/ 目录
• 在聊天界面中查找错误消息
• 验证Typst是否已安装： pip install typst

端口7860已在使用中

• 更改端口 agent/ui-agent.py:

  demo.launch(server_port=7861)  # Use a different port

发展

添加新的MCP服务器

1. 将服务器目录添加到 servers/
2. 安装服务器依赖项
3. 将服务器配置添加到 agent/ui-agent.py 在 mcpServers 字典

测试

使用MCP检查器测试单个MCP服务器：

Python服务器：

# Typst MCP Server
npx @modelcontextprotocol/inspector python servers/typst-mcp-server/server.py

# Image Resources MCP
npx @modelcontextprotocol/inspector python servers/image-resources-mcp/server.py

# Image Analyzer MCP (if enabled)
npx @modelcontextprotocol/inspector python servers/image-analyzer-mcp/image_analyzer_server.py

Node.js服务器：

# exif-mcp
npx @modelcontextprotocol/inspector node servers/exif-mcp/dist/server.js

官方文件

本项目所用技术的官方文档链接：

• mcp使用：用于创建代理/客户端和编排MCP服务器的框架

- https://docs.mcp-use.com/home

• FastMCP：快速模型上下文协议服务器框架

- https://gofastmcp.com/

• 奥拉玛：用于运行本地LLM模型（可选，用于图像分析器MCP）

- https://docs.ollama.com/

• Gradio：Web界面框架

- https://www.gradio.app/docs/python-client/introduction

• LangChain：用于代理编排的LLM框架

- https://docs.langchain.com/