Circuit Context

Source-backed hardware engineering guidance for engineers and AI assistants. Search recommendations, read their conditions and exceptions, and follow citations to the publisher. Covers schematics, PCB layout, interfaces, EMI/EMC and mechanical integration.

Start

Requires Python 3.10 or newer.

python -m pip install ".[mcp]"
circuit-context serve

serve runs a read-only MCP server over stdio. Configure an MCP client to run circuit-context with the argument serve. It exposes:

For example, search {"query": "return path", "domain": "pcb"}, then read a returned ID with get_guideline. A two-layer review can start directly with {"id": "two-layer-emc-workflow"}.

Related MCP server: Security Context MCP Server

Other ways to use it

circuit-context search "return path" --domain pcb
circuit-context get two-layer-emc-workflow
circuit-context catalogue

from circuit_context import get_guideline, search_guidelines

hits = search_guidelines("termination", interface="can")
guide = get_guideline("can-end-termination")

The base package supports Python and CLI retrieval without FastMCP. Install the mcp extra for the server. The AI client performs reasoning and uses separate CAD tools for design work; this package does not place parts, route boards or generate answers with an internal LLM.

Knowledge and retrieval

The corpus has 161 editorial guides and 77 source records, expanded from KiCadFlow's engineering guidance. JSON is the maintained source; SQLite FTS5/BM25 provides offline keyword retrieval by default. Optional local semantic search handles paraphrases; hybrid search combines both using reciprocal rank fusion. An optional cross-encoder reranks the candidates.

python -m pip install ".[mcp,search]"
circuit-context prepare-search --reranker
circuit-context search "Where does returning current go when a signal changes layers?" --method hybrid

Model downloads happen only during explicit preparation. Queries run locally. Use --rerank to enable the second stage, or MCP arguments {"query": "...", "method": "hybrid", "rerank": true}. Neither semantic similarity nor reranking establishes that the corpus contains an answer. See setup and measured tradeoffs.

Applicability, required inputs, verification, limitations and source editions stay attached to each guide. Missing coverage is reported. The corpus has not undergone independent hardware-engineer review and does not establish product compliance.

The generated index lives in ~/.circuit-context/cache/; override it with CIRCUIT_CONTEXT_DIR. It contains guidance, not user queries or project files.

• Coverage and authoring

• Two-layer stackup and EMC

• Four-layer stackup choices and review

• Materials, calculations and grounding

• Placement, routing geometry and manufacturing review

• Schematic visual layout and readability

• Evidence format and RAGFlow assessment

• GPIO, UART, SPI and I2C

• Serial memory, storage, digital audio and debug

• USB-C and PD

• Source capture and Markdown conversion

• Architecture and next steps

Development

python -m pip install -e ".[mcp,dev,ingest,search]"
python -m ruff check .
python -m mypy
python examples/scripts/pcb_knowledge.py
python examples/scripts/hybrid_contract.py
python -m build

The example checks actual MCP retrieval, citations, bounds and cache recovery in both protocol modes. Its prompt fixtures also describe AI expectations; passing retrieval checks does not measure model reasoning or hardware outcomes.

Publisher captures, extracted Markdown, page images and generated reports stay under ignored out/. They are not distributed with the package.

AGPL-3.0-only. See LICENSE and provenance.