内容
<div align="center">
# ByteAsk嵌入式MCP
**从嵌入式和固件参考文档中获取引用的答案 — 面向无法承担寄存器值猜测的编码代理。**
[](https://smithery.ai/servers/kulkarnianirudha8/byteaskai)
[](LICENSE)
[](pyproject.toml)
[](https://modelcontextprotocol.io)
[](#)
[](#contributing)
[](https://docs.byteask.ai/embedded)
官方MCP注册命名空间：`ai.byteask/embedded-docs` · 远程MCP端点：`https://mcp.byteask.ai/mcp`
[快速开始](#快速开始) · [工具](#工具) · [连接客户端](#连接客户端) · [配置](#配置) · [托管服务器](#托管服务器) · [贡献](#贡献)
<img src="assets/demo.gif" alt="A coding agent reaches for ETH_DMATDLAR from memory; byteask reads the corpus and the line snaps to the cited ETH_DMACTXDLAR with a page citation." width="820">
</div>
---
ByteAsk嵌入式MCP是[ByteAsk嵌入式文档](https://docs.byteask.ai/embedded)的开源服务器：
一个**基于源代码、按页引用证据检索**的MCP服务器，适用于编写固件/驱动器/协议代码的编码代理（Claude Code、Codex、Cursor），他们需要**精确**的事实 — SunSpec点、寄存器偏移量、Modbus功能代码、行程阈值、SCPI命令、API符号。
它返回**逐字逐句的引用片段和页码引用** — 而不是作者的答案 — 当没有任何足够相关的结果时，它会说**没有匹配**而不是编造。每个文档都平等对待：没有权威层，没有过滤器。
> [!NOTE]
> **此仓库中包含的内容：** MCP *服务器* — 工具、传输（stdio + Streamable HTTP）、承载身份验证、DNS重新绑定保护、结果渲染 — 以及一个小型、可扩展的检索接口。
>
> **此仓库中不包含的内容：** 检索引擎和文档语料库。文档如何解析、切分、嵌入和排名，以及许可的源材料本身，都位于 [`SearchBackend`](src/byteask_embedded_mcp/backend.py) 接口后面，并为托管的端点 `https://mcp.byteask.ai/mcp` 提供支持。该仓库附带了一个内存中的 [`SampleBackend`](src/byteask_embedded_mcp/backend.py) （一些说明性的公共知识记录），以便服务器可以直接运行。
## 为什么
- **引用或无。** 每个结果都是原始来源的逐字引用文本，带有章节和页码引用。如果找不到匹配的结果，则会返回诚实的“无匹配结果” — 不会编造寄存器值。
- **为编码代理而构建。** 工具描述和触发器是调优的，以便代理在看到十六进制文字、Modbus代码、IEEE条款、SCPI动词或MCU零件编号时自动调用 `search_docs` — 在从内存中回答之前。
- **两个传输，一个服务器。** `stdio` 用于本地代理，Streamable HTTP用于托管。
- **自带检索。** 搜索引擎是一个两方法接口 — 在 `BYTEASK_BACKEND` 后面交换任何内容。
- **零设置演示。** 捆绑的 `SampleBackend` 立即运行。无需API密钥。
## 快速开始
需要Python ≥ 3.10 和 [`uv`](https://docs.astral.sh/uv/)。
```bash
uv sync
uv run byteask-embedded-mcp # 作为MCP服务器运行（stdio）
```
就是这样 — 捆绑的 `SampleBackend` 提供几个说明性的记录，因此 `search_docs` 立即生效。 使用 `uv run pytest` 运行离线测试。
## 连接客户端
### 托管（无需安装）
托管服务器通过 **Streamable HTTP** 在 `https://mcp.byteask.ai/mcp` 进行通信，并由完整的许可语料库支持。
[](https://cursor.com/install-mcp?name=byteask-embedded-docs&config=eyJ1cmwiOiJodHRwczovL21jcC5ieXRlYXNrLmFpL21jcCJ9)
**克劳德代码：**
```bash
claude mcp add --transport http byteask-embedded-docs https://mcp.byteask.ai/mcp
```
<details>
<summary><strong>Codex、Cursor和其他客户端（mcp-remote）</strong></summary>
```json
{
"mcpServers": {
"byteask-embedded-docs": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.byteask.ai/mcp"]
}
}
}
```
</details>
### 本地（此仓库）
项目范围内的[`.mcp.json`](.mcp.json)为读取它的客户端注册stdio服务器。手动为克劳德代码：
```bash
claude mcp add byteask-embedded-docs -- uv run byteask-embedded-mcp
```
## 工具
输入是自然语言（或确切的标识符）。输出是紧凑的Markdown。
| 工具 | 功能 |
|------|--------------|
| **`search_docs(query, limit=8)`** | 搜索语料库；返回排名靠前的、按页引用的证据。每个结果都有文档标题、章节和页码引用、逐字引用片段和 `result_id`。 “没有匹配结果”的响应意味着 *未找到 — 不应编造*。 |
| **`get_context(result_id)`** | 展开一个结果到其完整的源章节。 |
| **`request_document(request)`** | 请求添加缺少的文档（服务器端记录）。 |
示例输出：
```markdown
## “写多个寄存器的Modbus功能代码”的结果
### 示例 — Modbus应用协议（说明性）— §6.12, p.30
> 功能代码16（0x10），写多个寄存器，写入远程设备中的连续寄存器块（1到123个寄存器）...
_ref: sample:modbus-fc16_
```
## 插入您自己的检索
服务器仅依赖于一个两方法接口（ [`backend.py`](src/byteask_embedded_mcp/backend.py) ）：
```python
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`，并指向它：
```bash
BYTEASK_BACKEND="my_pkg.my_module:make_backend"
```
确切的返回值合约在 `backend.py` 顶部记录。
## 配置
所有设置都是环境变量（从 `.env` 加载；参见 [`.env.example`](.env.example) ）。
| 变量 | 默认值 | 备注 |
|----------|---------|-------|
| `BYTEASK_BACKEND` | — | `module:callable` 返回一个 `SearchBackend`；为空 → `SampleBackend` |
| `BYTEASK_LOGS` | `logs` | 查询/请求JSONL日志写入的位置 |
| `MCP_TRANSPORT` | `stdio` | `stdio` （本地代理）或 `http` |
| `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `127.0.0.1` / `8000` | HTTP绑定地址 |
| `MCP_HTTP_AUTH_TOKEN` | — | HTTP的承载令牌（为空=未经身份验证，仅限开发） |
| `MCP_ALLOWED_HOSTS` | — | `Host`头部中允许的逗号分隔主机（`*`禁用） |
| `LOG_LEVEL` | `INFO` | stderr日志详细程度 |
<details>
<summary><strong>通过HTTP运行</strong></summary>
```bash
MCP_TRANSPORT=http MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32) \
uv run byteask-embedded-mcp --host 0.0.0.0 --port 8000
```
客户端然后发送 `Authorization: Bearer <token>`。捆绑的承载检查是一个共享密钥 **存根** — 在公开暴露之前用真正的身份验证（OAuth 2.1资源服务器，mTLS或受信任的反向代理）替换它。 DNS重新绑定保护通过 `MCP_ALLOWED_HOSTS` 独立启用。
</details>
## 托管服务器
您不需要运行任何东西即可使用ByteAsk嵌入式文档。托管服务器为克劳德代码、Codex、Cursor和任何MCP客户端提供嵌入式和固件参考文档的精确、按页引用的事实 — 寄存器映射、协议功能代码、SCPI命令、标准阈值、数据表规格。保证：**原始来源，或“无匹配结果” — 永不发明的值。**
| | |
|---|---|
| **名称** | `byteask-embedded-docs` |
| **端点** | `https://mcp.byteask.ai/mcp` （Streamable HTTP） |
| **文档和客户端设置** | <https://docs.byteask.ai/embedded> |
此仓库是支持该端点的开源服务器。
## 项目布局
```
src/byteask_embedded_mcp/
server.py # FastMCP应用 + 3个工具（search_docs, get_context, request_document）
backend.py # SearchBackend协议 + 内存中的SampleBackend（可交换为实际检索）
render.py # 结构化结果 -> 紧凑的Markdown
http_auth.py # Streamable HTTP入口 + 承载令牌保护存根
config.py # 服务器配置（传输、日志记录、后端选择）
schemas.py # 结果类型（Hit / Section）
obs.py # 每调用JSONL日志记录
tests/ # 离线单元测试（渲染器、后端、服务器工具）
assets/ # README演示GIF及其确定性生成器
```
## 安全
- **stdout在stdio模式下保持干净** （它是JSON-RPC通道）；所有日志都输出到stderr / `logs/*.jsonl`。
- **HTTP承载检查是一个存根** — 如果未设置令牌，则未经身份验证，最多是一个共享密钥。在广泛公开之前，请加强它。
- **DNS重新绑定保护** 默认启用HTTP传输。
## 贡献
欢迎PR和问题。
```bash
uv sync # 安装（包括开发工具）
uv run pytest # 运行离线测试套件
```
一些约定以保持服务器清洁：
- **后端缝隙是扩展点。** 检索内部（解析、切分、嵌入、排名）故意在此范围内 — 在您自己的包中构建它们，而不是在这个仓库中。
- **保持依赖表面小** 并保持stdio路径不依赖HTTP堆栈。
- **为新行为添加测试** ；套件是完全离线的（无网络，无密钥）。
## 许可证
[MIT](LICENSE) © ByteAsk
