rs MCP

rs mcp

MCP服务器+格鲁吉亚税务服务（rs.ge）的CLI。将运单、发票和纳税人SOAP API作为AI可调用工具公开。从同一代码库中提供两个接口：

• 命令行界面 (rs-cli)--与脚本和AI代理的子命令、JSON输出相同的85个操作
• 克劳德技能 — skills/rs-ge/ 文件夹，上传到Claude.ai或Claude Code，教Claude如何使用这些工具

服务范围：

主要特点：

• 对运单、发票、纳税人信息、参考数据的只读查询
• 运单和发票的完整CRUD（创建、发送、确认、拒绝、关闭、删除）
• 所有破坏性MCP操作的人在回路（HITL）安全
• 具有交互式的CLI [y/N] 破坏性命令的确认(--yes 跳过）
• 自动SOAP信封构造和XML响应解析

______________________________________________________________________

先决条件

• Node.js >=18（使用本地 fetch)
• npm
• MCP兼容客户端 --Cursor、Claude Desktop、Windsurf、Continue或任何支持MCP的代理/IDE
• rs.ge服务用户帐户 （通过rs.ge电子申报门户创建的子用户）

______________________________________________________________________

快速开始

1.克隆并安装

git clone  rs-mcp
cd rs-mcp
npm install

2.配置环境

复制示例文件并填写您的凭据：

cp .env.example .env

编辑 .env:

RS_SU=your_username:your_tin
RS_SP=your_password
RS_BASE_URL=https://services.rs.ge/WayBillService/WayBillService.asmx
RS_INVOICE_URL=https://www.revenue.mof.ge/ntosservice/ntosservice.asmx
RS_USER_ID=0
RS_TAX_URL=https://services.rs.ge/taxservice/taxpayerservice.asmx

看 环境变量 了解每个变量的详细信息。

3.建造

npm run build

这将从以下位置编译TypeScript src/ 进入 dist/.

4.连接到您的MCP客户端

服务器使用 stdio传输 --MCP客户端生成进程并通过stdin/stdout进行通信。配置因客户端而异：

光标 --创建 .cursor/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "rs-mcp": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/rs-mcp"
    }
  }
}

克劳德桌面版 --编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "rs-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/rs-mcp/dist/index.js"]
    }
  }
}

其他客户 --查阅客户的MCP文档。服务器入口点为 node dist/index.js 工作目录设置为项目根目录。

重要提示： 不运行 npm start 在正常使用过程中手动操作。您的MCP客户端生成服务器进程本身。更改后，使用重建 npm run build 并从客户端的设置中重新启动MCP服务器。

______________________________________________________________________

CLI快速入门

建成后，使用 rs-cli 二进制直接：

# Reference data (no auth needed for most)
node dist/cli.js reference waybill-types
node dist/cli.js reference units

# Waybill queries
node dist/cli.js waybill get 12345
node dist/cli.js waybill list --from 2025-01-01 --to 2025-03-31
node dist/cli.js waybill list --buyer-tin 123456789 --statuses 1

# Waybill actions (prompts [y/N] before executing)
node dist/cli.js waybill send 12345
node dist/cli.js waybill send 12345 --yes    # skip prompt

# Invoice
node dist/cli.js invoice seller-list --un-id 999 --from 2025-01-01 --to 2025-03-31
node dist/cli.js invoice get 456

# Taxpayer
node dist/cli.js taxpayer info 123456789
node dist/cli.js taxpayer dashboard

# Pretty-print JSON
node dist/cli.js waybill get 12345 --pretty

或者全局安装并使用 rs-cli 直接：

npm install -g .
rs-cli reference waybill-types

所有命令都输出JSON。使用 --pretty 强制格式化输出（在TTY上自动启用）。

全球旗帜：

有关完整的命令参考，请参见 skills/rs-ge/references/.

______________________________________________________________________

克劳德技能

这 skills/rs-ge/ 文件夹是正确的 克劳德代理技能上传它来教Claude如何使用MCP工具和CLI。

在第.ai条中安装：

1. 拉上拉链 skills/rs-ge/ 文件夹
2. 首选 设置→ 能力→ 技能→ 上传技巧

在Claude代码中安装： 放置 skills/rs-ge/ Claude Code技能目录中的文件夹。

______________________________________________________________________

环境变量

RS_SU 和 RS_SP 在所有三个服务中共享。运单和发票服务会自动将它们作为 su/spTaxPayer服务按方法显式传递它们（凭据参数名称因方法而异）。

______________________________________________________________________

项目结构

rs-mcp/
├── .env                        # Credentials (git-ignored)
├── .env.example                # Template for .env
├── package.json                # bin: { "rs-cli": "./dist/cli.js" }
├── tsconfig.json
├── skills/
│   └── rs-ge/                  # Claude Agent Skill (upload to Claude.ai / Claude Code)
│       ├── SKILL.md            # Skill definition with YAML frontmatter
│       └── references/         # Detailed command docs (loaded by Claude on demand)
│           ├── waybill.md
│           ├── invoice.md
│           └── taxpayer.md
└── src/
    ├── index.ts                # MCP entry point -- creates server, registers all tools
    ├── cli.ts                  # CLI entry point -- parseArgs router (rs-cli binary)
    ├── config.ts               # Loads environment variables
    ├── confirm.ts              # HITL pending-action store and execution logic
    ├── mcp-confirm.ts          # MCP wrapper: wraps queueAction with MCP content format
    ├── output.ts               # CLI JSON printer (pretty on TTY, compact when piped)
    ├── prompt.ts               # CLI readline [y/N] confirmation prompt
    ├── soap/
    │   ├── client.ts           # SOAP client for WayBill & Invoice (tempuri.org namespace)
    │   └── tax-client.ts       # SOAP client for TaxPayer (services.rs.ge namespace)
    ├── xml/
    │   ├── parser.ts           # XML-to-JSON parser (fast-xml-parser)
    │   └── waybill-builder.ts  # Structured JSON to Waybill XML converter
    ├── commands/               # CLI command handlers (one file per domain)
    │   ├── waybill.ts
    │   ├── invoice.ts
    │   ├── taxpayer.ts
    │   ├── reference.ts
    │   ├── helpers.ts
    │   └── confirm.ts
    ├── tools/                  # MCP tool registrations (one file per domain)
    │   ├── reference.ts
    │   ├── waybill.ts
    │   ├── waybill-write.ts
    │   ├── helpers.ts
    │   ├── invoice.ts
    │   ├── invoice-query.ts
    │   ├── invoice-desc.ts
    │   ├── invoice-helpers.ts
    │   ├── taxpayer.ts
    │   ├── taxpayer-reports.ts
    │   ├── taxpayer-auth.ts
    │   └── confirm.ts
    └── types/
        ├── reference.ts
        ├── waybill.ts
        ├── invoice.ts
        └── taxpayer.ts

______________________________________________________________________

建筑

flowchart LR
    Client["MCP Client\n(Cursor, Claude Desktop, etc.)"] -->|stdio| McpServer["MCP Server\n(index.ts)"]
    Terminal["Terminal / Script"] -->|argv| CLI["CLI\n(cli.ts → rs-cli)"]

    McpServer --> Tools["MCP Tools\n(tools/)"]
    CLI --> Commands["CLI Commands\n(commands/)"]

    subgraph soap_layer [Shared SOAP Layer]
        SoapClient["callSoap / callSoapXml\n(tempuri.org)"]
        TaxClient["callTaxSoap\n(services.rs.ge)"]
    end

    subgraph hitl_mcp [MCP HITL]
        Queue["queueAction → preview"]
        Execute["confirm_action → execute"]
    end

    Tools -->|read-only| SoapClient
    Tools -->|destructive| Queue
    Queue --> Execute
    Execute --> SoapClient

    Commands -->|read-only| SoapClient
    Commands -->|destructive: prompt y/N| SoapClient

    Tools -->|read-only| TaxClient
    Commands --> TaxClient

    SoapClient --> RS_WB["rs.ge\nWayBill API"]
    SoapClient --> RS_INV["rs.ge\nInvoice API"]
    TaxClient --> RS_TAX["rs.ge\nTaxPayer API"]

数据流——MCP：

1. MCP客户端通过stdio发送工具调用
2. 只读工具直接调用SOAP并返回JSON
3. 破坏性工具排队操作（HITL），返回预览，等待 confirm_action

数据流-CLI：

1. 用户运行 rs-cli [flags]
2. 只读命令调用SOAP并打印JSON
3. 破坏性命令提示 [y/N] （或跳过 --yes)，然后直接调用SOAP

______________________________________________________________________

人在环（HITL）安全系统

所有32个破坏性工具（创建、更新、删除、发送、确认、拒绝）都使用两阶段确认系统来防止意外的数据更改。

运作原理

sequenceDiagram
    participant User
    participant AI as AI Assistant
    participant Tool as Destructive Tool
    participant Store as Pending Store
    participant Confirm as confirm_action
    participant SOAP as rs.ge API

    User->>AI: "Delete waybill #12345"
    AI->>Tool: del_waybill(waybill_id=12345)
    Tool->>Store: queueAction(...)
    Store-->>Tool: action_id + preview
    Tool-->>AI: Preview with action_id
    AI-->>User: "This will delete waybill #12345. Confirm?"
    User->>AI: "Yes, confirm"
    AI->>Confirm: confirm_action(action_id, "CONFIRM")
    Confirm->>Store: executeAction(action_id)
    Store->>SOAP: Actual SOAP call
    SOAP-->>Store: Result
    Store-->>Confirm: Result
    Confirm-->>AI: Result JSON
    AI-->>User: "Waybill #12345 deleted successfully"

关键规则

• 未决行动 5分钟后过期
• 人工智能 必须显示预览 发送给用户并等待明确批准
• confirm_action 需要 confirmation_text: "CONFIRM" --人工智能无法自动确认
• 使用 reject_action 取消排队的操作
• 使用 list_pending_actions 查看所有等待确认的操作

HITL工具

______________________________________________________________________

工具参考

运单参考（5个工具）

获取运单字段的参考/查找数据。全部为只读，不需要参数。

______________________________________________________________________

运单读取（6个工具）

查询和过滤运单。全部为只读。

运单状态： 0=已保存， 1=活动， 2=关闭， 8=发送给运输商， -1=已删除， -2=已取消

______________________________________________________________________

运单书写（9个工具）

创建、激活、关闭和管理运单。所有破坏性（HITL保护）。

运单类型： 1=内部， 2=运输， 3=无运输， 4=分布， 5=返回， 6=子运单

货物清单项目字段： w_name, unit_id, quantity, price，并且可选 unit_txt, bar_code, a_id, vat_type, quantity_ext

______________________________________________________________________

运单助手（4个工具）

用于运单相关查找的实用工具。全部为只读。

______________________________________________________________________

发票CRUD和状态（12个工具）

创建、管理和控制发票生命周期。8破坏性+4只读。

发票状态： -1=已删除， 0=已保存， 1=已发送， 2=确认， 3=校正后的初级， 4=校正， 5=已发送校正， 6=已取消发送， 7=取消确认， 8=已确认更正

校正类型(k_type): 1=取消操作， 2=更改操作类型， 3=价格/补偿变化， 4=退货

______________________________________________________________________

发票查询（9个工具）

搜索并列出发票。全部为只读。

______________________________________________________________________

发票商品和链接（6个工具）

管理发票上的货物行项目和运单链接。4个破坏性+2个只读。

增值税金额(drg_amount): 正=正常增值税， 0 =零利率， -1 =免税

______________________________________________________________________

发票助手（13个工具）

查询、消费税代码、服务用户和发票请求。3破坏性+10只读。

______________________________________________________________________

纳税人信息（8个工具）

查询纳税人信息和查找。全部为只读。

注： 某些纳税人方法可能需要对您的子用户帐户进行额外的服务激活或两步短信验证。返回“授权错误”的方法可能需要通过rs.ge门户激活。

______________________________________________________________________

纳税人报告（8个工具）

财务报告和海关数据。7只读+1破坏性。

______________________________________________________________________

纳税人认证（4个工具）

基于短信的两步身份验证，用于敏感的纳税人操作。2个只读+2个破坏性。

______________________________________________________________________

SOAP服务参考

服务器与三个rs.ge SOAP端点通信：

运单服务

• 端点： https://services.rs.ge/WayBillService/WayBillService.asmx
• 命名空间： http://tempuri.org/
• 认证： su （用户名：TIN）和 sp （密码）自动注入到每个请求中
• 客户： src/soap/client.ts -- callSoap() 和 callSoapXml()

发票服务（NTOS）

• 端点： https://www.revenue.mof.ge/ntosservice/ntosservice.asmx
• 命名空间： http://tempuri.org/
• 认证： 相同 su/sp 证书，加 user_id 注射用于大多数方法
• 客户： 相同 callSoap() 定制 baseUrl

纳税人服务

• 端点： https://services.rs.ge/taxservice/taxpayerservice.asmx
• 命名空间： services.rs.ge
• 认证： 每个方法显式传递的凭据（参数名称各不相同： UserName, userName, inUserName, user)
• 客户： src/soap/tax-client.ts -- callTaxSoap()

______________________________________________________________________

发展

构建

npm run build    # Compiles TypeScript to dist/

跑

# MCP server (normally spawned by your MCP client, not run manually)
npm start                      # node dist/index.js

# CLI
node dist/cli.js               # show usage
node dist/cli.js reference waybill-types
node dist/cli.js waybill list --from 2025-01-01 --to 2025-03-31

技术栈

• TypeScript --严格模式，ES2022目标，Node16模块
• ES模块 ("type": "module")
• @模型上下文协议/sdk --MCP服务器框架
• 动物圈 --MCP输入模式验证
• 快速xml解析器 --XML响应解析
• Dotenv。 --环境变量加载
• 节点：util parseArgs --CLI参数解析（无外部框架）

添加新的MCP工具

1. 添加到中的现有文件 src/tools/ （或创建一个新的）
2. 使用 server.tool(name, description, schema, annotations, handler)
3. 注释：

   const READONLY = { readOnlyHint: true, destructiveHint: false } as const;
   const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true } as const;

1. 破坏性工具：使用 mcpQueueAction() 从 ../mcp-confirm.js 而不是直接调用SOAP
2. 出口 register*Tools(server: McpServer) 并把它叫进来 src/index.ts

添加新的CLI命令

1. 添加到匹配文件中 src/commands/
2. 只读：直接调用SOAP output(result)
3. 破坏性：提示 confirm() 从 ../prompt.js，或检查 flags.yes
4. 注册任何新 --flag 名字在 parseArgs 选项块 src/cli.ts

添加新的SOAP服务

1. 将端点添加到 src/config.ts 和 .env.example
2. 在中创建SOAP客户端 src/soap/ 如果命名空间不同
3. 在中添加类型接口 src/types/
4. 在中添加MCP工具 src/tools/ 和CLI命令 src/commands/

______________________________________________________________________

许可证

ISC