diff --git a/docs/api/mcp.md b/docs/api/mcp.md new file mode 100644 index 00000000..66cea4c2 --- /dev/null +++ b/docs/api/mcp.md @@ -0,0 +1,216 @@ +--- +title: MCP Server +layout: default +parent: API +nav_order: 3 +--- + +# MCP Server + +{: .new } +> This feature was added recently and might still change in future versions. + +Part-DB ships a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server, which allows AI assistants and +agents (like Claude, ChatGPT, or AI-powered coding tools) to directly interact with your Part-DB inventory: they can +search for parts, look up categories, footprints, manufacturers, storage locations, suppliers, and projects, and even +query external info providers like Digikey, Mouser or LCSC, all using natural language, without you having to write +any code against the [REST API]({% link api/intro.md %}). + +MCP is a standardized, widely supported protocol, so once your Part-DB MCP endpoint is set up, you can connect it to +many different AI clients and applications. + +{: .warning } +> The MCP integration is currently **read-only**: an AI assistant can look up data, but it can not create, change or +> delete anything in your Part-DB instance via MCP. +> Still, giving an AI assistant access to your inventory means it can read everything the connected user account is +> allowed to see, so only connect trusted AI clients and keep your API token secret, just like you would for the +> [REST API]({% link api/authentication.md %}). + +## Enabling the MCP server + +The MCP server is disabled by default and has to be enabled by an administrator first: + +1. Open the system settings and go to the **AI** tab. +2. In the **MCP (Model Context Protocol) Server** section, enable the **Enable MCP endpoint** checkbox. + +This can also be controlled via the `MCP_ENABLED` environment variable. + +Once enabled, the MCP server is reachable under the `/mcp` path of your Part-DB instance (e.g. +`https://your-part-db.local/mcp`). Unlike most other Part-DB pages, this path is **not** locale-prefixed (so it is +`/mcp`, not `/en/mcp`). + +## Permissions + +Users which should be allowed to use the MCP tools additionally need the **Use MCP tools (for AI agents)** permission +(under the **API** permission group). Granting it automatically also grants the base **Access API** permission. + +Like the REST API, authentication against the MCP endpoint is done using an [API token]({% link +api/authentication.md %}). A token with the **Read-Only** scope is enough to use all currently available MCP tools, +as they only read data. + +## Connecting an AI client + +To connect an AI client to Part-DB, you need two things: + +* The **MCP endpoint URL**, e.g. `https://your-part-db.local/mcp`. Once you have the required permission, you can + also find it on the **API** panel of your user settings page, under "MCP endpoint", together with a + copy-to-clipboard button. +* An **API token**. Create one on the same **API** panel of your user settings page (see + [Authentication]({% link api/authentication.md %}) for details about tokens and scopes). A token with the + **Read-Only** scope is sufficient. + +The client has to send this token as a bearer token in the `Authorization` header of every request: +`Authorization: Bearer tcp_`. How exactly you configure this depends on the AI client you use; some +examples for common clients are shown below. + +{: .note } +> Part-DB's MCP server only supports the **Streamable HTTP** transport (no stdio, no plain SSE). Most modern MCP +> clients support this transport directly. Clients that only support local, stdio-based MCP servers can be bridged to +> a remote HTTP server with a small proxy tool like [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), as shown +> in the Claude Desktop example below. + +MCP client configuration formats change frequently, so if the examples below don't quite match what you see in your +client, check the client's own documentation for how to add a remote MCP server with a custom `Authorization` header. + +### Claude Code + +Add the server with the Claude Code CLI: + +```bash +claude mcp add part-db https://your-part-db.local/mcp \ + --transport http \ + --header "Authorization: Bearer tcp_" +``` + +### Claude Desktop + +Claude Desktop currently only launches local (stdio) MCP servers directly from its config file, so a remote server +like Part-DB's has to be bridged with the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) proxy. Open +Claude Desktop's configuration file (**Settings → Developer → Edit Config**) and add: + +```json +{ + "mcpServers": { + "part-db": { + "command": "npx", + "args": [ + "-y", + "mcp-remote", + "https://your-part-db.local/mcp", + "--header", + "Authorization: Bearer tcp_" + ] + } + } +} +``` + + +### Google Antigravity + +Open **Manage MCP Servers** and add the server via its JSON configuration: + +```json +{ + "mcpServers": { + "part-db": { + "serverUrl": "https://your-part-db.local/mcp", + "headers": { + "Authorization": "Bearer tcp_" + } + } + } +} +``` + +### Cursor + +Add the following to your `.cursor/mcp.json` (project-specific) or global Cursor MCP settings: + +```json +{ + "mcpServers": { + "part-db": { + "url": "https://your-part-db.local/mcp", + "headers": { + "Authorization": "Bearer tcp_" + } + } + } +} +``` + +### VS Code (MCP support / GitHub Copilot) + +Add the following to your `.vscode/mcp.json` (or use the **MCP: Add Server** command from the command palette): + +```json +{ + "servers": { + "part-db": { + "type": "http", + "url": "https://your-part-db.local/mcp", + "headers": { + "Authorization": "Bearer tcp_" + } + } + } +} +``` + +### Other clients + +Any MCP client that supports the Streamable HTTP transport with custom headers can connect to Part-DB, you generally +just need to provide: + +* **URL**: `https://your-part-db.local/mcp` +* **Transport**: Streamable HTTP +* **Header**: `Authorization: Bearer tcp_` + +## Available tools + +The following MCP tools are currently available. All of them are read-only. + +### Parts + +* **search_parts** – Search for parts by a keyword, with toggles to control which fields are searched (name, + description, comment, tags, storage location, supplier order number, MPN, IPN, supplier, manufacturer, footprint, + category, database ID), and an optional regex mode. +* **get_part_details** – Get full details about a specific part by its database ID, including stock, prices, + order details, attachments, parameters and EDA info. + +### Master data + +Categories, footprints, manufacturers, storage locations, measurement units, suppliers and part custom states all +expose the same pair of tools: + +* **list_categories** / **get_category_details** +* **list_footprints** / **get_footprint_details** +* **list_manufacturers** / **get_manufacturer_details** +* **list_storage_locations** / **get_storage_location_details** +* **list_measurement_units** / **get_measurement_unit_details** +* **list_suppliers** / **get_supplier_details** +* **list_part_custom_states** / **get_part_custom_state_details** + +Each `list_*` tool accepts an optional `keyword`, matched against the name and comment. Without a keyword, all +elements are returned in hierarchical tree order; with a keyword, matching results are sorted by their full path, so +parent/child relationships can still be derived from the flat list. Each `get_*_details` tool takes the element's +database `id` and returns its full details. + +### Projects + +* **list_projects** / **get_project_details** – Same behavior as the master data tools above. + `get_project_details` additionally returns the project's BOM entries, status, description and associated build + part. + +### Info Provider System + +These tools query external part information providers (e.g. Digikey, Mouser, LCSC), see the +[Information provider system]({% link usage/information_provider_system.md %}) page for background: + +* **list_info_providers** – List the info providers that are currently active and can be used with the two tools + below. +* **search_info_providers** – Search one or more external info providers (or the configured default providers, if + none are specified) for parts matching a keyword. +* **get_info_provider_part_details** – Get full details (datasheets, images, parameters, prices, ...) for a specific + search result, identified by the `provider_key` and `provider_id` returned by `search_info_providers`.