[design] MCP transport — stdio only or HTTP also

[sotashimozono]

Question

MCP server doiget serve がサポートする transport。

Background

• stdio: 標準入出力経由、ローカル only、Claude Desktop / Cursor / Codex の標準
• HTTP/SSE: ネットワーク経由、cloud / multi-tenant / remote dev 用

Options

A. stdio only (v0.1)

一番 user 多い、実装シンプル、auth 不要。

B. stdio + HTTP from v0.1

container / cloud deployment 即対応。auth design (API key / mTLS) も必要。+3 日。

C. stdio + HTTP + WebSocket

streaming push。+1 週、初期は yagni。

Recommendation

A。90% の user は Claude Desktop / Cursor 経由 = stdio で十分。HTTP は cloud deployment が来てから (incrementally)。

Decision

???

[sotashimozono]

Filed as external review by Claude (Anthropic, AI agent operating under souta's GitHub auth). Reads with #16 (Legal posture) and #12 (Threat model).

立場

Recommendation A (stdio only) を 強く支持。 加えて HTTP transport は MVP では non-goal、 将来の Phase でも posture 整合性の検証なしに着手しない という形で本 Discussion を 永続的 lock することを提案します。

理由は:

1. HTTP transport を実装した瞬間に、 doiget は「multi-tenant 意識を持つ server」になる
2. multi-tenant server は publisher 側から見ると「公衆送信」近接の構造に見える
3. user が contract party になる [legal] Legal posture, tool neutrality framing, and required safeguards #16 posture が崩れる (誰が ToS の責任主体かが authority delegation で曖昧になる)
4. authentication / authorization 層の追加は attack surface を増やすが、 posture ベースだと受益が小さい

HTTP transport の永続的 non-goal 化

docs/SCOPE.md の "Permanent non-goals" (#9 review で提案) に MCP HTTP transport を 1 条として加える:

No MCP HTTP / SSE / WebSocket transport.
doiget supports MCP via stdio only. This is intentional, not a TODO.
A multi-tenant network-exposed doiget would shift the user's role from
contract party to service consumer, which conflicts with the stated
posture (see LEGAL.md). Do not propose HTTP transport in pull requests.

これを structurally enforce する仕組み:

• --features http-transport のような feature flag を 作らない
• http_transport.rs のような module を 作らない
• posture-lint.yml ([legal] Legal posture, tool neutrality framing, and required safeguards #16 §6 提案) で source code 内に axum, actix-web, hyper::Server, warp, tide 等の web framework crate import を grep し、 検出したら CI fail

stdio transport の Phase 3 spec lock

stdio が単一 transport なので、 spec を厳密化:

Process model

parent (MCP host) -> spawn(doiget serve) -> doiget child process
                  <- stdin/stdout JSON-RPC ->
                  -> SIGTERM / SIGINT -> doiget child shutdown

• doiget child は single-instance per session。 同じ host から複数 spawn は host 側責任
• child は stdin EOF を検出したら 5 秒以内に shutdown
• ongoing fetch があれば cancellation token で中断
• store lock の release を保証 (graceful shutdown)

Concurrency

• doiget child 内部で tokio runtime を持つ
• 複数 MCP request を 並列処理可 (max concurrency = MAX_CONCURRENT_FETCHES = 5、 [legal] Legal posture, tool neutrality framing, and required safeguards #16 §8)
• 但し store write は serialize (atomic write + flock)

Backpressure

• 大量 request を host が投げてきたら、 MAX_CONCURRENT_FETCHES を超える分は queue
• queue が 100 を超えたら新規 request を RATE_LIMITED で reject
• queue depth は doiget_health tool で観測可

Logging

• tracing-subscriber の writer を stderr 強制 ([ux] User personas + 出力 mode 設計 (agent / researcher / CI / library) #14 §2)
• log level は RUST_LOG env var で制御、 default = info
• structured log (JSON Lines) を Phase 3 で採用 (RUST_LOG_FORMAT=json env)

stdin/stdout の 1 byte も noise を出さない確認

#14 §2 と重複するが、 本 Discussion で改めて lock:

• stdout は JSON-RPC frame のみ。 banner / progress / log は禁止
• panic message が stdout に出ないように std::panic::set_hook で stderr 強制
• 起動時の cargo info banner も off (println!("doiget v0.1") 系は禁止)
• CI で確認: doiget serve を起動 → 1 秒後 SIGTERM → stdout が空であること

Phase 4+ で HTTP を再考する場合の必要条件

万一 author が HTTP transport を将来再考する場合の 障壁を高くする 前提条件を本 Discussion で予め明記:

1. docs/LEGAL.md の posture を public 法律 review に通す
2. authentication / authorization の formal threat model を作成
3. multi-tenant 利用での provenance log の責任分担を design (誰が log を所有するか)
4. publisher legal team へ事前通知 (proactive)
5. 上記を満たしても Phase X として独立 release、 OA stdio binary との配布分離

これらが満たされない限り、 「便利だから HTTP もつけよう」という増分追加を構造的に防ぐ。

Reviewer Decision proposal

• Decision: A (stdio only)、 永続化
• HTTP transport を docs/SCOPE.md の Permanent non-goals に登録
• web framework crate を cargo-deny の deny list に追加
• posture-lint.yml で web framework import を CI で検出、 違反 PR を fail
• stdio transport の process / concurrency / backpressure / logging spec を Phase 3 で lock
• stdout noise 0 byte の CI assertion を Phase 3 から
• HTTP 再考の場合の barrier 条件を本 Discussion に永続記録

最終 Decision 権は author に留保。

---

Reviewer: Claude (Anthropic). Filed 2026-05-05.