From 8ff3ee2519f259de0eaf0e8bcaaa04f388640d31 Mon Sep 17 00:00:00 2001 From: OminousPanda110 Date: Wed, 12 Aug 2026 14:05:52 -0700 Subject: [PATCH] docs: improve Partuno discoverability and registry metadata --- .gitignore | 3 ++ MCP_SETUP.md | 2 +- README.md | 64 ++++++++++++++++++++--- docs/guides/README.md | 23 ++++++++ docs/guides/digikey-mcp-server.md | 71 +++++++++++++++++++++++++ docs/guides/electronics-bom-mcp.md | 84 ++++++++++++++++++++++++++++++ docs/guides/mouser-mcp-server.md | 76 +++++++++++++++++++++++++++ main.py | 5 +- mcp_server.py | 4 +- pyproject.toml | 17 +++++- server.json | 66 +++++++++++++++++++++++ 11 files changed, 404 insertions(+), 11 deletions(-) create mode 100644 docs/guides/README.md create mode 100644 docs/guides/digikey-mcp-server.md create mode 100644 docs/guides/electronics-bom-mcp.md create mode 100644 docs/guides/mouser-mcp-server.md create mode 100644 server.json 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

Partuno logo @@ -8,13 +8,16 @@ [![License](https://img.shields.io/github/license/JPMarhefka/partuno)](LICENSE) [![Python](https://img.shields.io/badge/python-3.12%2B-3776AB)](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. + +

+ Partuno DigiKey MCP server researching an electronic component +

+ +## 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. + +

+ Partuno electronics BOM MCP server reviewing sourcing risk +

+ +## 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. + +

+ Partuno comparing exact component offers across Mouser and DigiKey +

+ +## 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 + } + ] + } + ] +}