chore: add smithery.yaml for Smithery distribution by jdrhyne · Pull Request #9 · PSPDFKit/nutrient-document-engine-mcp-server

jdrhyne · 2026-02-27T20:13:48Z

Summary

add smithery.yaml so the server can be listed/distributed via Smithery
define required config (documentEngineBaseUrl, documentEngineApiAuthToken)
expose optional dashboard credentials in config schema

Why

This improves discoverability and one-command install ergonomics for MCP clients that support Smithery manifests.

Copilot

Pull request overview

Adds a Smithery manifest so this MCP server can be distributed/listed via Smithery, exposing required Document Engine connection settings and optional dashboard credentials.

Changes:

Introduce smithery.yaml with a startCommand definition for npx @nutrient-sdk/document-engine-mcp-server
Define Smithery configSchema for Document Engine base URL + API token, plus optional dashboard username/password
Map Smithery config values to the server’s expected environment variables

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-02T19:17:47Z

smithery.yaml

+        description: Optional dashboard username.
+      dashboardPassword:
+        type: string
+        description: Optional dashboard password.


The config schema allows setting only dashboardUsername or only dashboardPassword, but the server enables the dashboard only when both env vars are provided. Adding a schema constraint (e.g., anyOf requiring both fields together, or dependentRequired) would prevent confusing partial configs.

Suggested change

description: Optional dashboard password.

description: Optional dashboard password.

dependentRequired:

dashboardUsername:

- dashboardPassword

dashboardPassword:

- dashboardUsername

smithery.yaml

Copilot · 2026-03-02T19:17:47Z

smithery.yaml

+        description: Base URL for the Nutrient Document Engine instance.
+      documentEngineApiAuthToken:
+        type: string
+        default: secret


documentEngineApiAuthToken is marked as required, but the schema also provides a default of secret. This means Smithery clients may not prompt users for a real token and will run with the well-known default, which is risky outside local dev. Consider removing the default (keep it required) or changing the default to an empty value so users must supply a token explicitly.

Suggested change

default: secret

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-02T19:25:59Z

smithery.yaml

      args: ['/app/dist/index.js'],
      env: {
        DOCUMENT_ENGINE_BASE_URL: config.documentEngineBaseUrl,
        DOCUMENT_ENGINE_API_AUTH_TOKEN: config.documentEngineApiAuthToken,
        DOCUMENT_ENGINE_API_BASE_URL: config.documentEngineApiBaseUrl,


documentEngineApiBaseUrl is exposed in the Smithery config and mapped to DOCUMENT_ENGINE_API_BASE_URL, but the server code doesn’t appear to read DOCUMENT_ENGINE_API_BASE_URL anywhere (no references under src/). As a result, this config knob currently has no effect; either wire this env var into the Document Engine client configuration or remove it from the Smithery schema/env mapping to avoid misleading users.

Copilot · 2026-03-02T19:26:00Z

smithery.yaml

        DOCUMENT_ENGINE_BASE_URL: config.documentEngineBaseUrl,
        DOCUMENT_ENGINE_API_AUTH_TOKEN: config.documentEngineApiAuthToken,
        DOCUMENT_ENGINE_API_BASE_URL: config.documentEngineApiBaseUrl,


mcpServerUrl is mapped into the container as MCP_SERVER_URL, but the MCP server implementation under src/ doesn’t reference MCP_SERVER_URL (it configures transport/host/port via MCP_TRANSPORT, MCP_HOST, PORT). Unless Smithery uses this env var externally, this setting won’t affect the server and may confuse users; consider removing it from the manifest or updating it to match actual server configuration.

Copilot · 2026-03-02T19:26:00Z

smithery.yaml

+        description: Optional dashboard username
+      dashboardPassword:
+        type: string
+        description: Optional dashboard password


The schema describes dashboardUsername/dashboardPassword as independently optional, but the server only enables the dashboard when both DASHBOARD_USERNAME and DASHBOARD_PASSWORD are set. Update the descriptions (or the schema constraints, if supported) to make it explicit that both values must be provided together to enable the dashboard.

Suggested change

description: Optional dashboard username

dashboardPassword:

type: string

description: Optional dashboard password

description: Optional dashboard username; must be provided together with dashboardPassword to enable the dashboard

dashboardPassword:

type: string

description: Optional dashboard password; must be provided together with dashboardUsername to enable the dashboard

nickwinder

Found 3 issues. See inline comments below.

nickwinder · 2026-03-02T19:51:04Z

smithery.yaml

      documentEngineBaseUrl:
        type: string
+        format: uri
+        pattern: '^https?://'


These two constraints are redundant and may behave inconsistently relative to the server's authoritative Zod .url() check in src/utils/Environment.ts:7-9.

format: uri is advisory and not strictly enforced by all validators. pattern: '^https?://' actively blocks schemes that Zod's .url() might accept (e.g. custom proxy schemes). The documented example http://localhost:5000 should pass both, but having a secondary schema-level gate that may diverge from runtime validation adds confusion without adding safety. Consider removing the format and pattern constraints and relying solely on the server's own validation.

nickwinder · 2026-03-02T19:51:16Z

smithery.yaml

+        description: Optional dashboard username
+      dashboardPassword:
+        type: string
+        description: Optional dashboard password


dashboardPassword is a credential but is declared as a plain type: string with no sensitivity annotation. JSON Schema supports "writeOnly": true to signal to UI tooling that the value should be masked rather than displayed in plaintext.

dashboardPassword: type: string writeOnly: true description: Optional dashboard password

Note: the pre-existing documentEngineApiAuthToken field has the same gap — worth fixing there too.

nickwinder · 2026-03-02T19:51:27Z

smithery.yaml

+        ...(config.dashboardUsername ? { DASHBOARD_USERNAME: config.dashboardUsername } : {}),
+        ...(config.dashboardPassword ? { DASHBOARD_PASSWORD: config.dashboardPassword } : {})


These independent truthy checks allow a user to supply only one of the two credentials. That will silently inject a partial env var — the dashboard will not activate (since src/index.ts requires both: !!(env.DASHBOARD_USERNAME && env.DASHBOARD_PASSWORD)), but there is no startup error to tell the user why.

A single combined conditional enforces the "both or neither" contract the server already expects:

...(config.dashboardUsername && config.dashboardPassword ? { DASHBOARD_USERNAME: config.dashboardUsername, DASHBOARD_PASSWORD: config.dashboardPassword } : {})

See the runtime contract at src/index.ts:171 and src/dashboard/routes.ts:23-26.

jdrhyne · 2026-03-02T19:54:47Z

Addressed the latest review feedback in 5246a19:

removed extra URL schema constraints from documentEngineBaseUrl (rely on runtime validation)
marked credential fields as writeOnly in schema (documentEngineApiAuthToken, dashboardPassword)
enforced dashboard credentials as both-or-neither:
- dependentRequired in configSchema
- combined conditional env mapping so partial creds are not injected

Please take another look when you have a minute.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

smithery.yaml:23

documentEngineApiBaseUrl is exposed in the Smithery config schema, but the server codebase does not read any DOCUMENT_ENGINE_API_BASE_URL environment variable (no references found under src/). As a result, this config option appears to be a no-op for the distributed server; consider removing it from the schema/env mapping, or adding corresponding support in src/utils/Environment.ts + ClientFactory if it’s intended to work.

      documentEngineApiBaseUrl:
        type: string
        description: Optional override for API base URL

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-02T20:47:27Z

smithery.yaml

      mcpServerUrl:
        type: string
        description: Optional MCP callback/server URL


mcpServerUrl is described as an MCP server/callback URL, but the MCP server implementation doesn’t consume an MCP_SERVER_URL env var (no references under src/); this looks like a client-side variable used only in the examples/ directory. Including it here may confuse users configuring the server; consider dropping it from the manifest or renaming/repurposing it to match the server’s actual HTTP settings (MCP_TRANSPORT, MCP_HOST, PORT).

Copilot · 2026-03-02T20:47:27Z

smithery.yaml

        DOCUMENT_ENGINE_API_AUTH_TOKEN: config.documentEngineApiAuthToken,
        DOCUMENT_ENGINE_API_BASE_URL: config.documentEngineApiBaseUrl,
-        MCP_SERVER_URL: config.mcpServerUrl
+        MCP_SERVER_URL: config.mcpServerUrl,


The env object includes optional keys (DOCUMENT_ENGINE_API_BASE_URL, MCP_SERVER_URL) whose values will be undefined when the corresponding config fields are omitted. Many process runners expect env values to be strings; consider conditionally adding these keys only when a value is provided (like the dashboard credential spread), or providing explicit defaults.

jdrhyne requested a review from Copilot March 2, 2026 19:15

Copilot started reviewing on behalf of jdrhyne March 2, 2026 19:16 View session

Copilot AI reviewed Mar 2, 2026

View reviewed changes

chore: add smithery.yaml for Smithery distribution

bb75062

jdrhyne force-pushed the chore/add-smithery-yaml branch from 16b404d to bb75062 Compare March 2, 2026 19:19

jdrhyne requested a review from Copilot March 2, 2026 19:23

Copilot started reviewing on behalf of jdrhyne March 2, 2026 19:23 View session

Apply suggestion from @Copilot

167c81c

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI reviewed Mar 2, 2026

View reviewed changes

nickwinder reviewed Mar 2, 2026

View reviewed changes

chore: address smithery review feedback

5246a19

jdrhyne requested review from Copilot and nickwinder March 2, 2026 20:44

Copilot started reviewing on behalf of jdrhyne March 2, 2026 20:44 View session

Copilot AI reviewed Mar 2, 2026

View reviewed changes

		...(config.dashboardUsername ? { DASHBOARD_USERNAME: config.dashboardUsername } : {}),
		...(config.dashboardPassword ? { DASHBOARD_PASSWORD: config.dashboardPassword } : {})

Conversation

jdrhyne commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

nickwinder left a comment

Choose a reason for hiding this comment

Uh oh!

nickwinder Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

nickwinder Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

nickwinder Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

jdrhyne commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jdrhyne commented Feb 27, 2026 •

edited

Loading

jdrhyne commented Mar 2, 2026 •

edited

Loading