使用说明

XML转换器MCP服务器

A. 模型上下文协议（MCP）HTTP服务器 它将入境旅游XML结构转换为出境运输订单格式。使用TypeScript/Node.js构建，支持stdio和HTTP流式传输。

🎯 特性

✅ 单MCP工具: transform_xml 对于入境→出站XML转换
✅ 双重运输支持：stdio（用于MCP客户端）和HTTP（用于web客户端）
✅ 完整的数据映射：处理旅游、货运、车站、物品和多级参数
✅ 生产就绪：完整的错误处理、验证和全面的测试
✅ 类型安全：通过严格验证完成TypeScript实现

🚀 快速开始

安装

# Install dependencies
npm install

# Build the project
npm run build

运行服务器

# Run with stdio transport (default - for MCP clients)
npm start

# Run with HTTP streamable transport (for web clients)
npm run start:http

# Development mode with auto-reload
npm run dev        # stdio transport
npm run dev:http   # HTTP transport

发展

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Clean build directory
npm run clean

🐳 容器部署

波德曼部署（推荐）

使用Podman和提供的PowerShell脚本将XML Transformer MCP服务器部署为容器。

先决条件

波德曼 -容器运行时(安装指南)
PowerShell 5.1+（Windows PowerShell或PowerShell核心）

快速部署

# Deploy with default settings (production, port 3100)
.\deploy.ps1

# Deploy with custom settings
.\deploy.ps1 -Port 3101 -Environment dev

集装箱详细信息

图像名称: ci-transport-mapper-mcp-http:latest
容器名称: ci-transport-mapper-mcp-http
默认端口: 3100
健康检查：每30秒自动监测一次
自动重启：除非手动停止

容器管理

# View real-time logs
podman logs -f ci-transport-mapper-mcp-http

# Stop the container
podman stop ci-transport-mapper-mcp-http

# Restart the container
podman restart ci-transport-mapper-mcp-http

# Check container status
podman ps --filter name=ci-transport-mapper-mcp-http

# Remove container (if needed)
podman rm ci-transport-mapper-mcp-http

集装箱特征

✅ HTTP传输：针对web客户端和API访问进行了优化
✅ 健康监测：内置健康检查功能，可自动恢复
✅ 环境隔离：在隔离容器环境中运行
✅ 端口映射：可配置端口映射（默认值：3100）
✅ 自动重启：故障时自动重新启动
✅ 资源标签：标签便于管理和监控

访问已部署的服务器

部署后，可以在以下位置访问服务器：

HTTP端点: http://localhost:3100
状态检查: curl http://localhost:3100
MCP端点: http://localhost:3100/mcp

Docker Compose（替代方案）

您还可以使用Docker Compose进行部署：

# Build and start with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

📡 用法示例

MCP客户端（标准传输）

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/server.js']
});

const client = new Client({}, { capabilities: {} });
await client.connect(transport);

const result = await client.request({
  method: 'tools/call',
  params: {
    name: 'transform_xml',
    arguments: {
      inbound_xml: '<tour id="895851881">...</tour>'
    }
  }
});

MCP客户端（HTTP传输）

import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport({
  baseUrl: 'http://localhost:3100'
});

const client = new Client({}, { capabilities: {} });
await client.connect(transport);

// Use the same request format as above

环境变量

# Transport type (stdio or http)
MCP_TRANSPORT=http

# Port for HTTP transport (default: 3100)
PORT=3100

🔧 XML转换

输入格式（入境旅游）

<tour id="895851881">
    <alphanumeric_number>611441-812203</alphanumeric_number>
    <company_id>454692</company_id>
    <plant>DE Koerdel</plant>
    <vehicle_id>vehicleTanker</vehicle_id>
    <shipment id="556898153">
        <number>611441-2216281</number>
        <station type="loading">
            <company_name>Shell Int. Trading</company_name>
            <from_date>2025-10-20</from_date>
            <from_time>03:33</from_time>
            <!-- ... more station data ... -->
        </station>
        <items>
            <item>
                <pos_number>6766213</pos_number>
                <description>Super E10 S</description>
                <!-- ... more item data ... -->
            </item>
        </items>
        <!-- ... shipment parameters ... -->
    </shipment>
    <!-- ... tour parameters ... -->
</tour>

输出格式（出站传输）

<transport>
    <number>812203</number>
    <shipper_id>454692</shipper_id>
    <plant>DE Koerdel</plant>
    <vehicle_id>vehicleTanker</vehicle_id>
    <shipments>
        <shipment>
            <number>2216281</number>
            <station type="loading">
                <company_name>Shell Int. Trading</company_name>
                <date_time_period>
                    <start>2025-10-20T03:33:00Z</start>
                    <end>2025-10-20T03:43:00Z</end>
                    <timezone>Europe/Berlin</timezone>
                </date_time_period>
            </station>
            <items>
                <item>
                    <pos_number>6766213</pos_number>
                    <description>Super E10 S</description>
                    <!-- ... transformed item data ... -->
                </item>
            </items>
            <!-- ... shipment parameters ... -->
        </shipment>
    </shipments>
    <!-- ... transport parameters ... -->
</transport>

🎯 关键转变

转变	规则
根元素	`<tour>` → `<transport>`
迁移数	`"611441-812203"` → `"812203"` （如果没有连字符，则按原样使用）
日期/时间	单独的字段→ ISO 8601(`2025-10-20T03:33:00Z`)
车站参考	`loading_nr` → `loading_name`
多级参数	运输、装运和项目级别的流程
CDATA清理	从参数值中删除CDATA包装器

📁 项目结构

CI_transport_mapper_mcp_http/
├── src/
│   ├── server.ts                 # Main MCP server entry point
│   ├── tools/
│   │   └── xml-transformer.ts    # XML transformation logic
│   ├── types/
│   │   ├── inbound.ts            # TypeScript interfaces for inbound XML
│   │   ├── outbound.ts           # TypeScript interfaces for outbound XML
│   │   └── index.ts              # Type exports
│   ├── utils/
│   │   ├── xml-parser.ts         # XML parsing utilities
│   │   ├── transformation-utils.ts # Transformation helper functions
│   │   └── validation.ts         # Input/output validation
│   └── mappings/
│       └── field-mappings.ts     # Core transformation logic
├── tests/
│   ├── xml-transformer.test.ts   # Unit tests
│   └── fixtures/                 # Test XML files
├── Examples/
│   ├── inbound.xml               # Sample input
│   ├── outbound.xml              # Sample output
│   └── respond.xml               # Sample response
├── Documentation/
│   ├── MCP_Server_Implementation_Plan.md    # Detailed implementation guide
│   ├── XML_Data_Comparison.md               # Data mapping comparison
│   └── XML_Path_Comparison_Table.md         # Mapping rules reference
├── deploy.ps1                   # Podman deployment script
├── docker-compose.yml           # Docker Compose configuration
├── Dockerfile                   # Container build configuration
└── README.md                    # This file

🧪 测试

该项目包括全面的测试，包括：

✅ 主要改造逻辑 使用真实的XML示例
✅ 边缘案例 用于数字提取（带/不带连字符）
✅ 错误处理 对于无效的XML输入
✅ 多级参数 处理
✅ 日期/时间转换 验证

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Run specific test file
npm test -- xml-transformer.test.ts

🔍 验证

服务器执行全面验证：

输入XML结构：验证所需的旅游元素
输出XML结构：确保有效的传输格式
参数处理：基于可见性规则的过滤器
数据类型：使用Zod模式进行类型安全转换

📊 错误处理

优雅的失败：清除调试错误消息
输入验证：及早捕获格式错误的XML
类型安全：防止TypeScript的运行时错误
日志记录：全面的错误报告

🤝 贡献

分叉存储库
创建要素分支
通过测试进行更改
确保所有测试通过： npm test
提交拉取请求

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🔗 相关文档

容器部署指南 -全面的集装箱部署说明
MCP服务器实施计划 -完整的技术规格
XML数据比较 -数据映射分析
XML路径比较表 -详细的映射规则
模型上下文协议 -MCP官方文件