Skip to content

MCP server crashes on startup: upload_assets.spec.ts is inside the xmcp tools path and loads as a tool #37337

Closed

Description

@fmontes

Problem Statement

@dotcms/mcp-server@0.1.0 was published on 2026-09-01 and crashed on startup for every user, before reading any configuration. It was unpublished within minutes, so real-world impact was nil — but the build defect is still on main and will recur on the next publish.

Root cause

xmcp.config.ts declares the tool directory:

paths: {
    tools: './src/tools',
    ...
}

xmcp loads every module in that directory as a tool, and there is no spec/test exclusion. This file lives there:

core-web/apps/mcp-server/src/tools/upload_assets.spec.ts

So the test file is bundled into the production artifact and executed as a tool at startup. describe is a Vitest global that does not exist at runtime:

ReferenceError: describe is not defined
    at 236 (/…/node_modules/@dotcms/mcp-server/269.js:1:11049)
    at a (/…/node_modules/@dotcms/mcp-server/stdio.js:194:2285)
    at async Promise.all (index 6)
    at async ld (/…/node_modules/@dotcms/mcp-server/stdio.js:194:776)

Promise.all (index 6) is the tool loader, and index 6 (0-based) of the alphabetical listing of src/tools/ is exactly upload_assets.spec.ts:

0 download_assets.ts   3 page_place_content.ts   6 upload_assets.spec.ts  ← 
1 execute.ts           4 page_verify.ts          7 upload_assets.ts
2 page_create.ts       5 search.ts

The published bundle carries the test source verbatim in chunk 269.js:

236(e,t,n){n.r(t);var r=n(825);describe("lenientBoolean",()=>{ … it.each([["false",!1] …

The other nine .spec.ts files in the app are under src/lib/ and are harmless — only this one sits inside the tools path.

Introduced in #36641.

Steps to Reproduce

Verified against the published 0.1.0 tarball (now unpublished). Because the tools glob and the file location are both unchanged on main, any new publish reproduces it.

From source:

  1. Build the app: npx nx build mcp-server (from core-web/)
  2. Send an MCP initialize to the built bundle over stdio:
    printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}' \
      | node dist/apps/mcp-server/stdio.js
  3. The process exits 1 with ReferenceError: describe is not defined and writes nothing to stdout.

Comparison across published versions, same stdin, confirming this is specific to the build and not the invocation:

Version Result
0.1.0 exit 1 — ReferenceError: describe is not defined
0.1.0-beta.4 exit 0 — correct initialize response
0.0.13 exit 1 — Error: DOTCMS_URL environment variable is required (correct behavior; no credentials were supplied)

Acceptance Criteria

  • src/tools/ contains no test files — move upload_assets.spec.ts alongside the other specs in src/lib/, or to a directory outside the tools path.
  • The xmcp tools glob excludes *.spec.ts / *.test.ts, so a colocated test can never again be loaded as a tool. (Moving the one file fixes today's break; this is what stops the next one.)
  • A CI smoke test starts the built artifact and asserts it answers initialize and tools/list over stdio. A crash-on-boot regression must fail the build, not the publish.
  • 0.1.1 published with the fix and the latest dist-tag moved to it.

dotCMS Version

@dotcms/mcp-server@0.1.0 (published 2026-09-01T23:04:51Z, since unpublished) and current main. Not present in 0.1.0-beta.4.

Additional context

latest currently resolves to 0.0.13, which starts correctly but exposes a completely different tool surface — content_action, content_save, content_search, content_type_create, content_type_list, context_initialization — with zero overlap against the 0.1.x tools. Anything pointing at @dotcms/mcp-server@latest today gets the old API.

Activity

  1. fmontes commented on Sep 1, 2026

    @fmontes
    MemberAuthor

    From-source repro confirmed — this is not an artifact of the npm publish pipeline.

    Running the locally built bundle at core-web/dist/apps/mcp-server/stdio.js, with credentials supplied so configuration cannot be the cause:

    DOTCMS_URL="https://demo.dotcms.com" AUTH_TOKEN="dummy" \
      node core-web/dist/apps/mcp-server/stdio.js < initialize.jsonl
    exit: 1
    ReferenceError: describe is not defined
    

    Identical failure to the published 0.1.0, nothing on stdout. So the defect is in the build as produced from main, and a CI smoke test on the built artifact (acceptance criterion 3) would catch it before a publish ever happens.

    Local workaround while the fix lands: move src/tools/upload_assets.spec.ts out of the tools directory and rebuild — that restores a working server for anyone who needs to develop against it now.

  2. github-actions commented on Sep 1, 2026

    @github-actions
    Contributor
  3. self-assigned this
    on Sep 2, 2026
  4. fmontes commented on Sep 2, 2026

    @fmontes
    MemberAuthor

    Blocks #37345 — the agent toolkit's plugin manifests pin @dotcms/mcp-server@latest, so dotCMS/agent-toolkit stays private until 0.1.1 publishes and the latest dist-tag moves. Right now latest resolves to 0.0.13, whose six tools share no names with the 0.1.x surface.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions