MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致

[kiki830621]

Problem

Finding A1: max_messages: "0" (string) 繞過 <=0 檢查

MCP SDK 的 Value.intValue 只對 .int(...) case 回傳 Int，對 .string(...) 回傳 nil。所以呼叫端送 JSON {"max_messages": "0"}（string 不是 int）會：

1. args["max_messages"]?.intValue 回傳 nil
2. <= 0 檢查被跳過
3. fallback 到 default（get_chat_history: limit; dump_chat_to_markdown: 5000）
4. 使用者無感知

From verification of #5, #6 by devils-advocate:
「實測 MCP SDK Value.intValue 對 .string(...) 回 nil，使用者誤送 JSON string "0" → nil → fallback 到 default 5000，完全繞過 <= 0 檢查」

Finding A2: CLI parseCLIDate + --until 跟 MCP 不同步

CLI 的 parseCLIDate（TelegramAllCLI.swift:148）仍有 #5 修好的 bug：

• 沒 regex pre-check——CLI 會 silently accept 2026/04/17
• --until 沒 end-of-day 語意——CLI 的 --until 2026-04-17 還是 parse 到 00:00:00，漏掉當日訊息

From verification of #5, #6 by regression + devils-advocate:
「CLI history --dump-markdown 和 MCP dump_chat_to_markdown 行為分歧：同一個 2026-04-17 在兩邊的上界語意不一樣」

Type

bug

Expected

• max_messages 若是 string-encoded number（例 "5"）要能正確 parse 或拒絕
• CLI 的 --until 行為跟 MCP until_date 一致（包含整天）
• CLI 的 --since/--until 拒絕非 YYYY-MM-DD 格式

Actual

• MCP handler 對 type-mismatched 輸入靜默忽略
• CLI 對 2026/04/17 等格式 silent accept
• CLI --until 遺漏當日訊息

Strategy

• MCP handler: 當 args["max_messages"] 是 string 時，先 Int(stringValue) parse，parse 失敗回 errorResult → done in parseMaxMessages helper (commit a918b11, refined to use SDK Int(value, strict:false) in f0203ac)
• CLI: 讓 parseCLIDate 和 parseUntilDate 共用 CheTelegramAllMCPCore 的 helpers，或下推到 TelegramAllLib → done by moving DateParsing to TelegramAllLib (commit b7e7899)

Code Reference

• MCP 層：Sources/CheTelegramAllMCPCore/Server.swift:364-375, 484-494
• CLI 層：Sources/telegram-all/TelegramAllCLI.swift:148-158
• MCP SDK 行為：.build/checkouts/swift-sdk/Sources/MCP/Base/Value.swift:42-45

Related: #5, #6

Implementation history

• 2026-04-26: Initial implementation (commits a918b11 + b7e7899)
• 2026-04-26: scope expanded to include .double after max_messages silently falls back to default for .string/.double values (cap bypass) #20 DA finding
• 2026-04-27: verify-stage DA caught strict-reject .double(N.0) regression; fixed via SDK Int(value, strict:false) in f0203ac
• 2026-04-27: verify-stage DA caught CLI ValidationError grammar regression; fixed in 2a05f83

---

Current Status

Phase: closed
Last updated: 2026-04-27 by idd-close

Key Decisions

• A1：用 MCP SDK 自帶的 Int(value, strict: false) 而非自製 dual-path — .int(n) / .double(whole) / .string(numeric) 三條路徑都收，.double(0.5) 正確 reject。avoids cross-language ABI break
• A2：DateParsing 從 MCPCore 移到 TelegramAllLib + public — CLI / MCP 共用一份；CLI 文法保留舊風格 --since must be YYYY-MM-DD; got X
• 順便 subsume max_messages silently falls back to default for .string/.double values (cap bypass) #20（DA finding from Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13 verify，同根因擴展到 .double）
• Direct-commit path（一致於 get_chat_history: from_message_id=0 首次呼叫只回傳 1 則訊息 #3-MCP 層補 handler 行為 unit test（get_chat_history） #7、Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13、Test hardening: int64 helper DRY + boundary + TZ assertions #15）
• 6-AI verify: 4 reviewer + Codex 全 PASS（集體盲點），DA 反駁找出 2 HIGH + 4 MEDIUM + 5 LOW，2 HIGH/MEDIUM in-scope fix

Scope Changes

• DA fix feat(all-mcp): 支援一次抓取完整對話歷史（自動分頁） #1：.double(5000.0) 從 reject 改 accept (commit f0203ac) — 修正 cross-language ABI regression
• DA fix feat(all-mcp): 新增 dump 對話為 Markdown 的 tool #2：CLI ValidationError 從 --since Date format invalid: ... 改回 --since must be YYYY-MM-DD; got X (commit 2a05f83)
• 順便 subsume max_messages silently falls back to default for .string/.double values (cap bypass) #20

Blocking

(none)

Test counts

• 150 → 163 (+13)
• Codex 獨立驗證 swift test 通過 (34 + 14 = 48 隔離 filter tests)

Commits

• a918b11 fix: enforce max_messages type, reject string/double silent fallback (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8, max_messages silently falls back to default for .string/.double values (cap bypass) #20)
• b7e7899 fix: CLI date parity with MCP — share parseISODate/parseUntilDate (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8)
• f0203ac fix: accept whole-number .double via MCP SDK Int(value, strict:false) (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 verify DA F1+F2)
• 2a05f83 fix: CLI date error message reuses old phrasing (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 verify DA F3)
• 6fbfc40 docs: CHANGELOG 0.5.3 — MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8/Test: assert MCP handler error message text (contract test) #11/Test: backward-compat numeric-string chat_id / from_message_id parsing #12 + max_messages silently falls back to default for .string/.double values (cap bypass) #20 subsumed

Subsumed

• max_messages silently falls back to default for .string/.double values (cap bypass) #20 closed as subsumed by MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8

Follow-up

• chat_id type-mismatch error message misleads (silently shows 'is required' instead of type error) #22 chat_id type-mismatch UX (F4)
• parseDumpChatToMarkdownArgs default 5000 bypasses validateMaxMessagesCap (latent invariant) #23 dump default 5000 cap bypass (F5)
• Apply parseMaxMessages pattern to limit and other numeric option args #25 limit consistency (F10)

[kiki830621]

Diagnosis

Type

bug + parity

Analysis

A1 (subsumes #20): Value.intValue 對 .string/.double 回 nil，導致：

• args["max_messages"]?.intValue ?? 5000 當 max_messages 是 .string("0") 時 silently fallback 到 5000，繞過 cap
• 同樣對 .double(20000.0)、.double(0.5)、.string("not-a-number") 都 silently 回到 default
• 影響兩個 parser：parseGetChatHistoryArgs 和 parseDumpChatToMarkdownArgs

A2 (CLI parity): CLI 的 parseCLIDate 與 MCP 的 parseISODate/parseUntilDate 行為分歧：

• CLI 沒 regex pre-check → silently 接受 2026/04/17
• CLI --until 2026-04-17 還在 00:00:00（漏整天訊息）
• MCP 的兩個 helper 在 CheTelegramAllMCPCore，CLI 在 telegram-all target 不能直接 import（依賴鏈不對）

Strategy

A1：抽 parseMaxMessages(_ args:) throws -> Int? helper，對 max_messages 採 coerce 路徑：

• .int(n) → n
• .string(s) → 嘗試 Int(s) 嚴格 base-10 parse
• 都失敗且 key 存在 → throw HandlerArgError("max_messages must be an integer")
• key 不存在 → 回 nil
• 永遠 run validateMaxMessagesCap on parsed value
• 兩個 parser 各自呼叫此 helper，handle nil → default 邏輯

A2：把 DateParsing.swift 從 CheTelegramAllMCPCore 移到 TelegramAllLib 並改 public：

• CLI + MCP 共用同一份
• CLI 的 parseCLIDate 替換為 parseISODate (since) / parseUntilDate (until)
• CLI 用 ValidationError 包裝 DateParseError 加上 --flagName 前綴

Complexity

Simple — 多個小改動，每個邊界清楚。無新抽象（移檔不算新抽象）。

Risks

• 移 DateParsing.swift target 會改動 import；test target 必須跟上
• parseMaxMessages 對 .string("5") 改成接受可能讓 caller 行為變更（之前 silent 5000，現在 5）。但 issue body 明說可接受
• CLI 的 --until 改 end-of-day 是行為變更（但這是 issue 要求）

---

Implementation Plan

Direct-commit path（一致於 #3-#7、#13、#15）。

Phase 1: A1 — type enforcement on max_messages（subsumes #20）

• HandlerArgs.swift 新增 parseMaxMessages(_ args:) throws -> Int? helper（coerce + validate）
• parseGetChatHistoryArgs 改用 parseMaxMessages，保留 fromMsgId==0 → limit 規則
• parseDumpChatToMarkdownArgs 改用 parseMaxMessages，handle nil → 5000
• Test: testMaxMessagesAsStringAccepted — .string("100") → 100
• Test: testMaxMessagesAsStringRejectsBadFormat — .string("not-a-number") → throws
• Test: testMaxMessagesAsStringZeroRejected — .string("0") → throws（不是 fallback 到 default）
• Test: testMaxMessagesAsDoubleRejected — .double(5000.0) → throws
• Test: testDumpMaxMessagesAsStringRejected — .string("0") → throws (parity)
• Test: testDumpMaxMessagesAsDoubleRejected — .double(20000.0) → throws (parity)

Phase 2: A2 — DateParsing 共用 helper

• 建立 Sources/TelegramAllLib/DateParsing.swift (移自 CheTelegramAllMCPCore)
• parseISODate / parseUntilDate / DateParseError 改 public
• 刪除 Sources/CheTelegramAllMCPCore/DateParsing.swift（或保留 import-only stub，看 build pass 哪個簡單）
• CheTelegramAllMCPCore 加 import TelegramAllLib（已有）使用即可
• CLI TelegramAllCLI.swift:148-157 的 parseCLIDate 改用 parseISODate / parseUntilDate
• 把 --until 從 start-of-day 改成 end-of-day（行為對齊 MCP）
• CLI test: 暫無 CLI test target，補一個 TelegramAllLibTests 的 DateParsing test

Phase 3: Verify + CHANGELOG

• swift build pass
• swift test --skip E2ETests: 期待 158+ pass
• CHANGELOG.md [0.5.3] Added/Fixed/Changed sections

Commit strategy

3 atomic commits：

1. Phase 1 — parseMaxMessages helper + 6 new tests
2. Phase 2 — DateParsing 移 TelegramAllLib + CLI 統一 + 1 new test
3. CHANGELOG 收尾（若 Phase 1/2 commit 沒含）

Scope check

✅ A1 + A2 都直接對應 #8 的 Strategy bullets。Phase 1 順便 subsume #20（.double 也修，超出 #8 但 within #20 scope）。

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

Phase 1: A1 — type enforcement on max_messages（subsumes #20）

• HandlerArgs.swift 新增 parseMaxMessages helper（coerce .int(n) / .string(s)，其他 throws）
• parseGetChatHistoryArgs 改用 parseMaxMessages，保留 fromMsgId==0 → limit 規則
• parseDumpChatToMarkdownArgs 改用 parseMaxMessages，handle nil → 5000
• testMaxMessagesAsStringAccepted — .string("100") → 100
• testMaxMessagesAsStringRejectsBadFormat (renamed testMaxMessagesAsStringInvalidRejected)
• testMaxMessagesAsStringZeroRejected — no silent fallback
• testMaxMessagesAsDoubleRejected
• testDumpMaxMessagesAsStringRejected (Zero variant)
• testDumpMaxMessagesAsDoubleRejected

Phase 2: A2 — DateParsing 共用 helper

• 建立 Sources/TelegramAllLib/DateParsing.swift（移自 CheTelegramAllMCPCore）
• parseISODate / parseUntilDate / DateParseError 改 public
• 刪除舊的 Sources/CheTelegramAllMCPCore/DateParsing.swift
• CheTelegramAllMCPCore 加 import TelegramAllLib
• CLI parseCLIDate 改用 parseISODate / parseUntilDate，新增 endOfDay flag
• --until 從 start-of-day 改成 end-of-day（行為對齊 MCP）
• DateParsingTests.swift 加 import TelegramAllLib（既有 21 tests 全保留）
• [~] CLI test addition — skipped: 既有 21 個 DateParsingTests 完全 cover behavior（CLI 是 thin wrapper），加 CLI-specific test 是 redundant；改用 ServerHandlerLogicTests 的 7 個 contract assertion 鎖 message text

Phase 3: Verify + CHANGELOG

• swift build pass
• swift test --skip E2ETests: 160 tests pass (139 → 150 → 156 → 160 across 4 commits)
• CHANGELOG.md [0.5.3] Fixed/Test/Refactored sections

Legend: - [x] done · - [~] skipped (may revisit) · - [-] won't fix (scope)
idd-close will refuse to close if any - [ ] remains in this checklist.

Changes

• a918b11 fix: enforce max_messages type, reject string/double silent fallback (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8, max_messages silently falls back to default for .string/.double values (cap bypass) #20)
• b7e7899 fix: CLI date parity with MCP — share parseISODate/parseUntilDate (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8)
• eeabd91 test: assert MCP handler error message contract (Test: assert MCP handler error message text (contract test) #11) — relevant to MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 A1 message
• 6fbfc40 docs: CHANGELOG 0.5.3 — MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8/Test: assert MCP handler error message text (contract test) #11/Test: backward-compat numeric-string chat_id / from_message_id parsing #12 + max_messages silently falls back to default for .string/.double values (cap bypass) #20 subsumed

Files Changed (#8 scope)

 CHANGELOG.md                                       |  17 +++
 HandlerArgs.swift                                  |  +33 +6
 Sources/.../DateParsing.swift                      | rename + visibility public
 Sources/telegram-all/TelegramAllCLI.swift          |  +14 -10
 Tests/.../DateParsingTests.swift                   |  +1 (import)
 Tests/.../ServerHandlerLogicTests.swift            |  +95 (6 dump-cap + #20 subsume tests)

Test counts

• Before: 150 tests
• After A1: 156 (+6 max_messages type tests)
• All pass

Subsumed

• max_messages silently falls back to default for .string/.double values (cap bypass) #20 (max_messages .string/.double silently bypass cap) — fully covered by parseMaxMessages helper. Will close max_messages silently falls back to default for .string/.double values (cap bypass) #20 with cross-link to MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 commits.

Scope Compliance

所有改動可追溯 #8 A1 / A2 + #20。1 個 transparent skip：CLI-specific test（既有 DateParsingTests 已 cover）。

Next: verification pending

[kiki830621]

Verify: Batch 3 (#8 + #11 + #12 + subsumed #20)

Engine

Agent Team (5 Claude reviewers: requirements / logic / security / regression / devils-advocate) + Codex (gpt-5.5 xhigh) = 6-AI review

要求覆蓋率

• MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 4/4 sub-requirements addressed (FULLY) — type enforcement + DateParsing→TelegramAllLib + CLI parity + --until end-of-day
• Test: assert MCP handler error message text (contract test) #11 1/1 (FULLY in named cases; PARTIALLY if literally "all throws-tests") — 7 contract assertions on key tests
• Test: backward-compat numeric-string chat_id / from_message_id parsing #12 3/3 sub-requirements addressed (FULLY) + 1 dump parity test
• max_messages silently falls back to default for .string/.double values (cap bypass) #20 subsumed: .string + .double rejection now correctly distinguishes type-error vs cap-error after DA fix

Findings（合併去重，按 severity 排序）

#	Severity	Finding	Source	Action
1	—	Behavior 100% equivalent for legitimate .int callers; truth tables verified across 14 cases (logic) and 24 tests pass independently (codex)	team:logic + codex	PASS
2	—	Scope check passed: only 6 files touched, 21 existing DateParsingTests still green after internal → public move	team:regression + codex	PASS
3	—	Visibility expansion (DateParsing → public in TelegramAllLib) is benign — pure parse, no FS/network	team:security	PASS
4	—	validateMaxMessagesCap shared helper continues to be security-positive (single source of truth for cap policy)	team:security	PASS
5	HIGH	parseMaxMessages rejected .double(5000.0) as type-mismatched, but JSON spec allows whole-number doubles. MCP SDK already provides Int(value, strict: false) (Value.swift:320) which uses Int(exactly:) to coerce whole-number doubles correctly. DIY dual-path missed this. In-scope fix f0203ac — replaced 8-line custom logic with single SDK call.	team:devils-advocate	In-scope fix ✓
6	MEDIUM	CLI ValidationError("--since \(e.description)") produces grammatically broken "--since Date format invalid: ..." (reads like flag is named --since Date). In-scope fix 2a05f83 — restored old phrasing "--since must be YYYY-MM-DD; got X" by extracting DateParseError.input directly.	team:devils-advocate	In-scope fix ✓
7	MEDIUM	testChatIdAsStringInvalidThrows asserts "chat_id is required" for .string("not-a-number"), but the field IS provided (just type-mismatched). Inconsistent with max_messages's strict "must be an integer". UX bug.	team:devils-advocate	Follow-up
8	MEDIUM	parseDumpChatToMarkdownArgs default 5000 no longer goes through validateMaxMessagesCap (only when key absent). Currently safe (5000 < 10_000) but if cap policy changes to 1000, default would silently bypass.	team:devils-advocate + logic LOW informational	Follow-up
9	MEDIUM	Exact-match contract tests (#11) lock cap value 10_000 and suggestion text. Cap policy change requires synchronized N-test update. Plan said hasPrefix; implementation chose exact.	team:devils-advocate	Follow-up
10	MEDIUM	Server.swift other numeric option args (limit ?? 50/20/200 at lines 374, 387, 446, 454) still have same silent-fallback pattern that #8 A1 fixed for max_messages. Only half-fixed.	team:devils-advocate	Follow-up
11	LOW	Phase 1 commit a918b11 is "dirty checkpoint" (parseMaxMessages exists but DateParsing still in MCPCore, CLI still inline). Repeat of #13 a834e88 anti-pattern. Third occurrence now.	team:devils-advocate	Won't fix (already past bisect window; future batches should squash phases)
12	LOW	#20 subsume is "ahistorical revisionism" — #8 original scope didn't include .double; expanded after DA finding.	team:devils-advocate	Won't fix (commit message + closing comment of #20 leave full audit trail)
13	LOW	CHANGELOG 0.5.3 mixes 4 issues (#8/#11/#12/#20) in one minor version. Users can't cherry-pick individual fixes.	team:devils-advocate	Won't fix (release cadence preference; can split future)
14	LOW	ServerHandlerLogicTests.swift now 426 lines (CLAUDE.md "200-400 typical"). Trajectory: #7 ~170, #13 ~290, #8/#11/#12 ~430. Approaching 500.	team:devils-advocate	Follow-up
15	LOW	testTarget doesn't explicitly depend on TelegramAllLib in Package.swift (works via transitive); CLI's parseCLIDate wrapper has no direct CLI integration test (relies on underlying 21 DateParsingTests)	team:regression	Won't fix (transitive deps + thin wrapper coverage adequate)

Devil's Advocate 反駁有效率

DA 反駁 4 reviewer + Codex 的「全 PASS」判定，找出 2 個 HIGH (F1+F2 = #5) + 4 MEDIUM + 2 LOW–MEDIUM + 3 LOW。

• 2 個 in-scope fix 已修（日期處理改善: until_date 語義偏差 + parseISODate 靜默 nil #5/max_messages 邊界防護: 加硬上限 + 0/負數處理 #6，commits f0203ac + 2a05f83）
• 4 個 follow-up（MCP 層補 handler 行為 unit test（get_chat_history） #7/MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8/改善 stderr log 格式: ASCII 箭號 + DateParseError internal visibility #9/Input hardening: DateParseError input truncate + since/until range sanity check #10 + Test: handler glue integration (errorResult conversion + tdlib wiring) #14）
• 3 個 won't fix（Test: assert MCP handler error message text (contract test) #11/Test: backward-compat numeric-string chat_id / from_message_id parsing #12/Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13 + Test hardening: int64 helper DRY + boundary + TZ assertions #15，理由透明）

集體盲點被精準抓到：4 reviewer + Codex 都默認「strict reject .double 是 fix bug」，沒人翻 SDK 找 lenient API。Codex 雖驗證 5000 decode 成 .int(5000)，但漏了「caller 主動傳 5000.0」這條 cross-language ABI 路徑。

Codex 獨立貢獻

• 跑 swift test --filter ServerHandlerLogicTests (34 tests pass) + --filter DateParsingTests (14 tests pass) 自驗
• 直接讀 swift-sdk Value.swift Codable decode order，確認 JSON 5000 decode 成 .int(5000)（不是 .double(5000.0)）
• 點出 Test: assert MCP handler error message text (contract test) #11 嚴格解讀為 PARTIALLY（dump 的 throws tests 沒升級到 exact match — 可作為 Test: assert MCP handler error message text (contract test) #11 follow-up）

Scope Check

PASS — 改動限於 6 檔案（HandlerArgs / DateParsing / Server / TelegramAllCLI / 2 tests / CHANGELOG），全部追溯 #8/#11/#12/#20。F1+F2 + F3 in-scope fix 不擴大 scope，反而糾正原始實作的 over-correction。

Tests

• 150 → 163 tests pass, 0 failures
• Codex 獨立驗證 swift test 通過（34 + 14 = 48 隔離 filter tests）

Commits

• a918b11 fix: enforce max_messages type, reject string/double silent fallback (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8, max_messages silently falls back to default for .string/.double values (cap bypass) #20)
• b7e7899 fix: CLI date parity with MCP — share parseISODate/parseUntilDate (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8)
• eeabd91 test: assert MCP handler error message contract (Test: assert MCP handler error message text (contract test) #11)
• 2219206 test: lock backward-compat numeric-string chat_id/from_message_id (Test: backward-compat numeric-string chat_id / from_message_id parsing #12)
• 6fbfc40 docs: CHANGELOG 0.5.3 — MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8/Test: assert MCP handler error message text (contract test) #11/Test: backward-compat numeric-string chat_id / from_message_id parsing #12 + max_messages silently falls back to default for .string/.double values (cap bypass) #20 subsumed
• f0203ac fix: accept whole-number .double via MCP SDK Int(value, strict:false) (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 verify DA F1+F2)
• 2a05f83 fix: CLI date error message reuses old phrasing (MCP handler 型別強制 + CLI parity: max_messages string bypass + CLI date behavior 不一致 #8 verify DA F3)

判決

PASS — 無 blocking findings 留存；2 個 HIGH/MEDIUM in-scope 已修復（f0203ac + 2a05f83）；5 個 valid follow-ups（#7/#8/#9/#10/#14）待 user triage；3 個 informational won't-fix 理由透明。