[design] MCP server が公開する tool の名前と signature

[sotashimozono]

Question

doiget serve で公開する MCP tool の名前 / 引数 / 返り値を確定する。

Phase 3 (MVP) 提案

resolve_paper(ref: String) -> Metadata
fetch_paper(ref: String, source_policy?: "strict"|"lenient") -> FetchResult
batch_fetch(refs: Vec<String>) -> Vec<FetchResult>
info(ref: String) -> Option<EntryInfo>
search_local(query: String, limit?: usize) -> Vec<Match>
list_recent(limit?: usize) -> Vec<EntryInfo>

Phase 4 で追加予定

bibtex_export(filter?: Query) -> String
csl_export(filter?: Query) -> String
expand_citation_graph(ref: String, depth: usize, max_refs?: usize) -> Graph

Open questions

• 命名規則: snake_case (default) / camelCase / prefix (doiget_*)?
• error: MCP error として throw / ok: false で return — どちらが UX 良い？
• structured vs string: bibtex_export は string 直接 / {format, content} か？
• cache hint: resolve_paper は cache 可能 — MCP に hint 出すべき？

Decision

???

[sotashimozono]

Filed as external review by Claude (Anthropic, AI agent operating under souta's GitHub auth). Closely coupled with #4 (transport) / #12 (threat model) / #14 (personas).

立場

提案 6 tools (resolve / fetch / batch / info / search_local / list_recent) は agent UX として妥当な最小集合 ですが、 #16 / #12 を経た tightening を受けて、 spec を以下のように修正・強化する提案をします。

1. 命名規則: snake_case + doiget_ prefix

本文 open question への reviewer 回答:

• snake_case を採用 (Python / MCP server eco の慣習)
• doiget_ prefix を付ける: 理由は MCP host が複数 server を持つ前提で、 collision 防止と "どの server が出した tool か" の origin tracking が容易

doiget_resolve_paper(...)
doiget_fetch_paper(...)
doiget_batch_fetch(...)
doiget_info(...)
doiget_search_local(...)
doiget_list_recent(...)
doiget_paper_pdf_path(...)        # #9 で追加提案

PR がマージされた MCP eco の慣習 (tavily_search, slack_post_message など) と整合。

2. Error 設計: structured ok: false を採用、 throw しない

本文 open question への reviewer 回答:

• MCP error として throw せず、 ok: false で return を recommend
• 理由:
  • MCP throw は agent の retry loop で意味が曖昧になる (tool error vs transport error の区別困難)
  • structured return は agent が分岐しやすい
  • LLM が ok: false の error.code を見て次手を決められる

type FetchResult =
  | { ok: true,  ref: string, source: "crossref"|"unpaywall"|"arxiv",
      path: string, license: string, size_bytes: number }
  | { ok: false, ref: string, error: { code: ErrorCode, message: string } };

type ErrorCode =
  | "INVALID_REF"
  | "NO_OA_AVAILABLE"
  | "RATE_LIMITED"
  | "NETWORK_ERROR"
  | "STORE_ERROR"
  | "CAPABILITY_DENIED"   // CapabilityProfile (#16) で禁止された source
  | "FETCH_TIMEOUT"
  | "INTERNAL_ERROR";

ErrorCode は enum closed set で、 prose error message とは別 layer。 これを docs/MCP_TOOLS.md の reference として固定。

3. Structured vs string: format-aware return

本文 open question への reviewer 回答:

• bibtex_export 等は structured return ({format: "bibtex", content: "..."}) ではなく shape-stable な structured object にする
• 理由: agent が "format" を見て分岐しないなら structured 不要。 単に string で十分
• 但し multiple formats を返したい場合 (例: bib + csl 両方) は object で。 single format なら string

// Single format
type BibTeXExport = string;          // BibTeX content directly

// Multi-format (Phase 4+)
type ExportBundle = { bibtex?: string, csl_json?: object };

4. Cache hint: MCP の cacheControl ではなく内部 cache を使う

本文 open question への reviewer 回答:

• MCP には universal cache hint が無い (各 host 実装依存)
• doiget 側で local resolver cache を持つ のが portable
  • ~/.cache/doiget/resolver/<safekey>.toml に Crossref response を 7 日 cache
  • resolve_paper は cache hit なら network 呼ばず返す
  • cache invalidation は version field + ttl で管理
• これで MCP host に依存せず latency を削れる

cache 設計を docs/CACHE.md に独立 spec で書く。

5. 入力 validation を tool spec の一部として lock

#12 (threat model) で agent-side untrusted input が threat として上がっている。 各 tool の入力 validation を JSON Schema として spec 化 し、 MCP tool の inputSchema に焼き込む:

{
  "doiget_fetch_paper": {
    "ref": {
      "type": "string",
      "minLength": 7,
      "maxLength": 256,
      "pattern": "^(10\\.\\d{4,9}/[A-Za-z0-9._/()-]+|arXiv:\\d{4}\\.\\d{4,5}|\\d{4}\\.\\d{4,5})$"
    }
  },
  "doiget_batch_fetch": {
    "refs": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": { ... }
    }
  }
}

これで MCP host 側で agent input がそもそも doiget に届く前に reject される (defense in depth)。

6. 提案する追加 tool

doiget_paper_pdf_path (#9 で提案、 ここで spec)

input:  { ref: string }
output: { ok: true, path: string } | { ok: false, error: ... }
description: "Returns the local filesystem path to the cached PDF.
              Does NOT read, parse, or transmit content."

doiget_capability_profile (新提案、 #16 と整合)

input:  {}
output: {
  oa_enabled: true,                    // 常に true
  metadata_sources: ["openalex", ...], // Phase 4 以降で増える
  tdm_enabled: false,                  // 個別 source ごとに boolean
  tdm_elsevier: false,
  tdm_aps: false,
  tdm_springer: false,
  rate_limit_per_sec: 5
}
description: "Reports which sources this doiget instance is allowed to use.
              Useful for agents to plan whether a fetch is feasible
              before issuing it."

これで agent が「この binary は TDM 可能か?」を事前に問い合わせできる。 CAPABILITY_DENIED error を防ぐ前段となる。

doiget_health (新提案、 operational sanity)

input:  {}
output: { store_writable: true, version: "0.1.0", schema_version: "1.0", ... }
description: "Reports doiget's operational health (writable store,
              schema version, etc.)."

MCP host が serve を起動した直後に sanity check 用。

7. 提案する non-tool

以下は MCP tool として exposing しない ことを Phase 3 spec に lock:

• doiget_delete_paper(...) — 削除は CLI 経由のみ。 agent が誤って消す事故を構造的に防ぐ
• doiget_set_credentials(...) — credential 操作は env / file 経由のみ。 MCP server が credential を受け取る surface を作らない ([legal] Legal posture, tool neutrality framing, and required safeguards #16 §1 とも整合)
• doiget_run_shell(...) のような generic escape — 当然作らない
• doiget_fetch_url(url: ...) — [security] threat model + security 対策 #12 で SSRF surface として却下済み

8. tool 説明文 (description) は LLM 向けに最適化

agent 経由で tool が選ばれる時、 LLM は tool description だけを読む。 description は以下の format に統一:

WHEN TO USE: "User wants to download a paper PDF given a DOI or arXiv id."
INPUTS: {ref}: "DOI like '10.1234/abc' or arXiv id like '2401.12345'"
OUTPUTS: "Path to local PDF if successful, or error code."
COSTS: "Network call (~1-3s). May fail if not Open Access."
SIDE EFFECTS: "Writes PDF to ~/papers/. Logs to ~/.config/doiget/access.log."
LIMITS: "Max 5 fetches per second. Use doiget_batch_fetch for >5 refs."

LLM が tool 選択 / parameter 推測を間違えにくくなる。

Reviewer Decision proposal

• 6 tools (本文) + 3 (paper_pdf_path / capability_profile / health) = 9 tools を Phase 3 で公開
• 命名: snake_case + doiget_ prefix
• Error: ok: false structured return、 closed set ErrorCode enum
• String / structured: single-format は string、 multi-format は object
• Cache: MCP cacheControl ではなく doiget 内部 cache (~/.cache/doiget/resolver/)
• 入力 validation: JSON Schema を MCP inputSchema に焼き込む
• non-tool list: delete / credentials / shell / URL fetch を Phase 3 で除外として明記
• description: WHEN/INPUT/OUTPUT/COSTS/SIDE EFFECTS/LIMITS の 6 項目フォーマット統一

最終 Decision 権は author に留保。

---

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