Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
DATASHEET_LENS_HOMENoThe folder for the central datasheet-lens store. If unset, the default is ~/.datasheet-lens.~/.datasheet-lens

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

datasheet-lens gives the content of component datasheets (PDF): an index, a text search and the original pages. Read each value from the original (get_page_image or get_pdf_pages), never from the text layer alone: the text layer can lose signs, units, subscripts and the structure of tables. When a tool tells about a newer release or a restart of the client, tell the user one time.

User project: the project file datasheet-lens.toml must hold the same parts as the CAD project (schematic, BOM). At the start of the work, and after each change of the CAD project, do these steps:

  1. Get the parts of the CAD project (all fields of each symbol, with their names) from the CAD tool: a BOM file (CSV, for example export_bom of kicad-workbench) or a list from its MCP server. A general value with no MPN (10k) has no selected part. MPN = '-' tells that the symbol needs no part (a test point).

  2. project_check(bom=) or project_check(parts) with all parts: it gives the parts that are missing, extra or different, with the next call. Give path when the working folder of the server is not in the project.

  3. For each missing part: find its datasheet (list_documents), or add it with add_document (a URL or a local PDF). Then project_add_part(mpn, base, document). mpn is the concrete orderable MPN of the BOM (TLV75533PDBVR, get_ordering_codes gives them), base is the part of the datasheet (TLV755P). If you cannot get the datasheet, tell the user the MPN, the reason and the search links of part_links(mpn).

  4. Tell the user about each change, different or extra part, and when a CAD MPN and its datasheet do not agree (value, package, variant). For a new MPN, add its datasheet at once; a change is valid only when the user confirms it. The CAD BOM is the master: write each part that the user confirms into the CAD project too (the fields that project_check names; kicad-workbench: set_symbol_fields), and into the project file (project_update_part, adopt_part). Remove a part only when the user agrees.

  5. project_sync: it copies the documents into the project folder. Then project_check again: it must give no missing, extra or different part.

  6. project_availability, as the next steps of project_check give it: tell the user each WARNING (not orderable, no stock, lifecycle risk) and each note about a missing API key. search_distributors gives the concrete MPNs of a part. find_parts finds new parts and replacements; adopt_part takes one.

The store identifies a document by its SHA-256: add_document of a file that it has copies nothing and gives the reference. Do not match a file to a document by its name only. Use add_document only for the documents of the parts. project_sync imports only the PDF files of the folder that the project file names. If the repository keeps its datasheets in a different folder, tell the user.

Find the content step by step:

  1. The document: project_status, list_documents(part), list_parts (the central store). A part can have a datasheet, a manual, errata and a package drawing.

  2. find_facts(part or document): the values that a session read before. Do this before you read a value.

  3. get_index: the outline and the table and figure captions, with pages. get_outline gives one section of a large document. list_items gives all tables and figures.

  4. search_text: a word, a register name or a value, with page and line.

  5. get_page_map: the elements of one page, with IDs and regions.

  6. get_page_image with an element ID, a caption (all pages of a table) or a region (300 to 600 dpi): read the values here.

  7. save_fact: save each value that the work uses, with its page and element.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}

Tools

Functions exposed to the LLM to take actions

NameDescription
list_partsA

The parts in the store, with their manufacturer and the number of their documents. Gives one line for each part: "MPN (manufacturer): N documents". A concrete part also gets the documents of its base part: "0 own documents, 1 of the base part AP63203". list_documents gives the documents of a part.

list_documentsA

The documents in the store, or the documents of one part (a concrete part also gets the documents of its base part). Gives one line for each document: its reference (12 characters, for the other tools), the number of pages, the file name, the role or the parts, and the title.

add_documentA

Add a PDF document to the store: copy or download it, build its index and its element map, and link it to its part. Use it when list_documents does not find the datasheet; the URL can come from a distributor tool or from the Datasheet field of a CAD symbol. The element map of a large document can take minutes: a background thread builds it, and the index and the page images are available at once. Gives the document reference, the pages, the size of the index and the state of the element map. Without part, it also gives a rough proposal of the MPN from the text of the PDF; it can be wrong. Read the MPN on page 1 of the original, then call add_document again with part. No tool removes a link of a document to a part in the store: give part only when the MPN is sure. The result gives the title of the document: the title of the PDF metadata can be wrong (a file name, a different document). No tool changes a title later: give title when you know it. The manufacturer of a datasheet comes from the datasheet: when the tool cannot read it, or the given name differs, the result asks (ASK THE USER) and links no part. To put the part into the user project: project_add_part.

get_indexA

The index of a document: the outline (bookmarks or numbered headings) with pages, and the table and figure captions with their page and position. A large document gives only the top outline levels: get_outline gives the entries under a section. Also the pages with no text layer or with images of a low resolution. Start here to find where the content is.

get_outlineA

The outline entries under one section of a document, with pages. Use it for a large document, when get_index gives only the top levels.

search_textA

Find a text in the text layer of one document, or of all documents of a part. Gives one line for each hit: the document reference, the page, the table or figure that holds the line (an element ID) or the region of the line, and the line. Give the element or the region to get_page_image: it costs less than a full page. The page headers and footers are not shown: a last line gives their number. Use it to find the page of a register, a parameter or a pin. Then read the value from the original (get_page_image): the text layer can be wrong.

get_page_mapA

The structure of one page: headings, tables, figures, formulas and captions. Gives one line for each element: its ID (for example p7.T1), its type, its region [x0, y0, x1, y1] in pt (origin at the top left of the page) and its text or caption. Use the IDs with get_element_text and get_page_image. The element map of a large new document can take minutes to build. Until it is complete, the result tells so: then use get_index, search_text and get_page_image with a page or a region.

get_element_textA

The full text of elements from the text layer, with their type, page and region. Use it for headings and paragraphs. Read table values, figures and formulas from get_page_image: the text layer can lose their structure. The text of a table or figure is only its caption. For a table, figure or formula, the result also gives the call of get_page_image for its image (with the caption label of a table, the call that gives each page of a table that continues on the next pages).

list_itemsA

The tables, figures and captions of the whole document. Gives one line for each item: element ID, page, region and caption. Use it to find a table or a figure when you do not know its page.

get_page_imageA

The original as a PNG image: an element, a caption, a region or a full page. Read the values from this image. An element, a caption or a region is rendered at 300 to 600 dpi when it fits max_px: prefer them, because a full page costs more input. A full page is correct for a table that fills the page. It is rendered at the resolution that fits max_px. A caption with no table or figure in the element map gives its full page. Gives a line with the page, the region, the dpi and the size, and the image.

get_pdf_pagesA

The original pages as a new PDF file. Use it when your client can read a PDF. Gives the file path and the PDF as an embedded resource.

save_factA

Save a value that you read from the original, with its source and your model ID, so that a later session finds it with find_facts. Before you read a value, look for it with find_facts: do not save a value two times. A new fact has the state unchecked. Gives the fact number.

find_factsA

Find values that were read before (save_fact). With part, it searches the documents of the part and of its base part: a concrete MPN also finds the facts of its datasheet. Gives one line for each fact: number, subject, value, the part (when the fact is for one part of a document of more parts), column, conditions, source (document, page, element or region), state and author. A fact is not the source of truth: check an important value against the original, then set its state with set_fact_status.

set_fact_statusB

Set the state of a saved fact after you compared it with the original. Gives the fact number and its new state.

project_statusB

The parts and documents of the user project, and the state of the copies in the project folder: missing or changed copies, new files, problems. It changes nothing. Gives one line for each part (MPN, manufacturer, base part) and one line for each document (reference, role, file). The first line of a datasheet of more parts gives these parts (variants); the next lines of the document do not. A first line can tell about a newer release or a necessary restart of the LLM client, or about the team server (a failed sync, a conflict): tell the user.

project_syncA

Synchronize the user project with the central store: add the documents that the store links to the project parts, copy the missing copies into the project folder, move the copies into the subfolders of the layout, and import the new PDF files of the folder. A new file gets a part only from the store; for a different file the result proposes a part, and project_add_part assigns it. The inbox (the folder _inbox in the folder of the copies) is for the PDF files that the user downloads: sync gives each one to the project parts that it agrees with (the MPN, the base part and the manufacturer of the datasheet) and that have no datasheet, and takes it from the inbox. For a file with no part, ask the user for the part, then assign it with project_add_part. Gives the changes and the problems.

project_add_partA

Add a part to the user project, with the documents that the store links to it. Then project_sync copies the documents into the project folder. A link of a document to the store part stays in the store (no tool removes it): check the MPN and the base part before you give document. A new part of the design: The CAD BOM is the master: write the change that the user confirmed into the CAD project too (MPN, MPN_Confirmed, Value_Confirmed, LCSC, Manufacturer, Distributor; kicad-workbench: set_symbol_fields), then project_check. The manufacturer of a datasheet comes from the datasheet: when the tool cannot read it, or the given name differs, the result asks (ASK THE USER) and adds nothing. Gives the part and its documents.

manufacturer_relationA

The manufacturer registry of the store: the names of each manufacturer, and the pairs that are two manufacturers. A part keeps the manufacturer name of its datasheet; the registry tells if two names are one manufacturer. When a tool reports that the registry does not know if two names are the same manufacturer, ask the user which relation is correct, then record it here and do the step again. Do not record a relation that the user did not confirm. Parts with the same MPN that become one manufacturer merge. Gives the merges, or the registry and the pairs of names that are probably one manufacturer (give them to the user to decide).

manufacturer_checkA

Check the manufacturer of each part of the store against its datasheet: the manufacturer of a part is the manufacturer of its datasheet, not the name of a distributor (older versions of adopt_part gave the name of the distributor). Gives the renames (the same manufacturer with the name of the datasheet), the parts whose datasheet gives a different manufacturer, and the parts whose datasheet names no manufacturer that the tool knows. Show the renames to the user, and apply them only when the user agrees. The changes go to the team server with the other changes of the store.

part_linksA

Search links for a part: datasheet, price and stock (DigiKey, Mouser, Farnell, LCSC, Octopart, Findchips), and symbol, footprint and 3D model (Component Search Engine, SnapMagic, Ultra Librarian). When DigiKey is in the global distributor list and has a key, also the direct links of DigiKey to the CAD models and the datasheets of the MPN. Use them when the store and the CAD project have no datasheet, and for the CAD files. datasheet-lens does not open these pages: open one with a web tool, or give the links to the user (a CAD site needs a free account for the download). A datasheet that you find: add_document with its URL. Gives one line for each link.

search_distributorsA

The orderable parts at the enabled distributors, from their official APIs, and in the JLCPCB parts library when it is on the machine (with the C number and the library class): the part number of the source (adopt_part takes it), lifecycle state, stock, prices and datasheet URL (Mouser gives no package: read it in the datasheet). An MPN of more manufacturers gives one line for each manufacturer. A part that is obsolete or discontinued is marked NOT ORDERABLE. Use it to select the concrete MPN of the BOM, and to check that it can be ordered. Each result names its source (the terms of the distributors ask for it). The enabled distributors come from the project file or the global configuration (distributor_status). Each needs a personal API key: for a distributor with no key, the result has a note with the steps for the user. Give the note to the user. With no key at all, the result gives the search links of part_links.

find_partsA

Find new parts or replacement parts by their parameters (a parametric search) at DigiKey (official API) or in the JLCPCB parts library (a local database for the JLCPCB assembly). Call part_parameters first to get the names and values of the parameters. Gives each filter with its status, and for each part: MPN, manufacturer, distributor number, state or library class, stock, price, the filtered parameters, datasheet and product URL. A numeric filter compares the first number of a value ("2.5V, 8V" gives 2.5 V). A distributor keeps one or few values of a parameter at its own conditions: read each value that the design needs in the datasheet (get_page_image) and save it with save_fact. When the user selects a candidate: adopt_part(source, number) adds its datasheet, the part and its purchase source (not add_document and project_add_part: they save no purchase source). When the source is not available, the error gives the steps for the user: give them to the user.

part_parametersA

The parameters of a part category at a source of the parametric search (DigiKey, or the JLCPCB parts library), for the filters of find_parts: the full name, the short name, the number of parts with a value, the number of values and examples of the values (jlcpcb: of the parts with JLCPCB stock). The parameters that most parts have come first: a parameter of few parts can be a parameter of a different part type in the same category. Use it before find_parts.

project_availabilityA

The lifecycle state and the stock of each part of the user project at the enabled distributors (official APIs) and in the JLCPCB parts library. Gives one verdict for each part from all sources:

  • A lifecycle risk of the manufacturer at any distributor (OBSOLETE, LAST TIME BUY, NOT FOR NEW DESIGNS), with the state of each distributor: select a replacement also when a source has stock.

  • A part with a purchase source ([[part.source]]): the offer of its number. "orderable at the purchase source", or a warning with the reasons (not checked, the number is not there or is an other MPN, not orderable, no stock) and the other sources with stock.

  • A part with no purchase source: "orderable" (the sources with stock), or no stock, not orderable, or no source has the MPN. A part with no warning gets one line with the details of each source. A part with a warning gets one indented line for each source. For a part with a lifecycle risk, no JLCPCB stock, or a loading fee (Extended), the lines "replacement" give parts of the JLCPCB library (the same MPN; resistors, capacitors, inductors with the same parameters), Basic and Preferred first: read the datasheet of a replacement before you propose it. To use a replacement: the user agrees, the CAD project changes, then project_update_part(mpn, new_mpn) and adopt_part. After the parts: the lines of the sources (parts with no purchase source, a source that does not answer, the age of the JLCPCB library). Tell the user about each warning, and give the user each note about a missing API key (see search_distributors). A part of not_fitted (DNP) gets "not fitted (DNP), information only": tell the user, it is no step for the production.

distributor_statusA

The distributors that datasheet-lens asks (from the project file, the global configuration or the default), if each has an API key (no key values), and the services of each distributor: which one has a parametric search, a package, direct links. Use it to select the distributor for a task. For a distributor with no key, a note with the steps for the user: give it to the user. The user changes the list with the CLI command "datasheet-lens dist NAME ..." (global) or "datasheet-lens dist --local NAME ..." (this project).

adopt_partA

Take a part that find_parts or search_distributors found: add its datasheet (one in the store, else a download: the site of the manufacturer first), add the part to the store and to the user project, and save the purchase source (the source and its part number; for JLCPCB the library class) in the store and in the project file. Use it when the user selects a candidate. The result gives the lifecycle state of the manufacturer from the distributors with a key: a WARNING (obsolete, last time buy, not for new designs) goes to the user, also when the source has stock. Then project_sync copies the datasheet into the project folder. The element map builds in the background. Read the values that the design needs in the datasheet and save them with save_fact. When no URL gives the datasheet (a login, a captcha), the result gives the URLs and the inbox folder of the project: give them to the user. A part with a new MPN becomes a new project part: to replace a project part (a replacement of project_availability), first the user agrees and the CAD project changes, then project_update_part(mpn, new_mpn), then adopt_part. The manufacturer of the part comes from its datasheet, not from the distributor: when the tool cannot read it, or the two names differ, the result asks (ASK THE USER) and adds nothing. A purchase source is added, not replaced: project_remove_source removes a wrong one. The CAD BOM is the master: write the change that the user confirmed into the CAD project too (MPN, MPN_Confirmed, Value_Confirmed, LCSC, Manufacturer, Distributor; kicad-workbench: set_symbol_fields), then project_check.

set_price_localeA

Set the country and the currency of the prices and the stock of DigiKey in the global configuration of the user, as the CLI command "datasheet-lens dist --site CZ --currency CZK". Mouser uses the country of the Mouser account, and JLCPCB gives USD. Give one of the two or the two. Change it only when the user asks.

jlcpcb_libraryB

The JLCPCB parts library on this machine: the local database of the parametric search with the source jlcpcb (JLCPCB stock for the assembly and library class). The update runs in the background: this tool answers at once, and status gives the progress. The old database stays until the new one is complete and checked. Tell the user the limits of the data that the result gives.

get_ordering_codesA

The orderable codes of a datasheet, from its text layer. Gives one line for each code: the code, its page and its line, which in an ordering table gives the package, the packing, the temperature and the state (ACTIVE, NRND ...). Use it to find the concrete orderable MPN for the BOM. A datasheet that gives only a scheme of its codes has no list: read its ordering information (get_page_image). A code of the datasheet is not always sold: check it with a distributor.

project_checkA

Compare the project file with the parts of the CAD project, so that the two hold the same parts. Each part with an MPN needs its datasheet, also an alternative in MPN. The convention: Value holds the general value ("2N7002", "100nF 10V"), the field MPN the MPNs ("2N7002LT1G, BSS138LT1G"), and the hidden fields Value_Confirmed and MPN_Confirmed the copies of the last confirmation. The confirmation of the user is the truth: until it, the confirmed MPNs are the parts. With bom, one line for each BOM file gives the columns that the tool read. Then the result gives these lines:

  • conflict: the fields or the columns of one symbol do not agree.

  • change in the CAD project: MPN is not MPN_Confirmed, or Value is not Value_Confirmed. Add the datasheet of a new MPN at once; tell the user; write the given fields only when the user confirms it.

  • not confirmed: the fields are not confirmed yet.

  • the old convention: the MPNs are in the parentheses of Value (or only of Value_Confirmed). Write the given fields (the move); the confirmed state and the parts do not change.

  • no field Value_Confirmed or MPN_Confirmed, no part selected (a general value and no MPN).

  • CAD lines with a part, the symbols that are not fitted (DNP: their parts stay parts of the project), the number of the same parts, and one line for each part that is different (one part with two MPNs), missing (with the documents of the store or the Datasheet field, and the next call) or extra.

  • project folder: the folder does not agree with the project file and the store (new references, missing copies, copies to move, files of the inbox to take): run project_sync; project_status gives the files.

  • project folder (a second line): the files that need a step of the user, because project_sync cannot do it (files of the folder or of the inbox with no part, changed copies, documents that the store does not have): tell the user.

  • next steps: when the two hold the same parts and no symbol needs a step of the user: project_sync (when the folder needs it), then project_availability. A JLCPCB (LCSC) finding of a symbol that is not fitted (DNP) is information for the user, not a step. A message of an other variant names it. A message names the fields to write by the columns of the BOM (the BOM must name its columns as the fields of the symbols: export_bom of kicad-workbench does), or by mpn_fields of the parts; when the field is not known, it names the choices and tells you to ask the user. In KiCad, write the fields with set_symbol_fields of the MCP server kicad-workbench. When the store is connected to a team server, it gets the rows of the server first: a datasheet that a different person added is not missing. In a project that uses JLCPCB (a JLCPCB purchase source, or an LCSC field), the lines "LCSC:" compare the JLCPCB number of each symbol (the LCSC column of the BOM, or lcsc of the parts) with the purchase source and with the JLCPCB parts library. The lines "Manufacturer:" and "Distributor:" compare the fields Manufacturer (the manufacturers of the MPNs of the field MPN, in their order) and Distributor (the preferred distributor of the fitted part) with the project: write the given fields, and ask the user where a line tells it. It changes nothing in the project.

project_update_partA

Change a part of the user project in place: its MPN, base part, category, manufacturer, preferred distributor, or a pinned document. A new manufacturer must agree with the datasheet of the part (as project_add_part). A file of the folder with the content of a document is a copy of sync when it is in the subfolder of the layout of its part, else it is pinned: project_sync tells it for each new reference, and pin_document or unpin_document changes it. The part keeps its place in datasheet-lens.toml and its copies (project_remove_part and project_add_part would delete and copy them again). Then project_sync moves a copy when the layout gives it a different subfolder. The CAD BOM is the master: write the change that the user confirmed into the CAD project too (MPN, MPN_Confirmed, Value_Confirmed, LCSC, Manufacturer, Distributor; kicad-workbench: set_symbol_fields), then project_check. Gives each changed field with its old and new value, then the part and its documents.

project_remove_partA

Remove a part from the user project, and delete its copies that no other part uses. A pinned file stays (see project_update_part), unless delete_pinned is true. The central store does not change, because other projects can use the part. To change the MPN of a part, use project_update_part. Gives the removed part and the deleted and kept files.

project_remove_sourceA

Remove a purchase source ([[part.source]]) from a part of the user project: a number that the project does not order (a different packaging) or a wrong number (project_check gives "one of them is wrong", project_availability gives "is X, not Y"). A part can have more numbers of one source; adopt_part adds one and does not replace the others. Do it only when the user agrees. The CAD BOM is the master: the LCSC field of the symbol must give a number that the part keeps (write it with kicad-workbench set_symbol_fields), then project_check.

project_remove_documentA

Remove a document from the parts of the user project; the parts stay. The project remembers it (exclude), so that project_sync does not add it again; project_add_part with this document adds it again. It also accepts a document that the project file does not name yet, but that project_sync would add (a "new reference" of project_status): use it to stop the sync of a document that the store links to a part. The copy is deleted when no part uses it; a pinned file stays. The central store does not change.

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

B3.4/5.0

Scored across 34 tools

Disambiguation3/5

The reading/indexing tools (get_index, get_outline, get_page_map, list_items, search_text) and project state tools (project_check, project_status, project_sync) are related enough to be confused, though the long descriptions help differentiate them. Distributor search tools (search_distributors, find_parts, part_parameters, part_links) also overlap in intent.

Naming Consistency4/5

All names use snake_case and most follow a predictable action_noun or domain-prefixed pattern. There are minor deviations with noun-only tools and mixed verbs such as get/list/search/find, but the set remains readable and predictable.

Tool Count2/5

With 34 tools spanning PDF indexing, project sync, distributor search, manufacturer registry, and saved facts, the surface is very large for one server. This exceeds the typical well-scoped range and likely warrants splitting or consolidation.

Completeness3/5

Project lifecycle coverage is strong, including add/update/remove/sync/check/status/availability. However, the central store lacks explicit remove, update, relink, or title-correction operations for documents and parts, creating notable lifecycle dead ends.

Maintenance

ActivityNo data
ResponsivenessOutdated data