AI导哈

场景模拟MCP服务器

Mock ItrLoader项目的MCP服务器，用于生成和管理税务返还场景模拟，支持多种流程和错误类型的场景构建。

  • by danny-zent
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 danny-zent/mock-itr-scenario-mcp

使用说明

模拟ITR场景MCP服务器

创建和管理Mock ItrLoader项目方案的模型上下文协议（MCP）服务器。

功能

MCP工具

基本工具

工具 说明
template_list 查看可用方案模板列表
template_load 加载特定模板
scenario_build_normal 创建正常退款方案
scenario_build_error 生成错误方案
scenario_build_progress 创建进度传输方案
scenario_validate 验证方案
scenario_assign 将方案分配给user_ern
scenario_unassign 取消分配方案
error_types_list 查看支持的错误类型列表

Flow特定方案生成工具

工具 说明 Flow
scenario_build_simple_auth [个人]创建简单的身份验证流方案 cert_request→cert_response→check→load
scenario_build_common_cert 创建联合证书流方案 check（common_cert）→load
scenario_build_corp_common_cert 创建联合证书流方案corp_check（common_cert）→corp_load_calc

创建失败方案工具

工具 说明
scenario_build_simple_auth_fail 创建简单身份验证请求（cert_request）失败方案
scenario_build_cert_response_fail 快速验证完成确认（cert_response）生成失败方案

MCP资源

资源 说明
scenario://templates 模板列表
scenario://error-types 支持的错误类型列表
scenario://schema 场景JSON Schema

安装

uv安装

如果未安装uv，可以使用以下命令进行安装：

curl -LsSf https://astral.sh/uv/install.sh | sh
# 또는 macOS/Homebrew
brew install astral-sh/uv/uv
# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex

# uv 사용
uv pip install -e .

# pip 사용
pip install -e .

从GitHub导入和注册MCP服务器的过程

  1. GitHub存储库分支
    • 原始（Upstream）： https://github.com/danny-zent/mock-itr-scenario-mcp
    • 使用组织或个人GitHub帐户创建Fork。
  2. 分支存储库克隆
    git clone https://github.com/<your-org-or-id>/mock-itr-scenario-mcp.git
cd mock-itr-scenario-mcp
  3. 依赖性安装 （上面 설치 请参见步骤）
  4. 验证MCP服务器路径
    • command: uv
    • args: ["run", "-m", "mock_itr_scenario_mcp.server"]
    • cwd：克隆的存储库路径，例如： /Users/danny/git/mock-itr-scenario-mcp)
  5. 将mcpServers条目添加到Cursor/Claude配置文件
    • 光标： ~/.cursor/mcp.json
    • 克劳德桌面： claude_desktop_config.json
    • 如以下示例所示 mcpServers.mock-itr-scenario 添加块并将环境变量设置为所需值
  6. 重新启动编辑器或刷新MCP服务器
    • 光标： ⌘K → “重新加载MCP服务器”
    • Claude Desktop:保存设置后重新启动应用程序

使用方法

Cursor设置

~/.cursor/mcp.json:

{
  "mcpServers": {
    "mock-itr-scenario": {
      "command": "uv",
      "args": ["run", "-m", "mock_itr_scenario_mcp.server"],
      "cwd": "/Users/you/path/to/your-fork/mock-itr-scenario-mcp",
      "env": {
        "MOCK_ITR_MODEL_YEAR": "2024",
        "DYNAMODB_ENDPOINT_URL": "http://localhost:8000"
      }
    }
  }
}

Claude桌面设置

claude_desktop_config.json:

{
  "mcpServers": {
    "mock-itr-scenario": {
      "command": "uv",
      "args": ["run", "-m", "mock_itr_scenario_mcp.server"],
      "cwd": "C:/Users/you/path/to/your-fork/mock-itr-scenario-mcp",
      "env": {
        "MOCK_ITR_MODEL_YEAR": "2024"
      }
    }
  }
}

环境变量

变量 说明 默认值
MOCK_ITR_MODEL_YEAR 归属年份（attr_yr） 2024
DYNAMODB_ENDPOINT_URL DynamoDB端点URL （AWS基本）
SCENARIO_TABLE_NAME DynamoDB表名称 mock-itr-scenarios
AWS_REGION AWS区域 ap-northeast-2

使用示例

查看模板列表

模板是项目根目录的 templates/ 目录中 TPL_*.json 以格式保存。

사용자: "사용 가능한 템플릿 목록 보여줘"

AI: template_list 도구를 사용합니다.

사용 가능한 템플릿:
- TPL_NORMAL_BIZ_HIGH: 개인사업자 고액환급 (5,500,000원)
- TPL_NORMAL_BIZ_LOW: 개인사업자 저액환급 (150,000원)
- TPL_ERR_NO_TAX_RETURN: 종소세신고내역없음 에러
...

创建方案

사용자: "300만원 환급 시나리오 만들어줘"

AI: scenario_build_normal 도구를 사용합니다.

생성된 시나리오:
- 사용자: 테스트사용자
- 환급액: 3,000,000원
- 사업자 유형: 개인사업자

创建特定于Flow的方案

简单认证Flow（个人）

사용자: "카카오 간편인증으로 500만원 환급 시나리오 만들어줘"

AI: scenario_build_simple_auth 도구를 사용합니다.

생성된 시나리오:
- Flow: cert_request → cert_response → check → load
- 사용자: 테스트사용자
- 간편인증: 카카오
- 환급액: 5,000,000원

联合证书Flow（个人）

사용자: "공동인증서로 200만원 환급 시나리오 만들어줘"

AI: scenario_build_common_cert 도구를 사용합니다.

생성된 시나리오:
- Flow: check (common_cert) → load
- 환급액: 2,000,000원

联合证书Flow（实体）

사용자: "법인 공동인증서 시나리오 만들어줘"

AI: scenario_build_corp_common_cert 도구를 사용합니다.

생성된 시나리오:
- Flow: corp_check (common_cert) → corp_load_calc
- 사업체명: 주식회사 테스트사업자

创建失败方案

简单身份验证请求失败

사용자: "카카오 간편인증 요청 실패 시나리오 만들어줘"

AI: scenario_build_simple_auth_fail 도구를 사용합니다.

생성된 시나리오:
- cert_request: 실패
- 에러 타입: 간편인증오류
- 에러 메시지: "카카오톡 간편인증 요청에 실패했습니다. 사용자 정보를 확인해주세요."

无法快速验证完成确认

사용자: "간편인증 완료 확인 실패 시나리오 만들어줘"

AI: scenario_build_cert_response_fail 도구를 사용합니다.

생성된 시나리오:
- cert_request: 성공
- cert_response: 실패
- 에러 타입: 간편인증미완료
- 에러 메시지: "간편인증이 완료되지 않았습니다."

创建错误方案

退款者错误

사용자: "기환급자 에러 시나리오 만들어줘"

AI: scenario_build_error 도구를 사용합니다.

생성된 시나리오:
- 에러 타입: 기환급자
- 발생 액션: load
- 에러 메시지: "2024" (환경변수 MOCK_ITR_MODEL_YEAR 값)
- 설명: 같은 귀속년도에 이미 환급을 받은 사람이 다시 조회(load) 액션을 할 때 발생

无综合所得税申报明细错误

사용자: "종소세 신고내역 없음 에러 시나리오 만들어줘"

AI: scenario_build_error 도구를 사용합니다.

생성된 시나리오:
- 에러 타입: 종소세신고내역없음
- 에러 메시지: "종합소득세 신고 내역이 없습니다."

开发

# 개발 의존성 설치
uv pip install -e ".[dev]"

# 테스트 실행
pytest

# 린트
ruff check .

# 타입 체크
mypy src

方案数据结构

特定于动作的请求/响应数据

每个场景动作 Confluence文档中的API规格包含与匹配的请求/响应数据结构：

  • cert_request：简单的身份验证请求（基于user_info）
  • cert_response：快速验证完成（基于user_info+cert_info）
  • 检查：用户验证（基于token或common_cert，返回tin/cookies）
  • 负载：收集和计算（基于cookies，返回退款结果）
  • 计算：计算（基于export_file_prefix）
  • corp_load_calc：法人收集和计算（基于cookies）

Flow说明

1.[个人]简单认证Flow

사용자정보입력 → cert_request → 사용자 인증완료 → cert_response → check (token) → load

2.[个人]共同证书Flow

인증서정보 → check (common_cert) → load

3.[法人]共同证书Flow

인증서정보 → corp_check (common_cert) → corp_load_calc

主要错误类型

捐赠者（ALREADY_REFUNDED）

  • 具体值动作: load
  • 说明：当同一归属年已收到退税的人再次进行查询（load）操作时发生。
  • 错误消息：环境变量 MOCK_ITR_MODEL_YEAR的值（例如“2024”、“2025”）
  • 示例：2024年已收到退税的用户试图重新查询2024年退税时发生。

无运营商错误（NO_BIZ）

  • 具体值动作: load
  • 说明：HomeTax帐户中没有商家
  • 错误消息：“处理过程中发生异常。[未更改运营商]”

会话过期（SESSION_EXPIRED）

  • 具体值动作: load
  • 说明：收集期间会话过期（需要重试）
  • 错误消息：“会话因重复连接而过期。”

身份证号码错误（INVALID_SSN）

  • 具体值动作: load
  • 说明：由于身份证号码错误，收集失败
  • 错误消息：“请确认商家注册号/身份证号。”

参考资料

相关 MCP