<div align="center">

# mcp-nexar

Model Context Protocol server for Nexar/Octopart component search.

[![License](https://img.shields.io/github/license/SpectraSynq/mcp-nexar?style=flat-square)](LICENSE)
[![GitHub](https://img.shields.io/badge/github-SpectraSynq%2Fmcp--nexar-blue?style=flat-square&logo=github)](https://github.com/SpectraSynq/mcp-nexar)
[![Discord](https://img.shields.io/badge/discord-join-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/8y8rXegU8j)

</div>

`mcp-nexar` exposes Nexar GraphQL supply search through MCP tools for part lookup, exact MPN search, and datasheet URL extraction. It is intended for PCB design and EDA agents that need Octopart/Nexar component data without embedding project-specific K1 hardware code.

This repository is the canonical source for the Nexar MCP server. `SpectraSynq/K1.hardware` consumes it by repository reference instead of carrying a second editable copy.

## Quickstart

Install in an isolated Python environment:

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
export NEXAR_CLIENT_ID="your-client-id"
export NEXAR_CLIENT_SECRET="your-client-secret"
mcp-nexar
```

Nexar credentials are required for live API calls. Create your own application credentials in Nexar; do not commit them to a repository or MCP config file.

## Tools

- `parts_search(q, limit=3)` - free-text supply search for MPNs, manufacturers, and datasheet URLs.
- `part_by_mpn(mpn)` - exact MPN lookup with basic specs.
- `best_datasheet_url(mpn)` - extracts the first `bestDatasheet.url` from an MPN search.

## Claude Desktop example

```json
{
  "mcpServers": {
    "nexar": {
      "command": "/absolute/path/to/mcp-nexar/.venv/bin/mcp-nexar",
      "env": {
        "NEXAR_CLIENT_ID": "your-client-id",
        "NEXAR_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

## Honest local demo

This demo proves the package imports and refuses to call the network without credentials:

```bash
python - <<'PY'
from mcp_nexar.server import clear_token_cache, get_token

clear_token_cache()
try:
    get_token()
except RuntimeError as exc:
    print(exc)
PY
```

Expected output:

```text
Set NEXAR_CLIENT_ID and NEXAR_CLIENT_SECRET before using Nexar tools.
```

Run the offline test harness:

```bash
python -m pip install -e ".[dev]"
python -m pytest -q
```

## Provenance

Extracted from `SpectraSynq/K1.hardware` after the repository transfer to the SpectraSynq organisation.

- Source commit: `002fc9770c6211a752dfb50c43802c245c7e69`
- Source file: `mcp/mcp-nexar/server.py`
- Source SHA-256: `cbb668253d78fa2e01e6ccf87ee2e7bee56555644e583c91239bad757ae7ce94`

## Part of the SpectraSynq toolchain

- [K1.hardware](https://github.com/SpectraSynq/K1.hardware) - flagship KiCad and hardware automation repository.
- [mcp-lcsc](https://github.com/SpectraSynq/mcp-lcsc) - LCSC OpenAPI component lookup.
- [mcp-kicad-cli](https://github.com/SpectraSynq/mcp-kicad-cli) - KiCad CLI automation through MCP.

## License

Apache-2.0 - see [LICENSE](LICENSE).