Mock Itr Scenario MCP

模拟ITR场景MCP服务器

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

功能

MCP工具

基本工具

Flow特定方案生成工具

创建失败方案工具

MCP资源

安装

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。

1. 分支存储库克隆

   git clone https://github.com//mock-itr-scenario-mcp.git
   cd mock-itr-scenario-mcp

1. 依赖性安装 （上面 설치 请参见步骤）
2. 验证MCP服务器路径

- command: uv - args: ["run", "-m", "mock_itr_scenario_mcp.server"] - cwd：克隆的存储库路径，例如： /Users/danny/git/mock-itr-scenario-mcp)

1. 将mcpServers条目添加到Cursor/Claude配置文件

- 光标： ~/.cursor/mcp.json - 克劳德桌面： claude_desktop_config.json - 如以下示例所示 mcpServers.mock-itr-scenario 添加块并将环境变量设置为所需值

1. 重新启动编辑器或刷新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"
      }
    }
  }
}

环境变量

使用示例

查看模板列表

模板是项目根目录的 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
• 说明：由于身份证号码错误，收集失败
• 错误消息：“请确认商家注册号/身份证号。”

参考资料

• 模拟ItrLoader
• MCP规范
• MCP Python SDK
• 维兹涅夫退税税额计算Ramda API指南