MCP升级服务器
用于Upstage AI服务的MCP服务器的Node.js/TypeScript实现。
特性
- 文档分析：从各种文档类型（PDF、图像、Office文件）中提取结构和内容
- 信息提取：使用自定义或自动生成的模式提取结构化信息
- 模式生成：从文档分析中自动生成提取模式
- 文件分类：将文档分类为预定义的类别（发票、收据、合同等）
- 使用TypeScript构建类型安全
- 双传输支持：stdio（默认）和HTTP Streamable
- 异步/等待模式贯穿始终
- 全面的错误处理和重试逻辑
- 进度报告支持
安装
先决条件
- Node.js 18.0.0或更高版本
- 后台API密钥来自 高端控制台
从npm安装
# Install globally
npm install -g mcp-upstage-server
# Or use with npx (no installation required)
npx mcp-upstage-server从源代码安装
# Clone the repository
git clone https://github.com/UpstageAI/mcp-upstage.git
cd mcp-upstage/mcp-upstage-node
# Install dependencies
npm install
# Build the project
npm run build
# Set up environment variables
cp .env.example .env
# Edit .env and add your UPSTAGE_API_KEY用法
运行服务器
# With stdio transport (default)
UPSTAGE_API_KEY=your-api-key npx mcp-upstage-server
# With HTTP Streamable transport
UPSTAGE_API_KEY=your-api-key npx mcp-upstage-server --http
# With HTTP transport on custom port
UPSTAGE_API_KEY=your-api-key npx mcp-upstage-server --http --port 8080
# Show help
npx mcp-upstage-server --help
# Development mode (from source)
npm run dev
# Production mode (from source)
npm start与Claude Desktop集成
选项1:stdio传输（默认）
{
"mcpServers": {
"upstage": {
"command": "npx",
"args": ["mcp-upstage-server"],
"env": {
"UPSTAGE_API_KEY": "your-api-key-here"
}
}
}
}选项2:HTTP流式传输
{
"mcpServers": {
"upstage-http": {
"command": "npx",
"args": ["mcp-upstage-server", "--http", "--port", "3000"],
"env": {
"UPSTAGE_API_KEY": "your-api-key-here"
}
}
}
}运输选项
stdio传输（默认）
- 优点：设置简单，直接过程通信
- 缺点：仅限单客户端连接
- 用法：默认模式，无需额外配置
HTTP流传输
- 优点：多客户端支持，网络可访问，RESTful API
- 缺点：需要端口管理、网络配置
- 端点:
- POST /mcp -主MCP通信端点 - GET /mcp -服务器发送的事件流 - GET /health -健康检查端点
可用工具
parse_文档
使用Upstage AI的文档数字化API解析文档。
参数：
file_path（必填）：文档文件的路径output_formats（可选）：输出格式数组（例如\['html'、'text'、'markdown'）
支持的格式： PDF、JPEG、PNG、TIFF、BMP、GIF、WEBP
提取信息
使用Upstage Universal information Extraction从文档中提取结构化信息。
参数：
file_path（必填）：文档文件的路径schema_path（可选）：JSON模式文件的路径schema_json（可选）：JSON模式为字符串auto_generate_schema（可选，默认值：true）：如果没有提供，则自动生成架构
支持的格式： JPEG、PNG、BMP、PDF、TIFF、HEIC、DOCX、PPTX、XLSX
generate_schema
使用Upstage AI的模式生成API为文档生成提取模式。
参数：
file_path（必填）：要分析的文档文件的路径
支持的格式： JPEG、PNG、BMP、PDF、TIFF、HEIC、DOCX、PPTX、XLSX
此工具分析文档并自动生成JSON模式，该模式定义了可以从类似文档中提取的结构和字段。然后，生成的模式可以与 extract_information 工具时 auto_generate_schema 设置为 false.
使用案例：
- 为多个类似的文档创建可重用的模式
- 对提取区域有更多的控制
- 确保提取过程中字段命名的一致性
该工具返回可读的模式对象和 schema_json 可以直接复制和使用的字符串 extract_information 工具。
classify文档
使用Upstage AI的文档分类API将文档分类为预定义的类别。
参数：
file_path（必填）：要分类的文档文件的路径schema_path（可选）：包含自定义分类模式的JSON文件的路径schema_json（可选）：包含自定义分类模式的JSON字符串
支持的格式： JPEG、PNG、BMP、PDF、TIFF、HEIC、DOCX、PPTX、XLSX
此工具分析文档并将其分类。默认情况下，它使用一组全面的文档类型，但您可以提供自定义分类类别。
默认类别：
- 发票、收据、合同、简历、银行对账单、税务文件、保险、名片、信件、表格、证书、报告、其他
使用案例：
- 按类型自动排序和组织文档
- 筛选特定处理工作流的文档
- 构建具有自动分类功能的文档管理系统
信息提取模式指南
当 auto_generate_schema 是 false，您需要提供自定义模式。以下是正确格式化的方法：
📋 基本架构结构
架构必须遵循以下确切结构：
{
"type": "json_schema",
"json_schema": {
"name": "document_schema",
"schema": {
"type": "object",
"properties": {
"field_name": {
"type": "string|number|array|object",
"description": "Description of what to extract"
}
}
}
}
}❌ 常见错误
错误： 缺少嵌套结构
{
"company_name": {
"type": "string"
}
}错误： 响应格式不正确
{
"schema": {
"company_name": "string"
}
}错误： 缺少属性包装
{
"type": "json_schema",
"json_schema": {
"name": "document_schema",
"schema": {
"type": "object",
"company_name": {
"type": "string"
}
}
}
}✅ 正确示例
简单架构：
{
"type": "json_schema",
"json_schema": {
"name": "document_schema",
"schema": {
"type": "object",
"properties": {
"company_name": {
"type": "string",
"description": "Name of the company"
},
"invoice_number": {
"type": "string",
"description": "Invoice number"
},
"total_amount": {
"type": "number",
"description": "Total invoice amount"
}
}
}
}
}包含数组和对象的复杂架构：
{
"type": "json_schema",
"json_schema": {
"name": "document_schema",
"schema": {
"type": "object",
"properties": {
"company_info": {
"type": "object",
"properties": {
"name": {"type": "string"},
"address": {"type": "string"},
"phone": {"type": "string"}
},
"description": "Company information"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"item_name": {"type": "string"},
"quantity": {"type": "number"},
"price": {"type": "number"}
}
},
"description": "List of invoice items"
},
"invoice_date": {
"type": "string",
"description": "Invoice date in YYYY-MM-DD format"
}
}
}
}
}🛠️ 架构创建助手
您可以通过编程方式创建模式：
function createSchema(fields) {
return JSON.stringify({
"type": "json_schema",
"json_schema": {
"name": "document_schema",
"schema": {
"type": "object",
"properties": fields
}
}
});
}
// Usage example:
const schema = createSchema({
"company_name": {
"type": "string",
"description": "Company name"
},
"total": {
"type": "number",
"description": "Total amount"
}
});💡 数据类型
"string"：文本数据（姓名、地址等）"number"：数字数据（金额、数量等）"boolean"：真/假值"array"：项目列表"object"：嵌套结构"null"：空值
📝 最佳实践
- 始终包含描述：它们帮助AI了解要提取什么
- 使用特定的字段名称:
invoice_date而不是date - Nest相关字段：对象中的组相关信息
- 验证您的JSON：在使用模式之前使用JSON验证器
- 首先使用简单模式进行测试：在增加复杂性之前，先从基本字段开始
分类模式指南
这 classify_document 该工具使用针对分类任务优化的不同模式格式。以下是如何创建自定义分类模式：
📋 简单分类类别
对于自定义类别，只需提供一个类别对象数组：
[
{"const": "category1", "description": "Description of category 1"},
{"const": "category2", "description": "Description of category 2"},
{"const": "others", "description": "Fallback category"}
]该工具自动将其包装在API的正确架构结构中。
✅ 正确的分类示例
医疗文件分类器：
[
{"const": "prescription", "description": "Medical prescription document"},
{"const": "lab_result", "description": "Laboratory test results"},
{"const": "medical_record", "description": "Patient medical record"},
{"const": "insurance_claim", "description": "Medical insurance claim"},
{"const": "others", "description": "Other medical documents"}
]业务文档分类器：
[
{"const": "purchase_order", "description": "Purchase order document"},
{"const": "delivery_note", "description": "Delivery or shipping note"},
{"const": "quotation", "description": "Price quotation or estimate"},
{"const": "meeting_minutes", "description": "Meeting minutes or notes"},
{"const": "others", "description": "Other business documents"}
]❌ 常见分类错误
错误： 缺少描述字段
[
{"const": "invoice"},
{"const": "receipt"}
]错误： 缺少常量字段
[
{"description": "Invoice document"},
{"description": "Receipt document"}
]错误： 使用不同的字段名称
[
{"value": "invoice", "label": "Invoice document"},
{"type": "receipt", "desc": "Receipt document"}
]💡 分类最佳实践
- 始终包含“其他”类别：为意外的文档类型提供回退
- 使用描述性常数值：明确的类别名称，如“medical_scription”与“doc1”
- 添加有意义的描述：帮助AI理解每个类别代表什么
- 保持类别互斥：避免可能混淆分类的重叠类别
- 限制类别计数：类别太多会降低准确性（建议：3-10个类别）
- 使用一致的命名：始终坚持吃蛇壳或烤肉串
🛠️ 分类类别助手
function createClassificationCategories(categories) {
return JSON.stringify(categories.map(cat => ({
"const": cat.value,
"description": cat.description
})));
}
// Usage example:
const categoriesJson = createClassificationCategories([
{value: "legal_contract", description: "Legal contracts and agreements"},
{value: "financial_report", description: "Financial statements and reports"},
{value: "others", description: "Other document types"}
]);
// Result: Ready to use as schema_json parameter
// [{"const":"legal_contract","description":"Legal contracts and agreements"},{"const":"financial_report","description":"Financial statements and reports"},{"const":"others","description":"Other document types"}]发展
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
# Lint code
npm run lint
# Format code
npm run format
# Clean build artifacts
npm run clean项目结构
mcp-upstage-node/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # MCP server implementation
│ ├── tools/ # Tool implementations
│ │ ├── documentParser.ts
│ │ └── informationExtractor.ts
│ └── utils/ # Utility modules
│ ├── apiClient.ts # HTTP client with retry
│ ├── fileUtils.ts # File operations
│ ├── validators.ts # Input validation
│ └── constants.ts # Configuration constants
├── dist/ # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md输出文件
结果保存到：
- 文档解析：
~/.mcp-upstage/outputs/document_parsing/ - 信息提取：
~/.mcp-upstage/outputs/information_extraction/ - 生成的架构：
~/.mcp-upstage/outputs/information_extraction/schemas/ - 文档分类：
~/.mcp-upstage/outputs/document_classification/
许可证
麻省理工学院