ByteAsk-Embedded-MCP 是 ByteAsk Embedded Docs 背后的开源模型上下文协议（MCP）服务器，面向编写固件、驱动程序和协议代码的编码代理（Claude Code、Codex、Cursor），提供基于来源、带页码引用的证据检索能力。其核心定位是让代理在需要精确事实（如 SunSpec 数据点、寄存器偏移、Modbus 功能码、跳闸阈值、SCPI 命令、API 符号）时检索参考文档，而非依赖记忆猜测。
用途 该服务器用于嵌入式与固件参考文档的证据检索。它返回逐字源代码片段并附带章节和页码引用，从不生成编写式答案；当没有足够相关的内容时，会诚实返回“无匹配”，绝不编造寄存器值。所有文档被平等对待：没有权威层级，没有过滤器。
主要能力
- 引用或空手而归：每次命中都是逐字源文本，附带章节 + 页码引用；未命中时返回“无自信匹配”。
- 为编码代理构建：工具描述和触发条件经过调优，使代理在看到十六进制字面量、Modbus 代码、IEEE 条款、SCPI 动词或 MCU 部件号时，会条件反射式调用 search_docs，而非凭记忆回答。
- 双传输，单服务器：本地代理使用 stdio，托管使用 Streamable HTTP。
- 自带检索：搜索引擎是一个两方法接口，可在 BYTEASK_BACKEND 后替换任何实现，无需改动服务器。
- 零配置演示：捆绑的 SampleBackend 立即运行，无需 API 密钥。
使用方式 本地运行要求 Python ≥ 3.10 和 uv。捆绑的 SampleBackend 提供少量示例记录，因此 search_docs 可立即工作；离线测试用 uv run pytest 运行。连接客户端有两种方式：
- 托管（免安装）：托管服务器在 https://mcp.byteask.ai/mcp 使用 Streamable HTTP，由完整授权语料库支撑。
- 本地（本仓库）：项目级 .mcp.json 为读取它的客户端注册 stdio 服务器；也可手动为 Claude Code 配置。 输入为自然语言（或精确标识符），输出为紧凑的 markdown。
自带检索接入 服务器仅依赖一个两方法接口（backend.py）。实现该接口，暴露工厂 make_backend(config) -> SearchBackend，并将服务器指向它即可。确切的返回值契约记录在 backend.py 顶部。所有设置均为环境变量（从 .env 加载；参见 .env.example）。客户端随后发送 Authorization: Bearer <token>。捆绑的 bearer 检查是共享密钥存根，公开暴露前应替换为真实认证（OAuth 2.1 资源服务器、mTLS 或可信反向代理）。DNS 重绑定防护通过 MCP_ALLOWED_HOSTS 独立保持开启。
适用场景 适用于编写固件、驱动或协议代码、需要精确事实的编码代理工作流，尤其是需要从嵌入式与固件参考文档中获取寄存器映射、协议功能码、SCPI 命令、标准阈值和数据手册规格的场景。您无需运行任何东西即可使用 ByteAsk Embedded Docs；托管服务器为 Claude Code、Codex、Cursor 及任何 MCP 客户端提供精确、带页码引用的事实，保证逐字源文本或“无匹配”，绝不虚构值。
限制
- 本仓库仅包含 MCP 服务器（工具、传输、bearer 认证、DNS 重绑定防护、结果渲染）以及小型可插拔检索接口；检索引擎和文档语料库不在本仓库中，位于 SearchBackend 接缝之后并驱动托管端点。仓库内置的 SampleBackend 仅含少量示例性公共知识记录，以便开箱即用。
- stdio 模式下 stdout 保持干净（它是 JSON-RPC 通道）；所有日志写入 stderr / logs/*.jsonl。
- HTTP bearer 检查是存根——若未设置令牌则未认证，至多是共享密钥；广泛暴露前需加固。
- HTTP 传输默认开启 DNS 重绑定防护。
- 后端接缝是扩展点：检索内部实现（解析、分块、嵌入、排序）有意不在本仓库范围内，应在自己的包中于 SearchBackend 之后构建。
- 需保持依赖面小，stdio 路径不含 HTTP 栈；新增行为需添加测试，测试套件完全离线（无网络、无密钥）。
- 官方 MCP 注册表命名空间：ai.byteask/embedded-docs；远程 MCP 端点：https://mcp.byteask.ai/mcp。
收费、价格等具体商业信息暂未提供。
