Byteask Embedded Docs

ByteAsk Embedded MCP

組み込み機器およびファームウェアのリファレンス文書から、ページ引用付きの回答を提供します。レジスタ値を推測できないコーディングエージェント向けです。

公式 MCP Registry 名前空間：ai.byteask/embedded-docs · リモート MCP エンドポイント：https://mcp.byteask.ai/mcp

クイックスタート · ツール · クライアントの接続 · 設定 · ホスト型サーバー · コントリビューション

ByteAsk Embedded MCP は、ByteAsk Embedded Docs を支えるオープンソースサーバーです。 ファームウェア、ドライバー、プロトコルのコードを作成するコーディングエージェント（Claude Code、Codex、Cursor）向けに、ソースに基づくページ引用付きの根拠検索を提供します。SunSpec ポイント、レジスターオフセット、Modbus ファンクションコード、トリップしきい値、SCPI コマンド、API シンボルなどの正確な情報が必要な場合に役立ちます。

ページ引用付きの原文スニペットをそのまま返します。回答を生成することはありません。また、十分に関連する情報が見つからない場合は、捏造するのではなく一致なしと伝えます。すべての文書は同等に扱われ、優先度の設定やフィルターはありません。

メモ

このリポジトリに含まれるもの： MCP サーバー（ツール、トランスポート（stdio + Streamable HTTP）、ベアラー認証、DNS リバインディング対策、結果のレンダリング）と、小規模で差し替え可能な検索インターフェースです。

このリポジトリに含まれないもの： 検索エンジンと文書コーパスです。文書の解析、チャンク分割、埋め込み、ランキングを行う仕組みと、ライセンス対象のソース資料は、SearchBackend のインターフェースの先にあり、ホスト型エンドポイント https://mcp.byteask.ai/mcp を支えています。このリポジトリには、サーバーをすぐに実行できるよう、例示用の公開情報レコードをいくつか含むメモリー内の SampleBackend が同梱されています。

理由

• 引用がなければ、何も返しません。 ヒットした場合は、セクションとページの引用を含む原文をそのまま返します。見つからない場合は、正直に「確実に一致するものはありません」と返し、レジスタ値を決して捏造しません。
• コーディングエージェント向けに設計されています。 ツールの説明とトリガーは、エージェントが16進リテラル、Modbus コード、IEEE 条項、SCPI 動詞、MCU 型番を見つけたら、記憶に基づいて回答する前に、反射的に search_docs を呼び出すよう調整されています。
• 2つのトランスポート、1つのサーバー。 ローカルエージェントには stdio、ホスト型には Streamable HTTP を使用します。
• 検索機能を自由に差し替えられます。 検索エンジンは2つのメソッドからなるインターフェースです。サーバーを変更せずに、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_

独自の検索機能を接続する

サーバーが依存するのは、2 つのメソッドを持つインターフェース （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 の ベアラー認証チェックはスタブです。トークンが設定されていない場合は認証なし、設定されていても共有シークレットによる認証がせいぜいです。広く公開する前に強化してください。
• HTTP トランスポートでは DNS リバインディング対策 がデフォルトで有効です。

貢献

PR と Issue を歓迎します。

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

サーバーをクリーンに保つための規約をいくつか示します。

• バックエンドとの境界が拡張ポイントです。 検索の内部処理（解析、チャンク分割、埋め込み、ランキング）は意図的に対象外としています。これらはこのリポジトリではなく、ご自身のパッケージで SearchBackend の背後に実装してください。
• 依存関係を最小限に抑え、stdio の経路に HTTP スタックを含めないでください。
• 新しい動作にはテストを追加してください。テストスイートは完全にオフラインで動作します（ネットワークもキーも不要です）。

ライセンス

MIT © ByteAsk