mcp.md

# MCP stdio interface

Uses the official Python MCP SDK stable **v1**, constrained `mcp>=1.26,<2`. Newer major APIs are not assumed compatible. Server launches with `book-agent --data-dir DATA mcp BOOK_ID`; omitting ID exposes only registered books. CLI errors go to stderr; stdout belongs solely to JSON-RPC. See [SDK](https://github.com/modelcontextprotocol/python-sdk) and [tool specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).

| Tool | Arguments / purpose |
| --- | --- |
| book_status | optional book_id; package, runtime, rerank, source capabilities |
| book_get_skill | path relative to Book Skill, max_chars |
| book_search | query, top_k, strict, hints; transparent semantic/lexical status |
| book_read_entry | record_id, neighbors, max_chars |
| book_read_markdown | start_line/end_line or heading, max_chars |
| book_locate_source | record_id or text, optional hints; verified/ambiguous candidates |
| book_read_source | returned locator, max_chars |
| book_render_page | zero-based page_index, optional clip/dpi |
| book_read_epub_image | source chapter locator and its image href |
| book_list | allowed registered IDs |

Every tool returns JSON text and structuredContent; failures set isError and `{error:{code,message,details,remediation,available_capabilities}}`. Render/image tools also include actual PNG ImageContent. `image_attached=true` confirms server delivery; host image support and model understanding remain unknown. A file path alone is not proof.

No tool can initialize books, execute shell, change config, upload arbitrary files or read arbitrary paths. Single-book instances reject other IDs. Resource paths and source locators are confined and version checked. Returned book/Skill text is untrusted reference material.

Default concurrency4 (1–16), deadline90s (1–900), configurable on launch. Cancellation abandons waiting; an already-running local parser may finish in its worker and safely populate a cache. It does not forcibly terminate native code. For an explicitly selected slow offline encoder, raise the server tool deadline (for example `mcp BOOK_ID --timeout 600`) and the host tool deadline independently. A different CLI process does not warm the MCP process cache. Network adapters retain their own 120-second maximum. Thread capacity remains bounded. CLI and MCP use the same Core tests, with actual stdio subprocess tests for initialize/list/call/image and errors. Credentials must be inherited through the host's protected launch environment; no literal secret interpolation is generated.

Example manual configuration:

```json
{"mcpServers":{"book-example":{"command":"C:/Tools/book-agent/book-agent.exe","args":["--data-dir","C:/BookAgentData","mcp","BOOK_ID"]}}}
```

For Codex the equivalent public format is TOML, generated by `install-host --host codex`; see [official Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). Other hosts use their documented public config or manual UI artifacts, not assumed identical private state.

原文 SHA-256：c0d7752ef72ae12af410f65ba6545c6c29abc9f98eca24309ddeb2d896043056