RS.ge Waybill MCP Server

RS.ge运单MCP服务器

 ](https://nodejs.org/) 

MCP（模型上下文协议）服务器 它将RS.ge运单SOAP API与Claude Desktop集成在一起，实现了格鲁吉亚税务系统运单的自然语言查询。

______________________________________________________________________

📋 目录

• 快速开始
• 特性
• 文档
• 安装
• 配置
• 使用示例
• 故障排除
• 发展
• 项目结构

______________________________________________________________________

🚀 快速开始

# 1. Install dependencies
npm install

# 2. Configure credentials
cp .env.example .env
# Edit .env with your RS.ge credentials

# 3. Build
npm run build

# 4. Configure Claude Desktop
# Windows: %APPDATA%\Claude\claude_desktop_config.json
# Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

# Add to config:
{
  "mcpServers": {
    "rs-waybill": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_PROJECT/dist/index.js"]
    }
  }
}

# 5. Restart Claude Desktop

# 6. Test in Claude
"Show me waybills from October 19-21, 2025"

______________________________________________________________________

✨ 特性

• ✅ 自然语言接口 -通过Claude聊天查询运单
• ✅ 日期范围查询 -获取特定时期的运单
• ✅ TIN查询 -从税号中获取公司名称
• ✅ 词典 -访问错误代码、akciz代码、运单类型
• ✅ 类型安全 -具有严格类型的完整TypeScript
• ✅ 错误处理 -自动重试和详细日志记录
• ✅ 生产就绪 -使用真正的RS.ge API进行测试

______________________________________________________________________

📚 文档

综合指南 docs/ 文件夹：

对于用户

• 安装和部署指南 -安装、配置、故障排除

对于开发者

• 项目文档 -架构、组件、数据流
• RS.ge API最佳实践 -吸取重要经验教训并纠正API模式
• MCP开发指南 -如何构建MCP服务器

______________________________________________________________________

📦 安装

先决条件

• Node.js 18+ (下载)
• 克劳德桌面版 (下载)
• RS.ge证书 -服务用户和密码

设置步骤

1. 获取代码

   git clone  MCPWaybill
   cd MCPWaybill

1. 再进行

   npm install

1. 配置环境

   cp .env.example .env

编辑 .env:

   RS_SERVICE_USER=4053098841:405309884
   RS_SERVICE_PASSWORD=YourPasswordHere

1. 构建

   npm run build

1. 配置Claude桌面

编辑 claude_desktop_config.json:

   {
     "mcpServers": {
       "rs-waybill": {
         "command": "node",
         "args": [
           "C:\absolute\path\to\MCPWaybill\dist\index.js"
         ]
       }
     }
   }

⚠️ 重要提示： 使用绝对路径！

1. 重新启动克劳德桌面 （完全退出，然后重新启动）

______________________________________________________________________

⚙️ 配置

环境变量

创建 .env 文件：

# Required
RS_SERVICE_USER=username:company_id
RS_SERVICE_PASSWORD=your_password

# Optional
LOG_LEVEL=info

配置文件

编辑 config/config.json 对于高级设置：

{
  "api": {
    "timeout": 30000,
    "retries": 3
  },
  "logging": {
    "level": "info",
    "console": true
  }
}

______________________________________________________________________

💬 使用示例

获取运单

User: Show me waybills from October 19-21, 2025

Claude: I'll retrieve those waybills for you.
[Uses rs_get_waybills tool]

Found 61 waybills:
- October 19: 12 waybills
- October 20: 32 waybills
- October 21: 17 waybills
...

查找公司

User: What company has TIN 405309884?

Claude: [Uses rs_lookup_tin tool]
Company: შპს თეისთი

获取错误代码

User: Show me RS.ge error codes

Claude: [Uses rs_get_error_codes tool]
Error codes:
- -1072: Date range issue
- -101: Missing seller_un_id
...

______________________________________________________________________

🛠️ 故障排除

服务器未在Claude中显示

1. 检查绝对路径 claude_desktop_config.json
2. 验证 dist/index.js 存在
3. 完全重新启动克劳德桌面
4. 检查开发人员工具（查看→ 切换开发人员工具）

身份验证错误

1. 验证中的凭据 .env
2. 检查格式： username:company_id
3. 确保没有空格： RS_SERVICE_USER=value （不是 RS_SERVICE_USER = value)

工具不工作

1. 检查日志： tail -f logs/mcp-server.log
2. 测试：“显示昨天的运单”
3. 验证日期格式：YYYY-MM-DD

看 故障排除指南 获取详细帮助。

______________________________________________________________________

👨‍💻 发展

脚本

npm run build   # Compile TypeScript
npm run dev     # Build and run
npm run watch   # Auto-rebuild on changes

项目结构

src/
├── index.ts              # MCP server entry point
├── config/               # Configuration management
├── services/             # RS.ge API client & XML parsing
│   ├── soap-client.ts    # SOAP API client
│   └── xml-parser.ts     # XML handling
├── tools/                # MCP tools
│   ├── get-waybills.ts
│   ├── get-dictionaries.ts
│   └── lookup-tin.ts
├── types/                # TypeScript types
└── utils/                # Utilities

关键技术

• @模型上下文协议/sdk -MCP框架
• 阿西奥斯 -HTTP客户端
• 快速xml解析器 -XML解析
• 温斯顿 -日志记录
• 萨德 -验证

______________________________________________________________________

🎯 关键经验教训

该项目解决了复杂的RS.ge API集成难题：

正确使用API

XML解析

• 过滤掉 @_ 提取数据前的属性
• 处理单个和数组响应

看 RS_GE_API_BEST_PRACTICES.md 了解完整细节。

______________________________________________________________________

📄 许可证

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

______________________________________________________________________

🤝 贡献

1. 复刻仓库
2. 创建特征分支
3. 进行更改
4. 彻底测试
5. 提交拉取请求

______________________________________________________________________

📞 支持

• 文档： docs/
• 问题： GitHub问题
• 问题： 先检查文档

______________________________________________________________________

🏆 致谢

• Anthropic -克劳德桌面和MCP SDK
• RS.ge -运单SOAP API
• 社区 -测试和反馈

______________________________________________________________________

版本： 1.0.0\ 状态： 生产就绪✅\ 最后更新时间： 2025年1月

内置于❤️ 使用TypeScript和MCP SDK