Skip to main content
Glama

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

optics

Halvorsen Optical Supply

plano-convex lenses, achromatic doublets, flat mirrors, bandpass filters

thin-lens imaging, focused laser spot size

electronics

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 .-> DB

The 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
pytest

Connect it to Claude

Claude Code:

claude mcp add specdesk -- /absolute/path/to/.venv/bin/specdesk serve --db /absolute/path/to/data/optics.db

Claude 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

specdesk_catalog_overview

Categories, counts, history window, quote threshold, available calculators

specdesk_describe_category

Exact attribute keys, units, allowed values and observed ranges, used before filtering

specdesk_search_products

Attribute filters (eq, lt, between, in, ...), free text, stock, price, sorting, pagination

specdesk_get_product

Labelled specs with units, price, lead time, stock and datasheet id

specdesk_check_inventory

Batch availability, ship estimate and quote-required flag, with per-item errors

specdesk_search_documents

BM25 search over datasheets, guides and policy, returning snippets and citations (DS-OPT-PCX-0012 §2)

specdesk_get_document

Full document or one section, with citations

specdesk_demand_history

Zero-filled monthly units and order lines per SKU

specdesk_calc_*

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 (focal_lenght)

Error: "Did you mean 'focal_length_mm'?" plus the valid list

Invalid value (coating = "silver")

Error listing the allowed values (Protected Silver, ...)

Wrong operator for type (contains on a number)

Error naming the valid operators

Unknown SKU (OPT-PCX-001)

Error suggesting OPT-PCX-0001 first. It never substitutes silently, because a wrong guess would quote the wrong part

One bad SKU in a batch

That item is returned with found: false and suggestions, and the rest still succeed

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

requires_quote: true and a policy note, which the agent turns into an escalation

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 (f = 0)

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 records

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
      -
    • A
      license
      A
      quality
      B
      maintenance
      Provides 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.
      14
      76 npm
      12
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Spacecraft 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 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      -