使用说明

合同比较-MCP服务器与多代理编排

利用WIPO提出建议

具有多代理编排功能的模型上下文协议（MCP）服务器，具有用于查询代理的简单web界面。该系统支持多个LLM提供商（Ollama、OpenAI、Anthropic、Google），并协调多个代理来处理复杂的文档管理查询。

特性

符合MCP标准：实施模型上下文协议标准
FastAPI服务器：现代异步Python web框架
多代理编排：智能查询拆分和结果合成
PDF文档上传：通过自动文本提取上传和管理PDF文档
文档选择：通过UI手动选择或从查询文本中自动检测
智能文档匹配：编排器自动匹配查询中的文档名称
灵活的LLM提供商支持：通过UI或环境变量在Ollama（本地）、OpenAI、Anthropic或Google之间切换
模型选择：从所选提供商的可用型号中进行选择
web界面：现代Next.js前端，带有文档管理侧边栏和提供者/模型选择
自动代理发现：自动发现并注册代理
RESTful API：用于代理和文档管理的标准HTTP端点

快速开始

有关详细的设置说明，请参阅设置.md

先决条件

Python 3.11+
Node.js 18+
LLM提供者 （选择一个或多个）：
- 奥拉玛 （本地，免费）：从安装奥拉玛并拉取一个模型： ollama pull llama3:latest
- OpenAI （云，付费）：从获取API密钥 platform.openai.com
- Anthropic （云，付费）：从获取API密钥 console.anthropic.com
- 谷歌（云，付费）：从获取API密钥 ai.google.dev

快速安装

# 1. Clone repository
git clone <repository-url>
cd mcp-server-orchestration  # or whatever you name the repository

# 2. Set up Python backend
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# 3. Set up frontend
cd frontend
npm install
cd ..

# 4. Configure environment
cp env.example .env
# Edit .env with your LLM provider settings (see Configuration section below)

# 5. Start your LLM provider (if using Ollama)
# macOS: Open Ollama.app
# Linux: ollama serve
# For OpenAI/Anthropic/Google: Just add API key to .env

# 6. Start servers
# Terminal 1: MCP Server
source venv/bin/activate
python3 -m uvicorn backend.server.mcp_server:app --host 0.0.0.0 --port 8000

# Terminal 2: Frontend
cd frontend
npm run dev

访问前端 http://localhost:3000

使用系统

选择LLM提供商和型号:
- 使用聊天顶部的下拉菜单选择您的提供商（Ollama、OpenAI等）
- 从该提供商的可用型号中选择一个型号
- 系统将对该查询中的所有LLM调用使用您的选择
上传文档：点击侧边栏中的“上传PDF”上传基于文本的PDF文件
选择文档:
- 手册：选中要查询的文档旁边的复选框
- 自动：只需在查询中提及该文件（例如，“告诉我我的意大利文件”）
提问：在聊天中键入您的查询
- 系统将使用您选择的提供商/型号
- 自动使用所选文档
- 内部代理搜索实际文档文本
- 外部代理查询外部数据库（WIPO等）

建筑

组件

MCP服务器 （Python/FastAPI）
- 协调多代理工作流
- LLM无关架构-支持Ollama、OpenAI、Anthropic、谷歌
- 提供者可以通过UI或默认值根据请求进行切换 LLM_PROVIDER env 是
- 在端口8000上运行
前端（Next.js/React）
- 简单的聊天界面
- 连接到MCP服务器
- 在端口3000上运行
代理
- 内因：使用提取的文本搜索上传的PDF文档
- 外部代理人：查询外部数据库（例如WIPO获取合规信息）
编排器
- 使用LLM分析用户查询
- 从查询文本中自动检测和匹配文档
- 将查询拆分为特定于代理的任务
- 综合多种试剂的结果
- 可以访问所有上传的文档以进行智能路由

工作流程

User Uploads PDF → Text Extraction (pdfplumber) → Storage (filesystem + memory)
                                                              ↓
User Query + Provider/Model Selection → Orchestrator → Query Analysis (LLM)
                              ↓
                    Get Available Documents List
                              ↓
                    Match Documents from Query (LLM + Fallback)
                              ↓
                    Determine Agents Needed
                              ↓
                    Generate Optimized Queries (with document context)
                              ↓
                    Execute Agents (with selected documents + LLM provider)
                              ↓
                    Internal Agent: Uses document text from storage
                    External Agent: Queries external databases
                    (Both use selected LLM provider/model)
                              ↓
                    Compare & Synthesize Results (LLM)
                              ↓
                    Return Final Answer

文档管理

系统支持两种方式选择要查询的文档：

手动选择：用户可以通过侧边栏中的复选框选择文档
自动检测：编排器自动检测查询中提到的文档
- 示例：“告诉我我的意大利文件”→ 自动找到“Italy-111.pdf”
- 作品有变体：“意大利文件”、“日本-111”等。
- 两种方法可以协同工作（手动+自动检测）

API终点

MCP服务器（端口8000）

GET /health -健康检查
GET /api/providers -获取已配置LLM提供程序的列表
GET /api/models?provider=ollama -获取供应商的可用型号

POST /orchestrate -处理用户查询

{
  "query": "your query here",
  "selected_documents": ["document1.pdf", "document2.pdf"],  // Optional
  "provider": "openai",  // Optional: override default provider
  "model": "gpt-4"  // Optional: override default model
}

POST /api/upload -上传PDF文档
- 内容类型： multipart/form-data
- 主体： file （PDF文件）
GET /api/documents -列出所有上传的文档
DELETE /api/documents/{filename} -删除文档
GET /mcp/agents -列出所有注册代理人
GET /mcp/resources -列出所有MCP资源
POST /discover -触发器代理发现

前端（端口3000）

GET / -主聊天界面
POST /api/chat -聊天端点（转发到MCP服务器）

项目结构

mcp-server-orchestration/        # Project root
├── backend/                      # Backend MCP Server (Python/FastAPI)
│   ├── server/
│   │   └── mcp_server.py          # FastAPI server with upload endpoints
│   ├── agents/
│   │   ├── internal_agent.py      # Internal document agent (uses uploaded PDFs)
│   │   └── external_agent.py      # External database agent
│   ├── orchestrator/
│   │   └── orchestrator.py        # Query orchestration with document matching
│   ├── services/
│   │   ├── ollama_service.py      # Ollama API wrapper
│   │   └── document_storage.py    # PDF storage and text extraction
│   ├── uploads/                   # Uploaded PDF files (created on first upload)
│   ├── interfaces/
│   │   └── agent.py               # Agent interface
│   ├── registry/
│   │   └── registry.py            # Agent registry
│   └── discovery/
│       └── agent_discovery.py     # Auto-discovery
├── frontend/                      # Frontend UI (Next.js)
│   ├── app/
│   │   ├── api/chat/route.ts      # Chat API (forwards to MCP server)
│   │   ├── components/
│   │   │   ├── chat.tsx           # Chat UI component
│   │   │   └── document-sidebar.tsx  # Document upload and selection UI
│   │   └── page.tsx               # Main page with sidebar layout
│   └── package.json
├── requirements.txt               # Python dependencies
├── env.example                    # Environment template
├── SETUP.md                       # Detailed setup guide
└── README.md                      # This file

配置

创建一个 .env 文件来自 env.example:

基本配置

PORT=8000
LOG_LEVEL=INFO
ENV=development
ALLOWED_ORIGINS=*

LLM提供程序配置

选项1：Ollama（当地，免费）

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3:latest
# Optional: Add more models for dropdown
OLLAMA_MODELS=llama3:latest,llama3.1:latest,mistral:latest

选项2:OpenAI（云，付费）

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_MODEL=gpt-4
# Optional: Add more models for dropdown
OPENAI_MODELS=gpt-4,gpt-4-turbo,gpt-3.5-turbo

选项3：人工智能（云端，付费）

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-api-key-here
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

选项4：谷歌（云，付费）

LLM_PROVIDER=google
GOOGLE_API_KEY=your-api-key-here
GOOGLE_MODEL=gemini-pro

备注：您可以在中配置多个提供程序 .env。UI将在下拉列表中显示所有已配置的提供程序，您可以根据请求在它们之间进行切换。这 LLM_PROVIDER 变量设置默认提供程序。

文档

设置.md -包含分步说明的全面设置指南
工作流.md -详细的工作流程说明，包括文档上传、处理和LLM提供者架构
QUICKSTART.md -5分钟内起床和跑步的快速入门指南
期货_高盛.md -计划的改进和下一步行动（LangGraph、WIPO整合、代理增强）

主要特征说明

文档上传与管理

上传PDF：使用侧栏“上传PDF”按钮上传基于文本的PDF文件
文本提取：pdfplumber自动从所有页面中提取文本
存储：文档保存到 backend/uploads/ （持久）+缓存在内存中的文本（快速访问）
文档选择:
- 手册：侧边栏中的复选框
- 自动：在查询中提及文件（例如，“意大利文件”→ 找到“Italy-111.pdf”）

如何使用文档

上传：PDF→ 文本提取→ 存储
查询：用户提问（有或没有提及文档）
检测：编排器匹配查询中的文档或使用手动选择
处理：内部代理检索文档文本并将其包含在LLM提示中
回应：LLM搜索实际文档内容以回答

示例用例

“我的意大利合同怎么说？” → 自动检测Italy-111.pdf，搜索它
“比较我的意大利和日本文件” → 查找两者，搜索两者
“我在意大利和澳大利亚的合同中需要改变什么？” → 使用内部代理（意大利文件）+外部代理（澳大利亚合规）

发展

运行测试

pytest

查看日志

MCP服务器日志被写入 /tmp/mcp_server.log:

tail -f /tmp/mcp_server.log

或者使用辅助脚本：

./view_logs.sh

助手脚本

./start_server.sh -通过日志查看启动MCP服务器
./view_logs.sh -查看MCP服务器日志

故障排除

看设置.md 有关详细的故障排除指南。

常见问题：

Ollama没有跑：启动Ollama并验证 curl http://localhost:11434/api/tags
OpenAI/人类/谷歌错误：检查中是否正确设置了API密钥 .env
提供程序未显示在UI中：确保在中设置了API密钥 .env 对于该提供商
端口冲突：终止端口8000或3000上的进程
模块未找到：确保虚拟环境已激活并安装了依赖项

许可证

[在此处添加您的许可证信息]

贡献

创建要素分支
进行更改
添加测试
提交拉取请求