SpecDesk MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
SpecDesk
An AI copilot for technical product inquiries. SpecDesk connects an AI model to a distributor's product catalog, datasheets, inventory and order history so it can answer questions like:
"I need a 25 mm lens to focus a 633 nm laser at about 100 mm. Do you have it in stock, and could you supply 200 a quarter?"
The model finds parts that meet the spec, does the engineering math with tested calculators instead of guessing, checks stock and demand, and cites the datasheet sections it relied on. It flags anything a human has to decide, such as volume pricing, custom work or missing information.
The engine works for any industry. Industry knowledge lives in pluggable domain packs, and two ship today:
Domain pack | Fictional company | Categories | Calculators |
| Halvorsen Optical Supply | plano-convex lenses, achromatic doublets, flat mirrors, bandpass filters | thin-lens imaging, focused laser spot size |
| Brightwire Components | resistors, ceramic capacitors, LDO regulators | Ohm's law, LED series resistor, LDO thermal check |
All data is synthetic and reproducible from a seed. Companies, customers and specs are invented, though plausible.
Why this exists
Engineers at technical distributors spend hours on routine inquiries: reading the request, searching the catalog, checking datasheets, doing quick calculations, checking stock and writing a reply. Most of that is lookup and arithmetic, which AI tools handle well. A smaller part is judgment, like custom parts, volume pricing and unclear requirements, and that should stay with a person.
SpecDesk is built around that split. Every number in a reply comes from a tool call, so it can be traced. Every claim cites a source document. Anything outside policy goes to a person instead of getting an automated answer.
Success measures, tracked by the eval suite as it lands:
The right part is found on the first attempt.
Citations actually support the claims made.
Missing information is caught and asked about, never guessed.
Requests over policy limits are escalated (zero false promises).
Engineer time per inquiry drops (estimated from human-review edit rates).
Related MCP server: SheetsData MCP
Status
Step | Scope | State |
1 | Synthetic data, storage, MCP server, tests, CI | ✅ done |
2 | Agent workflow: structured requirement extraction → search → verify → cited draft or escalation | ⏳ next |
3 | Evaluation suite (labelled inquiries, failure injection) running in CI | planned |
4 | Demand forecasting tool with backtests against a naive baseline | planned |
5 | Human review queue UI, tool-call telemetry, Docker, Azure / Snowflake adapters | planned |
Architecture
flowchart LR
subgraph Clients
A[Claude Desktop / Claude Code]
B[SpecDesk agent<br/><i>step 2</i>]
end
subgraph "SpecDesk MCP server"
T[Tools: search, product, inventory,<br/>documents, demand, calculators]
R[Resource: catalog schema]
end
subgraph Data
DB[(SQLite<br/>products · inventory · orders<br/>documents + FTS5 index)]
end
P[Domain pack<br/>optics · electronics · ...]
A -- MCP stdio --> T
B -- MCP --> T
T --> C[Catalog layer<br/>validation + actionable errors] --> DB
P -. schema, calculators .-> T
P -. generates .-> DBThe domain pack defines categories, attribute schemas with units and allowed values, datasheet and guide text, demand patterns and calculators. Everything else is generic. See ADR 0001.
Quickstart
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
specdesk generate --domain optics # -> data/optics.db (about 0.3 s)
specdesk generate --domain electronics # -> data/electronics.db
specdesk info --db data/optics.db
pytestConnect it to Claude
Claude Code:
claude mcp add specdesk -- /absolute/path/to/.venv/bin/specdesk serve --db /absolute/path/to/data/optics.dbClaude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"specdesk": {
"command": "/absolute/path/to/.venv/bin/specdesk",
"args": ["serve", "--db", "/absolute/path/to/data/optics.db"]
}
}
}Then ask something like "Which lenses could focus a 2 mm HeNe beam to under 50 µm, and are any in stock?"
You can also inspect the server interactively with npx @modelcontextprotocol/inspector specdesk serve --db data/optics.db.
MCP tools
All tools are read-only (readOnlyHint), return typed structured output and have a published output schema.
Tool | Purpose |
| Categories, counts, history window, quote threshold, available calculators |
| Exact attribute keys, units, allowed values and observed ranges, used before filtering |
| Attribute filters ( |
| Labelled specs with units, price, lead time, stock and datasheet id |
| Batch availability, ship estimate and quote-required flag, with per-item errors |
| BM25 search over datasheets, guides and policy, returning snippets and citations ( |
| Full document or one section, with citations |
| Zero-filled monthly units and order lines per SKU |
| Deterministic calculators that vary by domain pack |
Resource: specdesk://catalog/schema holds the full attribute schema as Markdown.
How failures are handled
A model will call tools wrongly. The question is whether it can recover. Each failure mode below has a test in tests/.
Failure | Behaviour |
Misspelled attribute ( | Error: "Did you mean 'focal_length_mm'?" plus the valid list |
Invalid value ( | Error listing the allowed values ( |
Wrong operator for type ( | Error naming the valid operators |
Unknown SKU ( | Error suggesting |
One bad SKU in a batch | That item is returned with |
Over-specific text search | Falls back to partial matches, with a hint to use filters |
Zero results | A hint saying what to loosen |
Quantity above the quote threshold |
|
Discontinued item | Can't be backordered, so the note says to offer an equivalent |
Hostile input (SQL or FTS injection) | Attribute names are allow-listed, values are bound parameters, FTS terms are quoted and the connection is read-only |
Bad calculator input ( | A clear tool error, not a crash |
Design decisions
Adding a domain
Create src/specdesk/domains/<name>.py that defines categories (attributes, a name template, a pricing rule, a demand profile and care notes), optional guides and calculators, and a PACK. Then register it in domains/__init__.py. Pack validation catches conflicting attribute units across categories and undocumented calculators. Generation, search, documents, inventory, the MCP tools and the tests all work for the new domain without further changes.
Project layout
src/specdesk/
domain.py # DomainPack / Category / AttributeSpec types
domains/ # optics.py, electronics.py, registry
generate.py # reproducible synthetic data
schema.sql # tables + FTS5 indexes
catalog.py # validated, read-only data access
models.py # pydantic I/O models (also MCP output schemas)
server.py # MCP server (mcp Python SDK v2)
cli.py # specdesk domains | generate | info | serve
tests/ # 63 tests: packs, generation, catalog, calculators, MCP end to end
docs/decisions/ # architecture decision recordsLicense
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Live data for AI agents. Search the catalog, read the price, call the tool; keys stay server-side.
AI-callable calculators and engineering models with real formulas. No hallucinated math.
Search real parts with datasheet-provenance specs, check compatibility and compose priced BOMs.
Deterministic industrial replacement engine with official catalogs and expert accuracy checks.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables searching for electronic components, comparing prices across distributors, checking availability, and retrieving datasheets through the Nexar/Octopart API with specialized tools for resistors, capacitors, inductors, semiconductors, crystals, and connectors.12-
- AlicenseAqualityBmaintenanceProvides AI agents with instant, structured access to electronic component datasheets, pinouts, and electrical specifications without requiring PDF uploads. It enables seamless part searching, design validation, and side-by-side component comparisons across major hardware providers.1476 npm12MIT
- AlicenseNot gradedqualityBmaintenanceSpacecraft component specifications read from vendor datasheets (2,500+ products, 24 categories): search by engineering requirements, compare, budget mass and power, read datasheet digests and facts, find data gaps, and assemble a bus around parts you lock. Every value cites its datasheet page; missing data is named, never guessed.46 npm1MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to search enterprise Auto-ID products and exact SKUs, read live stock and current pricing, and explore variants, accessories, consumables and support relationships through a public read-only endpoint. It also surfaces manuals, firmware, drivers and other verified technical resources from the vendor's support center.-