使用说明

锌发生器研究

一个自包含的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个步骤）

下载或获取项目文件:
- 将项目文件解压缩到您选择的目录中
- 导航到项目目录： cd research-zine-generator

运行安装脚本:

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

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

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适配器和配置。
激活虚拟环境 （发射前需要）：

Linux/macOS：
```
source .venv/bin/activate
```
Windows（PowerShell）：
```
.venv\Scripts\activate
```
Windows（命令提示符）：
```
.venv\Scripts\activate.bat
```
备注：安装脚本在安装过程中自动激活虚拟环境。关闭终端或启动新会话后，您需要在运行应用程序之前再次激活它。
启动应用程序:
```
python agent/ui-agent.py
```

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

详细的设置说明

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

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

创建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

升级pip:
```
pip install --upgrade pip
```
安装Python依赖项:
```
pip install -r agent/requirements.txt
```

安装服务器依赖项:

# 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

安装其他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

安装并构建exif mcp （Node.js服务器）：
```
cd servers/exif-mcp
npm install
npm run build
cd ../..
```
备注：如果未安装Node.js，exif mcp服务器将无法工作。请从以下位置安装Node.js 18+https://nodejs.org/如果需要的话。

设置环境变量 （必填）：

应用程序使用 控制台环境变量，不 .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。要启用它们，请执行以下操作：

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

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

设置步骤：
- 安装Ollama：https://ollama.ai
- 拉一个视觉模型（模型必须支持视觉/图像理解）：
```
ollama pull llama3.2-vision:11b
```
- 默认Ollama服务器地址为 http://localhost:11434 （如果使用默认值，则不需要配置）
- 重要：如果你想使用不同的视觉模型，你必须：
  1. 拉动模型： ollama pull <model-name>
  2. 更新中的模型名称 agent/ui-agent.py 在Image Analyzer服务器配置中
  3. 确保您选择的模型支持视觉功能
- 取消注释中的服务器配置 agent/ui-agent.py
意象魔术mcp：需要单独安装

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

用管道安装 （推荐）：
```
pipx install imagesorcery-mcp
```
安装后设置 （必填）：
```
imagesorcery-mcp --post-install
```
这一步至关重要——它下载所需的模型，并尝试从GitHub安装clip Python包。

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

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

用法

上传图像：使用上传按钮将图像添加到图库
与AI聊天：请AI创建一个杂志，例如：
- “用我的所有图片创建一个杂志”
- “制作一本带标题的摄影随笔杂志”
- “生成具有网格布局的杂志”
下载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服务器

将服务器目录添加到 servers/
安装服务器依赖项
将服务器配置添加到 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/

使用说明

锌发生器研究

特性

快速开始

先决条件

设置（3个步骤）

详细的设置说明

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

环境变量

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

可选的

MCP服务器

主服务器（始终启用）

可选服务器

用法

项目结构

故障排除

“找不到Python虚拟环境”

“找不到服务器”错误

“未设置AZURE_INFERENCE_ENDPOINT”

PDF生成后未显示

端口7860已在使用中

发展

添加新的MCP服务器

测试

官方文件

相关 MCP

PRD生成服务

多模态AI生成服务器

游戏资产生成器

Blender自然语言3D建模工具

Seedream 图像生成 MCP 服务

UI设计生成工具