Byteask Embedded Docs

ByteAsk Embedded MCP

来自嵌入式与固件参考文档的带页码引用答案——专为那些无法承受猜错寄存器值的编码 Agent 打造。

官方 MCP Registry 命名空间：ai.byteask/embedded-docs · 远程 MCP 端点：https://mcp.byteask.ai/mcp

快速开始 · 工具 · 连接客户端 · 配置 · 托管服务 · 参与贡献

ByteAsk Embedded MCP 是 ByteAsk Embedded Docs 背后的开源服务： 一个面向编码 Agent 的基于来源、带页码引用的证据检索 MCP 服务 （Claude Code、Codex、Cursor），这些 Agent 编写固件 / 驱动 / 协议代码，需要 精确 的事实——SunSpec 数据点、寄存器偏移、Modbus 功能码、跳闸阈值、 SCPI 命令、API 符号。

它返回逐字原文片段并附页码引用——绝不自撰答案——当没有足够相关的内容时， 它会明确返回无匹配，而不是捏造。所有文档一视同仁：没有权威层级，没有过滤器。

说明

本仓库包含什么： MCP 服务——工具、传输方式（stdio + Streamable HTTP）、bearer 认证、DNS 重绑定防护、结果渲染——以及一个小的、 可插拔的检索接口。

本仓库不包含什么： 检索引擎和文档语料库。文档如何被解析、分块、 嵌入和排序，以及获得授权的源材料本身，都位于 SearchBackend 接缝之后，并为托管端点 https://mcp.byteask.ai/mcp 提供支持。本仓库附带一个内存版 SampleBackend（若干 示例性的公开知识记录），使服务开箱即用。

为什么

• 有引用，否则不给。 每个结果都是逐字源文本，并附有章节 + 页码 引用。检索失败时，它会诚实地返回“无可靠匹配”——绝不编造 寄存器值。
• 为编码 Agent 而生。 工具描述和触发条件经过调优，使 Agent 在看到 十六进制字面量、Modbus 代码、IEEE 条款、SCPI 动词或 MCU 型号时 会条件反射式地调用 search_docs——而不是凭记忆作答。
• 两种传输方式，一个服务。 stdio 用于本地 Agent，Streamable HTTP 用于托管。
• 自带检索。 搜索引擎是一个包含两个方法的接口——可以在 BYTEASK_BACKEND 之后替换为任何实现，而无需改动服务。
• 零配置演示。 内置的 SampleBackend 可立即运行。无需 API 密钥。

快速开始

需要 Python ≥ 3.10 和 uv。

uv sync
uv run byteask-embedded-mcp        # run as an MCP server (stdio)

就这样——内置的 SampleBackend 提供若干示例记录，因此 search_docs 立即可用。使用 uv run pytest 运行离线测试。

连接客户端

托管服务（无需安装）

托管服务在 https://mcp.byteask.ai/mcp 上使用 Streamable HTTP 协议，并以完整的授权语料库为后端。

Claude Code：

claude mcp add --transport http byteask-embedded-docs https://mcp.byteask.ai/mcp

{
  "mcpServers": {
    "byteask-embedded-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.byteask.ai/mcp"]
    }
  }
}

本地（本仓库）

项目级 .mcp.json 为读取它的客户端注册了 stdio 服务。对于 Claude Code，可手动执行：

claude mcp add byteask-embedded-docs -- uv run byteask-embedded-mcp

工具

输入为自然语言（或精确标识符）。输出为紧凑的 markdown。

示例输出：

## Results for "what Modbus function code writes multiple registers"

### Sample — Modbus Application Protocol (illustrative) — §6.12, p.30
> Function code 16 (0x10), Write Multiple Registers, writes a block of contiguous
> holding registers (1 to 123 registers) in a remote device. ...
_ref: sample:modbus-fc16_

接入你自己的检索

该服务仅依赖一个包含两个方法的接口（backend.py）：

class SearchBackend(Protocol):
    def search(self, query, limit=8, effort=None) -> dict: ...
    def get_context(self, result_id, effort=None) -> dict: ...

实现它，暴露工厂函数 make_backend(config) -> SearchBackend，并让服务指向它：

BYTEASK_BACKEND="my_pkg.my_module:make_backend"

确切的返回值约定记录在 backend.py 的顶部。

配置

所有设置均为环境变量（从 .env 加载；参见 .env.example）。

MCP_TRANSPORT=http MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32) \
  uv run byteask-embedded-mcp --host 0.0.0.0 --port 8000

托管服务

使用 ByteAsk Embedded Docs 无需运行任何东西。托管服务为 Claude Code、Codex、Cursor 以及任何 MCP 客户端提供来自嵌入式与固件参考文档的精确、标注页码的事实——寄存器映射、协议功能码、SCPI 命令、标准阈值、数据手册规格。其保证是：原文引用，或"无匹配"——绝不编造数值。

本仓库是为该端点提供支持的开源服务。

项目结构

src/byteask_embedded_mcp/
  server.py     # FastMCP app + 3 tools (search_docs, get_context, request_document)
  backend.py    # SearchBackend protocol + in-memory SampleBackend (swap for real retrieval)
  render.py     # structured result -> compact markdown
  http_auth.py  # Streamable HTTP entrypoint + stub bearer-token guard
  config.py     # server config (transport, logging, backend selection)
  schemas.py    # Hit / Section result types
  obs.py        # per-call JSONL logging
tests/          # offline unit tests (renderer, backend, server tools)
assets/         # README demo GIF + its deterministic generator

安全

• 在 stdio 模式下，stdout 保持干净（它是 JSON-RPC 通道）；所有日志写入 stderr / logs/*.jsonl。
• HTTP 的 bearer 校验是一个存根——未设置 token 时无认证，最多只是一个共享密钥。在广泛暴露之前请加强它。
• DNS 重绑定保护在 HTTP 传输下默认开启。

贡献

欢迎提交 PR 和 issue。

uv sync            # install (incl. dev tools)
uv run pytest      # run the offline test suite

以下是一些保持服务整洁的约定：

• 后端接缝就是扩展点。 检索内部实现（解析、分块、嵌入、排序）有意不在此范围内 —— 请在自己的包中基于 SearchBackend 构建它们，而不是放在本仓库中。
• 保持依赖面尽可能小，并让 stdio 路径不依赖 HTTP 技术栈。
• 为新行为添加测试；测试套件完全离线（无网络、无密钥）。

许可证

MIT © ByteAsk