{ "markdown": "
\n\n# ByteAsk Embedded MCP\n\n**Page-cited answers from embedded & firmware reference docs — for coding agents that can't afford to guess a register value.**\n\n[![smithery badge](https://smithery.ai/badge/kulkarnianirudha8/byteaskai)](https://smithery.ai/servers/kulkarnianirudha8/byteaskai)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?logo=python&logoColor=white)](pyproject.toml)\n[![Model Context Protocol](https://img.shields.io/badge/Model_Context_Protocol-compatible-5FB3A3.svg)](https://modelcontextprotocol.io)\n[![Status: beta](https://img.shields.io/badge/status-beta-orange.svg)](#)\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)\n[![Hosted](https://img.shields.io/badge/hosted-mcp.byteask.ai-5FB3A3.svg)](https://docs.byteask.ai/embedded)\n\nOfficial MCP Registry Namespace: `ai.byteask/embedded-docs` · Remote MCP Endpoint: `https://mcp.byteask.ai/mcp`\n\n[Quickstart](#quickstart) · [Tools](#tools) · [Connect a client](#connect-a-client) · [Configuration](#configuration) · [Hosted server](#hosted-server) · [Contributing](#contributing)\n\n\"A\n\n
\n\n---\n\nByteAsk Embedded MCP is the open-source server behind [ByteAsk Embedded Docs](https://docs.byteask.ai/embedded):\na **source-grounded, page-cited evidence-retrieval** MCP server for coding agents\n(Claude Code, Codex, Cursor) that write firmware / driver / protocol code and need\n*exact* facts — SunSpec points, register offsets, Modbus function codes, trip\nthresholds, SCPI commands, API symbols.\n\nIt returns **verbatim snippets with page citations** — never an authored answer — and\nwhen nothing is relevant enough it says **no match** rather than fabricate. Every\ndocument is treated equally: no authority layer, no filters.\n\n> [!NOTE]\n> **What's in this repo:** the MCP *server* — tools, transports (stdio + Streamable\n> HTTP), bearer auth, DNS-rebinding protection, result rendering — plus a small,\n> pluggable retrieval interface.\n>\n> **What's _not_ in this repo:** the retrieval engine and the document corpus. How\n> documents are parsed, chunked, embedded, and ranked, and the licensed source\n> material itself, sit behind the [`SearchBackend`](src/byteask_embedded_mcp/backend.py)\n> seam and power the hosted endpoint at `https://mcp.byteask.ai/mcp`. This repo ships\n> an in-memory [`SampleBackend`](src/byteask_embedded_mcp/backend.py) (a few\n> illustrative, public-knowledge records) so the server runs out of the box.\n\n## Why\n\n- **Cited, or nothing.** Every hit is verbatim source text with a section + page\n citation. On a miss it returns an honest \"no confident match\" — it never invents a\n register value.\n- **Built for coding agents.** The tool descriptions and triggers are tuned so agents\n call `search_docs` reflexively the moment they see a hex literal, a Modbus code, an\n IEEE clause, a SCPI verb, or an MCU part number — before answering from memory.\n- **Two transports, one server.** `stdio` for local agents, Streamable HTTP for hosted.\n- **Bring your own retrieval.** The search engine is a two-method interface — swap in\n anything behind `BYTEASK_BACKEND` without touching the server.\n- **Zero-setup demo.** The bundled `SampleBackend` runs immediately. No API keys.\n\n## Quickstart\n\nRequires Python ≥ 3.10 and [`uv`](https://docs.astral.sh/uv/).\n\n```bash\nuv sync\nuv run byteask-embedded-mcp # run as an MCP server (stdio)\n```\n\nThat's it — the bundled `SampleBackend` serves a couple of illustrative records, so\n`search_docs` works immediately. Run the offline tests with `uv run pytest`.\n\n## Connect a client\n\n### Hosted (no install)\n\nThe hosted server speaks **Streamable HTTP** at `https://mcp.byteask.ai/mcp` and is\nbacked by the full licensed corpus.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=byteask-embedded-docs&config=eyJ1cmwiOiJodHRwczovL21jcC5ieXRlYXNrLmFpL21jcCJ9)\n\n**Claude Code:**\n\n```bash\nclaude mcp add --transport http byteask-embedded-docs https://mcp.byteask.ai/mcp\n```\n\n
\nCodex, Cursor, and other clients (mcp-remote)\n\n```json\n{\n \"mcpServers\": {\n \"byteask-embedded-docs\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-remote\", \"https://mcp.byteask.ai/mcp\"]\n }\n }\n}\n```\n\n
\n\n### Local (this repo)\n\nThe project-scoped [`.mcp.json`](.mcp.json) registers the stdio server for clients\nthat read it. Manually, for Claude Code:\n\n```bash\nclaude mcp add byteask-embedded-docs -- uv run byteask-embedded-mcp\n```\n\n## Tools\n\nInput is natural language (or an exact identifier). Output is compact markdown.\n\n| Tool | What it does |\n|------|--------------|\n| **`search_docs(query, limit=8)`** | Search the corpus; return ranked, page-cited evidence. Each hit has a document title, a section + page citation, the verbatim snippet, and a `result_id`. A \"no confident match\" response means *not found — do not fabricate*. |\n| **`get_context(result_id)`** | Expand a hit to its full source section. |\n| **`request_document(request)`** | Ask for a missing document to be added (logged server-side). |\n\nExample output:\n\n```markdown\n## Results for \"what Modbus function code writes multiple registers\"\n\n### Sample — Modbus Application Protocol (illustrative) — §6.12, p.30\n> Function code 16 (0x10), Write Multiple Registers, writes a block of contiguous\n> holding registers (1 to 123 registers) in a remote device. ...\n_ref: sample:modbus-fc16_\n```\n\n## Plug in your own retrieval\n\nThe server depends only on a two-method interface\n([`backend.py`](src/byteask_embedded_mcp/backend.py)):\n\n```python\nclass SearchBackend(Protocol):\n def search(self, query, limit=8, effort=None) -> dict: ...\n def get_context(self, result_id, effort=None) -> dict: ...\n```\n\nImplement it, expose a factory `make_backend(config) -> SearchBackend`, and point the\nserver at it:\n\n```bash\nBYTEASK_BACKEND=\"my_pkg.my_module:make_backend\"\n```\n\nThe exact return-value contracts are documented at the top of `backend.py`.\n\n## Configuration\n\nAll settings are environment variables (loaded from `.env`; see [`.env.example`](.env.example)).\n\n| Variable | Default | Notes |\n|----------|---------|-------|\n| `BYTEASK_BACKEND` | — | `module:callable` returning a `SearchBackend`; empty → `SampleBackend` |\n| `BYTEASK_LOGS` | `logs` | where query / request JSONL logs are written |\n| `MCP_TRANSPORT` | `stdio` | `stdio` (local agents) or `http` |\n| `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `127.0.0.1` / `8000` | HTTP bind address |\n| `MCP_HTTP_AUTH_TOKEN` | — | bearer token for HTTP (empty = unauthenticated, dev only) |\n| `MCP_ALLOWED_HOSTS` | — | comma-separated hosts allowed in the `Host` header (`*` disables) |\n| `LOG_LEVEL` | `INFO` | stderr log verbosity |\n\n
\nRunning over HTTP\n\n```bash\nMCP_TRANSPORT=http MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32) \\\n uv run byteask-embedded-mcp --host 0.0.0.0 --port 8000\n```\n\nClients then send `Authorization: Bearer `. The bundled bearer check is a\nshared-secret **stub** — replace it with real auth (OAuth 2.1 resource server, mTLS,\nor a trusted reverse proxy) before exposing publicly. DNS-rebinding protection stays\non independently via `MCP_ALLOWED_HOSTS`.\n\n
\n\n## Hosted server\n\nYou don't need to run anything to use ByteAsk Embedded Docs. The hosted server gives\nClaude Code, Codex, Cursor, and any MCP client exact, page-cited facts from embedded\nand firmware reference docs — register maps, protocol function codes, SCPI commands,\nstandard thresholds, datasheet specs. The guarantee: *verbatim source, or \"no match\" —\nnever an invented value.*\n\n| | |\n|---|---|\n| **Name** | `byteask-embedded-docs` |\n| **Endpoint** | `https://mcp.byteask.ai/mcp` (Streamable HTTP) |\n| **Docs & per-client setup** | |\n\nThis repository is the open-source server that powers that endpoint.\n\n## Project layout\n\n```\nsrc/byteask_embedded_mcp/\n server.py # FastMCP app + 3 tools (search_docs, get_context, request_document)\n backend.py # SearchBackend protocol + in-memory SampleBackend (swap for real retrieval)\n render.py # structured result -> compact markdown\n http_auth.py # Streamable HTTP entrypoint + stub bearer-token guard\n config.py # server config (transport, logging, backend selection)\n schemas.py # Hit / Section result types\n obs.py # per-call JSONL logging\ntests/ # offline unit tests (renderer, backend, server tools)\nassets/ # README demo GIF + its deterministic generator\n```\n\n## Security\n\n- **stdout stays clean** in stdio mode (it is the JSON-RPC channel); all logs go to\n stderr / `logs/*.jsonl`.\n- The HTTP **bearer check is a stub** — unauthenticated if no token is set, a shared\n secret at best. Harden it before exposing widely.\n- **DNS-rebinding protection** is on by default for the HTTP transport.\n\n## Contributing\n\nPRs and issues are welcome.\n\n```bash\nuv sync # install (incl. dev tools)\nuv run pytest # run the offline test suite\n```\n\nA few conventions to keep the server clean:\n\n- **The backend seam is the extension point.** Retrieval internals (parsing, chunking,\n embeddings, ranking) are intentionally out of scope here — build them behind\n `SearchBackend` in your own package, not in this repo.\n- **Keep the dependency surface small** and the stdio path free of the HTTP stack.\n- **Add a test** for new behavior; the suite is fully offline (no network, no keys).\n\n## License\n\n[MIT](LICENSE) © ByteAsk\n", "bytes": 9782, "sha": "8f1f2d05cbdb70f906842457e1052bfd69a520888fa25b42a12c30d34aa33fa3", "repo_slug": "byteask/byteask-embedded-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_ai_byteask_embedded_docs_55b61045/readme" }