Larkinmaxim MCP

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: '...'
    }
  }
});

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转换

输入格式（入境旅游）

    611441-812203
    454692
    
DE Koerdel

    vehicleTanker
    
        611441-2216281
        
            Shell Int. Trading
            2025-10-20
            03:33
            
        
        
            
                
6766213

                Super E10 S
                
            
        
        
    
    

输出格式（出站传输）

    812203
    454692
    
DE Koerdel

    vehicleTanker
    
        
            2216281
            
                Shell Int. Trading
                
                    2025-10-20T03:33:00Z
                    2025-10-20T03:43:00Z
                    Europe/Berlin
                
            
            
                
                    
6766213

                    Super E10 S
                    
                
            
            
        
    
    

🎯 关键转变

📁 项目结构

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的运行时错误
• 日志记录：全面的错误报告

🤝 贡献

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

📄 许可证

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

______________________________________________________________________

🔗 相关文档

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