diff --git a/.gitignore b/.gitignore
index 99e0aef..d548bc5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,9 @@ __pycache__/
*.py[cod]
.pytest_cache/
.venv/
+*.egg-info/
+build/
+dist/
.env
# Environment files and local credentials. Keep the example template tracked.
diff --git a/MCP_SETUP.md b/MCP_SETUP.md
index e7a19c0..1a1bb54 100644
--- a/MCP_SETUP.md
+++ b/MCP_SETUP.md
@@ -75,7 +75,7 @@ An unauthenticated request to `/mcp` should return HTTP 401 and advertise OAuth
1. Open **Settings > Apps > Developer mode > New Plugin**.
2. Name it `Partuno`.
-3. Set the description to `Open-source MCP server for electronic component research, BOM analysis, sourcing optimization, and safe distributor workflows.`
+3. Set the description to `Provider-neutral DigiKey and Mouser MCP server for electronic component research, BOM analysis, sourcing comparison, and safe distributor workflows.`
4. Choose **Server URL**.
5. Enter `https://YOUR-SERVICE.onrender.com/mcp`.
6. Choose **OAuth**.
diff --git a/README.md b/README.md
index 55d8ad2..78dd746 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Partuno
+# Partuno — DigiKey & Mouser MCP Server
@@ -8,13 +8,16 @@
[](LICENSE)
[](https://www.python.org/)
+
+
## Local-first component intelligence for MCP
-Partuno is an open-source Model Context Protocol (MCP) server for electronic
-component research, BOM analysis, sourcing comparisons, and carefully bounded
-distributor workflows. It connects AI assistants to operator-owned DigiKey and
-Mouser credentials while returning evidence, normalized attributes, and
-explicit uncertainty.
+Partuno is an open-source, provider-neutral, local-first Model Context Protocol
+(MCP) server for electronic component research, BOM analysis, sourcing
+comparison, and safe distributor workflows. Connect an AI assistant to your
+own DigiKey and Mouser credentials without shared credentials or autonomous
+ordering, while keeping evidence, normalized attributes, and explicit
+uncertainty visible.
Partuno was initially developed as a native MCP server. Native MCP is the
recommended connection because it works as an app in ordinary ChatGPT
@@ -45,6 +48,14 @@ python -m partuno
Then configure your MCP client to launch `python -m partuno` from the checkout.
See [MCP setup](MCP_SETUP.md) and the [local deployment guide](docs/deployment/local.md).
+For a hosted directory listing, see [Partuno on Glama](https://glama.ai/mcp/servers/JPMarhefka/partuno).
+
+After the `partuno` PyPI package is published, the equivalent package-based
+launcher is:
+
+```bash
+uvx --from partuno partuno-mcp
+```
### Self-host a remote MCP server
@@ -79,6 +90,46 @@ The Action setup details are documented in [MCP setup](MCP_SETUP.md).
See the [capability reference](docs/capabilities.md) for the current scope and
the safety boundary for each workflow.
+## DigiKey MCP server
+
+Partuno can run as a local-first DigiKey MCP server for component search,
+product research, current pricing and availability, lifecycle checks, MyLists,
+quotes, receiving reconciliation, and other bounded account workflows. The
+[DigiKey MCP server guide](docs/guides/digikey-mcp-server.md) covers setup,
+supported workflows, and the provider-specific safety boundaries.
+
+## Mouser MCP server
+
+Partuno also provides a Mouser MCP server surface for catalog search, exact
+offer comparison, read-only order history, and preview-confirmed Cart
+workflows. The [Mouser MCP server guide](docs/guides/mouser-mcp-server.md)
+explains the separate operator-owned Mouser credentials and what the server
+does and does not execute.
+
+## Electronics BOM MCP server
+
+Use Partuno as an electronics BOM MCP server to consolidate duplicate rows,
+resolve exact products, estimate current merchandise cost, check stock and
+lifecycle risk, inspect compliance and lead-time signals, and find substitutes
+or alternate packaging. See the [electronics BOM MCP server guide](docs/guides/electronics-bom-mcp.md)
+for a complete read-only example and known limitations.
+
+## AI component sourcing
+
+Partuno turns a natural-language engineering request into a traceable sourcing
+workflow. Recommendations preserve `meets`, `does_not_meet`, and `unknown`
+evidence states, so missing or ambiguous attributes are not silently treated as
+qualified requirements. The [natural-language examples](docs/examples/README.md)
+show the intended interaction style.
+
+## DigiKey vs Mouser comparison
+
+For an exact comparison, Partuno matches manufacturer and MPN identity first,
+then compares requested-quantity pricing, minimum order quantity, order
+multiples, purchasable quantity, availability, and manufacturer lead time. If a
+provider fails or returns incomplete evidence, the result remains partial
+instead of inventing a winner. See the [DigiKey vs Mouser comparison guide](docs/guides/mouser-mcp-server.md#compare-exact-offers-across-digikey-and-mouser).
+
## What Partuno does not do
- It does not supply DigiKey or Mouser credentials.
@@ -130,6 +181,7 @@ product research, BOM review, and safe account-preview workflows.
| Security and credential handling | [Security guide](docs/security.md) |
| Offline and live validation | [Testing guide](docs/testing.md) and [validation notes](VALIDATION.md) |
| Natural-language usage examples | [Examples](docs/examples/README.md) |
+| DigiKey, Mouser, and BOM entry points | [Search-focused guides](docs/guides/README.md) |
| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
| Security reports | [SECURITY.md](SECURITY.md) |
| Release history | [CHANGELOG.md](CHANGELOG.md) |
diff --git a/docs/guides/README.md b/docs/guides/README.md
new file mode 100644
index 0000000..0d2d551
--- /dev/null
+++ b/docs/guides/README.md
@@ -0,0 +1,23 @@
+# Partuno search-focused guides
+
+These are practical entry points for people looking for a DigiKey MCP server,
+Mouser MCP server, electronics BOM MCP server, or AI component-sourcing tool.
+Each guide includes setup, a public demo, supported workflows, and limitations.
+
+When Partuno's website is published, use these guides as the source content for
+the following descriptive routes:
+
+- [`/digikey-mcp-server/`](digikey-mcp-server.md)
+- [`/mouser-mcp-server/`](mouser-mcp-server.md)
+- [`/electronics-bom-mcp/`](electronics-bom-mcp.md)
+
+The pages are intentionally useful documentation rather than duplicate
+keyword-only landing pages. Partuno is independent; DigiKey and Mouser names
+identify integrations and do not imply endorsement.
+
+## Common links
+
+- [Partuno on GitHub](https://github.com/JPMarhefka/Partuno)
+- [Partuno on Glama](https://glama.ai/mcp/servers/JPMarhefka/partuno)
+- [Native MCP setup](../../MCP_SETUP.md)
+- [Capability reference](../capabilities.md)
diff --git a/docs/guides/digikey-mcp-server.md b/docs/guides/digikey-mcp-server.md
new file mode 100644
index 0000000..d61c573
--- /dev/null
+++ b/docs/guides/digikey-mcp-server.md
@@ -0,0 +1,71 @@
+# DigiKey MCP Server for Electronic Component Research | Partuno
+
+Partuno is a provider-neutral, local-first **DigiKey MCP server** for
+electronic component search, product research, BOM analysis, sourcing
+comparison, lifecycle checks, and bounded distributor workflows. It connects an
+MCP client to the operator's own DigiKey credentials; it is not an official
+DigiKey service and does not provide shared credentials.
+
+## What the DigiKey MCP server does
+
+Use Partuno to:
+
+- Search by keyword, manufacturer part number, or DigiKey product number.
+- Retrieve product details, stock, lifecycle, lead time, classifications,
+ pricing, datasheets, images, substitutes, and product-change notices.
+- Analyze BOMs for current merchandise cost, shortages, end-of-life risk,
+ compliance, lead time, tariffs, substitutes, and alternate packaging.
+- Preview and explicitly confirm supported MyList and quote changes.
+- Decode product-bag or packing-list barcodes and reconcile received quantities.
+
+
+ 
+
+
+## Setup
+
+The default deployment is local MCP over stdio. Credentials remain in the
+operator's environment and no public network port is required:
+
+```bash
+git clone https://github.com/JPMarhefka/partuno.git
+cd partuno
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements.txt
+cp .env.example .env
+python -m partuno
+```
+
+Then configure the MCP client to launch `python -m partuno` from the checkout.
+See the [native MCP setup guide](../../MCP_SETUP.md) for local and
+operator-owned remote deployments.
+
+## Supported MCP workflows
+
+The most relevant read-only tools include `search_products`,
+`get_product_details`, `get_product_pricing`, `research_product`,
+`analyze_bom`, `audit_lifecycle`, `get_substitutions`, and
+`get_product_change_notifications`. Account workflows include MyLists, quotes,
+order status, barcodes, and packing lists when the operator's DigiKey access
+allows them.
+
+For the complete surface and safety boundary, see the
+[capability reference](../capabilities.md).
+
+## Limitations and safety
+
+- You must supply and authorize your own DigiKey credentials.
+- Product, stock, pricing, and lead-time values are live provider data and can
+ change.
+- Missing or ambiguous engineering attributes remain `unknown`.
+- Manufacturer lead time is not a shipping estimate; shipping cost and delivery
+ ETA are not provided by the comparison workflow.
+- Partuno does not submit distributor orders or silently execute account changes.
+
+## Links
+
+- [Partuno source repository](https://github.com/JPMarhefka/Partuno)
+- [Partuno on Glama](https://glama.ai/mcp/servers/JPMarhefka/partuno)
+- [Mouser MCP server guide](mouser-mcp-server.md)
+- [Electronics BOM MCP server guide](electronics-bom-mcp.md)
diff --git a/docs/guides/electronics-bom-mcp.md b/docs/guides/electronics-bom-mcp.md
new file mode 100644
index 0000000..3ab73f2
--- /dev/null
+++ b/docs/guides/electronics-bom-mcp.md
@@ -0,0 +1,84 @@
+# Electronics BOM MCP Server for AI Sourcing | Partuno
+
+Partuno is an **electronics BOM MCP server** for analyzing component lists,
+checking sourcing risk, and comparing distributor offers with evidence. It
+connects an AI assistant to operator-owned DigiKey and Mouser integrations while
+keeping missing data, provider failures, and safety boundaries explicit.
+
+## What the electronics BOM MCP server does
+
+Given a BOM and requested quantities, Partuno can:
+
+- Consolidate duplicate part numbers and preserve customer references.
+- Resolve exact product details and calculate current estimated merchandise cost.
+- Check stock coverage, minimum order quantities, price breaks, lifecycle,
+ manufacturer lead time, RoHS, REACH, MSL, ECCN, and HTS data.
+- Flag last-buy dates, product-change notices, shortages, tariff-bearing options,
+ and Marketplace products.
+- Retrieve substitutes and alternate packaging for risky or unavailable parts.
+- Compare exact DigiKey and Mouser offers when both provider integrations are
+ available.
+
+
+ 
+
+
+## Example request
+
+```text
+Review this small BOM for sourcing risk and availability:
+
+U1 — onsemi LM358DR2G, quantity 10
+U2 — onsemi LM358DR2G, quantity 10
+
+Check pricing, stock, lifecycle, compliance, lead time, alternate packaging,
+and substitutes. Summarize the important risks without changing any account or
+purchasing data.
+```
+
+See [more natural-language examples](../examples/README.md) for component
+recommendation, exact offer comparison, product research, and safe account
+previews.
+
+## Setup
+
+The default path is local MCP over stdio:
+
+```bash
+git clone https://github.com/JPMarhefka/partuno.git
+cd partuno
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements.txt
+cp .env.example .env
+python -m partuno
+```
+
+Configure the MCP client to launch `python -m partuno` from the checkout. The
+[native MCP setup guide](../../MCP_SETUP.md) also covers loopback HTTP and an
+operator-owned remote deployment.
+
+## Supported MCP workflows
+
+The main BOM and sourcing tools are `analyze_bom`, `optimize_bom_pricing`,
+`audit_lifecycle`, `recommend_components`, and `compare_component_offers`.
+They combine provider responses but preserve which provider supplied each
+signal and whether a requirement is `meets`, `does_not_meet`, or `unknown`.
+
+## Limitations and safety
+
+- A BOM review is evidence gathering, not an engineering approval or purchasing
+ decision.
+- Unknown or conflicting attributes are reported rather than guessed.
+- Stock, pricing, lifecycle, and lead-time values are time-sensitive provider
+ data.
+- Shipping, tax, and delivery ETA are not silently estimated.
+- Account, list, quote, and Cart changes require their explicit confirmation
+ boundary; Partuno cannot submit an order.
+
+## Links
+
+- [Partuno source repository](https://github.com/JPMarhefka/Partuno)
+- [Partuno on Glama](https://glama.ai/mcp/servers/JPMarhefka/partuno)
+- [DigiKey MCP server guide](digikey-mcp-server.md)
+- [Mouser MCP server guide](mouser-mcp-server.md)
diff --git a/docs/guides/mouser-mcp-server.md b/docs/guides/mouser-mcp-server.md
new file mode 100644
index 0000000..93dc26b
--- /dev/null
+++ b/docs/guides/mouser-mcp-server.md
@@ -0,0 +1,76 @@
+# Mouser MCP Server for Component Sourcing | Partuno
+
+Partuno is a provider-neutral, local-first **Mouser MCP server** for catalog
+search, exact component-offer comparison, BOM sourcing, read-only order
+history, and carefully bounded Cart workflows. It uses the operator's own
+Mouser API credentials and is not affiliated with or endorsed by Mouser.
+
+## What the Mouser MCP server does
+
+Use Partuno to:
+
+- Search Mouser by keyword or exact part number.
+- Inspect availability, lifecycle, compliance, and price-break data.
+- Compare the exact manufacturer and MPN across Mouser and DigiKey at a
+ requested quantity.
+- Read order history and individual order details where the account API allows
+ it.
+- Read a Cart and preview an exact add, update, remove, replacement, or
+ order-copy change before execution.
+
+
+ 
+
+
+## Setup
+
+Start with the [native MCP setup guide](../../MCP_SETUP.md). For a local
+deployment, install Partuno and configure the operator-owned Mouser keys in the
+environment alongside the DigiKey settings:
+
+```bash
+git clone https://github.com/JPMarhefka/partuno.git
+cd partuno
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements.txt
+cp .env.example .env
+python -m partuno
+```
+
+Mouser Search and Account API keys remain separate. They are read from the
+deployment configuration and are never supplied as MCP tool parameters.
+
+## Supported MCP workflows
+
+The key tools are `search_mouser_products`,
+`compare_component_offers`, `search_mouser_order_history`,
+`get_mouser_order`, `get_mouser_cart`, `preview_mouser_cart_change`, and
+`execute_mouser_cart_change`. The comparison workflow requires strict
+manufacturer-plus-MPN identity before it compares requested-quantity offers.
+
+## Compare exact offers across DigiKey and Mouser
+
+Ask Partuno to compare a specific manufacturer part number and quantity. It
+reports unit price, merchandise total, minimum order quantity, order multiple,
+purchasable quantity, availability, lead time, and provider status. If one
+provider fails or the evidence is incomplete, the result remains partial
+instead of inventing a winner.
+
+See the [DigiKey vs Mouser comparison section](../../README.md#digikey-vs-mouser-comparison)
+and the [capability reference](../capabilities.md) for the comparison contract.
+
+## Limitations and safety
+
+- You must supply and authorize your own Mouser API credentials.
+- Shipping cost and delivery ETA are not returned by the comparison workflow.
+- Cart changes require an exact preview and a one-time execution token.
+- Partuno never submits a distributor order.
+- Inventory, pricing, and account permissions can change between requests.
+
+## Links
+
+- [Partuno source repository](https://github.com/JPMarhefka/Partuno)
+- [Partuno on Glama](https://glama.ai/mcp/servers/JPMarhefka/partuno)
+- [DigiKey MCP server guide](digikey-mcp-server.md)
+- [Electronics BOM MCP server guide](electronics-bom-mcp.md)
diff --git a/main.py b/main.py
index 4f22277..cb15deb 100644
--- a/main.py
+++ b/main.py
@@ -109,8 +109,9 @@
title="Partuno",
version="4.0.0",
description=(
- "Open-source MCP server for electronic component research, BOM analysis, "
- "sourcing optimization, and safe distributor workflows. "
+ "Open-source MCP server for DigiKey and Mouser electronic component research, "
+ "BOM analysis, sourcing comparison, and safe distributor workflows. "
+ "Partuno is provider-neutral and local-first. "
"Partuno connects to user-authorized DigiKey and Mouser integrations, "
"supports strict offer comparison and evidence-based component recommendations, "
"plus DigiKey Product Information V4, "
diff --git a/mcp_server.py b/mcp_server.py
index ec78305..3f595de 100644
--- a/mcp_server.py
+++ b/mcp_server.py
@@ -388,7 +388,9 @@ def build_mcp_server(*, local: bool = False) -> FastMCP | None:
website_url=None if local else settings.mcp_base_url,
auth=auth_provider,
instructions=(
- "Partuno is an open-source, provider-neutral MCP server. Use DigiKey and Mouser "
+ "Partuno is an open-source, provider-neutral DigiKey and Mouser MCP server for "
+ "electronic component research, BOM analysis, sourcing comparison, and safe "
+ "distributor workflows. Use DigiKey and Mouser "
"for authoritative component research, live inventory, "
"pricing, and exact offer comparison. Ask for missing critical engineering "
"requirements before recommending a component, and distinguish suitability "
diff --git a/pyproject.toml b/pyproject.toml
index f8a1f55..d78e138 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -5,9 +5,18 @@ build-backend = "setuptools.build_meta"
[project]
name = "partuno"
version = "4.0.0"
-description = "Local-first MCP server for electronic component research and sourcing"
+description = "Provider-neutral DigiKey and Mouser MCP server for electronic component research, BOM analysis, and sourcing comparison"
readme = "README.md"
requires-python = ">=3.12"
+keywords = [
+ "mcp",
+ "model-context-protocol",
+ "digikey",
+ "mouser",
+ "electronics",
+ "bill-of-materials",
+ "component-sourcing",
+]
dependencies = [
"fastapi==0.139.2",
"uvicorn[standard]==0.51.0",
@@ -20,6 +29,12 @@ dependencies = [
[project.scripts]
partuno-mcp = "partuno:main"
+[project.urls]
+Homepage = "https://github.com/JPMarhefka/Partuno"
+Repository = "https://github.com/JPMarhefka/Partuno"
+Documentation = "https://github.com/JPMarhefka/Partuno#readme"
+Issues = "https://github.com/JPMarhefka/Partuno/issues"
+
[tool.setuptools]
py-modules = [
"app",
diff --git a/server.json b/server.json
new file mode 100644
index 0000000..73ee4a4
--- /dev/null
+++ b/server.json
@@ -0,0 +1,66 @@
+{
+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+ "name": "io.github.JPMarhefka/partuno",
+ "title": "Partuno — DigiKey & Mouser MCP Server",
+ "description": "DigiKey and Mouser MCP server for component research, BOM analysis, and sourcing.",
+ "repository": {
+ "id": "1331637101",
+ "url": "https://github.com/JPMarhefka/Partuno",
+ "source": "github"
+ },
+ "websiteUrl": "https://github.com/JPMarhefka/Partuno",
+ "icons": [
+ {
+ "src": "https://raw.githubusercontent.com/JPMarhefka/Partuno/main/docs/assets/partuno-plugin-icon.png",
+ "mimeType": "image/png",
+ "sizes": ["any"]
+ }
+ ],
+ "version": "4.0.0",
+ "packages": [
+ {
+ "registryType": "pypi",
+ "registryBaseUrl": "https://pypi.org",
+ "identifier": "partuno",
+ "version": "4.0.0",
+ "runtimeHint": "uvx",
+ "packageArguments": [
+ {
+ "type": "positional",
+ "value": "partuno-mcp",
+ "isRequired": true
+ }
+ ],
+ "transport": {
+ "type": "stdio"
+ },
+ "environmentVariables": [
+ {
+ "name": "DIGIKEY_ACCESS_TOKEN",
+ "description": "Optional DigiKey bearer token for local mode.",
+ "isSecret": true
+ },
+ {
+ "name": "DIGIKEY_CLIENT_ID",
+ "description": "DigiKey OAuth client ID for the operator's integration.",
+ "isSecret": true
+ },
+ {
+ "name": "DIGIKEY_CLIENT_SECRET",
+ "description": "DigiKey OAuth client secret for the operator's integration.",
+ "isSecret": true
+ },
+ {
+ "name": "MOUSER_SEARCH_API_KEY",
+ "description": "Optional Mouser Search API key for catalog workflows.",
+ "isSecret": true
+ },
+ {
+ "name": "MOUSER_ACCOUNT_API_KEY",
+ "description": "Optional Mouser Account API key for order-history and Cart workflows.",
+ "isSecret": true
+ }
+ ]
+ }
+ ]
+}