Published package omits `src/` but `dist/**/*.js.map` references it, breaking source-map consumers

[marc-wilson]

Describe the bug

The published @modelcontextprotocol/sdk npm tarball ships dist/**/*.js.map source maps whose sources field references ../../../../src/**/*.ts, but the src/ directory is not included in the published package. Any bundler that resolves source maps (e.g. webpack's source-map-loader) fails to read the referenced TypeScript files and emits a warning for every SDK file it touches.

Verified on @modelcontextprotocol/sdk@1.29.0.

To Reproduce

Steps to reproduce the behavior:

1. Install @modelcontextprotocol/sdk@1.29.0 in a project bundled with webpack and source-map-loader enabled (the default for @nx/webpack Node apps with sourceMap: true).
2. Import something from @modelcontextprotocol/sdk — e.g. anything that pulls in dist/cjs/experimental/tasks/helpers.js.
3. Run the build.

Inspecting the shipped map confirms the dangling reference:

// dist/cjs/experimental/tasks/helpers.js.map
{"version":3,"file":"helpers.js","sources":["../../../../src/experimental/tasks/helpers.ts"], ...}

The tarball contents:

package.json   // no "files" field
LICENSE
README.md
dist/          // shipped
src/           // NOT shipped

Every dist/**/*.js.map in the package has the same broken sources path, so any imported file can trigger this — the experimental tasks helpers happened to surface it for us.

Expected behavior

The shipped source maps resolve cleanly. Either the referenced src/ files are included in the tarball, or the sources are inlined into the maps (sourcesContent / --inlineSources), or the maps are not shipped at all.

Logs

WARNING in .../@modelcontextprotocol/sdk/dist/cjs/experimental/tasks/helpers.js
Module Warning (from .../source-map-loader/dist/cjs.js):
Failed to parse source map from '.../@modelcontextprotocol/sdk/src/experimental/tasks/helpers.ts'
file: Error: ENOENT: no such file or directory, open
'.../@modelcontextprotocol/sdk/src/experimental/tasks/helpers.ts'

WARNING in .../@modelcontextprotocol/sdk/dist/cjs/experimental/tasks/interfaces.js
Module Warning (from .../source-map-loader/dist/cjs.js):
Failed to parse source map from '.../@modelcontextprotocol/sdk/src/experimental/tasks/interfaces.ts'
file: Error: ENOENT: no such file or directory, open
'.../@modelcontextprotocol/sdk/src/experimental/tasks/interfaces.ts'

WARNING in .../@modelcontextprotocol/sdk/dist/cjs/experimental/tasks/mcp-server.js
Module Warning (from .../source-map-loader/dist/cjs.js):
Failed to parse source map from '.../@modelcontextprotocol/sdk/src/experimental/tasks/mcp-server.ts'
file: Error: ENOENT: no such file or directory, open
'.../@modelcontextprotocol/sdk/src/experimental/tasks/mcp-server.ts'

Additional context

Possible fixes (any one resolves it):

1. Add "src" to the files array in package.json so the referenced TypeScript sources ship alongside the maps.
2. Build with --inlineSources (or post-process the maps to populate sourcesContent) so consumers don't need src/ on disk — typically the cleanest option for a published library.
3. Strip the //# sourceMappingURL= comments and omit .js.map files if maps aren't intended for downstream consumption.

Happy to open a PR for whichever direction maintainers prefer.

[norika1207-lab]

This looks worth pinning down as a protocol-level regression rather than only an implementation bug.

For published package source maps reference omitted src, the acceptance test I would want is a minimal client/server fixture that records the exact JSON-RPC or HTTP exchange, then asserts both the wire result and the local lifecycle state after the failure path. In MCP deployments, the dangerous failures are often not just wrong return values; they are pending requests, dropped notifications, mismatched session state, or errors that get translated into a generic response and become impossible to diagnose.

A useful fix boundary would preserve three signals: the protocol error sent to the peer, the local exception or cancellation reason available to application code, and a trace/log field that ties the two together. That makes the behavior debuggable for agent hosts without requiring every host to special-case this SDK detail.

[rinaldofesta]

I could not open a PR against v1.x from my fork (PR creation on that branch appears to be restricted), but I have the fix ready on a branch (rinaldofesta:fix/v1x-sourcemap-sources, based on v1.x): set inlineSources: true in the base tsconfig.json so tsc embeds the TypeScript into each map's sourcesContent. After rebuilding, all 84 dist/esm/*.js.map carry sourcesContent and resolve without src/, and the files field stays ["dist"]. It matches what the 2.0 build already does.

Happy to do whatever is easiest on your side: cherry-pick the commit, or if you can open the PR from my branch I'll keep it current.

One open question: declarationMap is also on, so .d.ts.map still points at src/; inlineSources only covers the .js.map side. If you also want declaration maps to resolve, the choice is shipping src/ or turning off declarationMap.

[mcp-claude]

reproduced on v1.x @ 69749aa (1.29.0). files: ["dist"] + sourceMap: true/declarationMap: true without inlineSources means every shipped .js.map and .d.ts.map has sources: ["../../../../src/**/*.ts"] with empty sourcesContent, and the referenced .ts files are absent from the tarball. main (v2) is on tsdown and embeds sourcesContent, so this is v1.x-only.

setting inlineSources: true in tsconfig.json fixes .js.map (source-map-loader stops warning) but not .d.ts.map — TypeScript's inlineSources doesn't apply to declaration maps. if .d.ts.map resolution matters (editor "go to definition" for types), the options are to also ship src/ or drop declarationMap. the reporter's proposed inlineSources-only fix addresses the webpack warning described here.

repro script (`repro.ts`)

// Repro for issue #2233: published tarball ships dist source maps whose
// `sources` field references ../../../../src/**/*.ts, but src/ is not shipped.
//
// 1. Build the SDK (npm run build).
// 2. Read a shipped .js.map and confirm `sources` point at src/*.ts.
// 3. Confirm `sourcesContent` is not populated.
// 4. Simulate `npm pack --dry-run --json` and confirm src/ is absent while
//    .js.map files are shipped.
// 5. Follow the sources[0] relative path from the shipped map location and
//    confirm the source .ts file would not resolve inside the tarball.
import { execSync } from "node:child_process";
import { readFileSync, existsSync } from "node:fs";
import { dirname, join, resolve } from "node:path";

const repo = resolve(process.cwd());
const mapFile = join(repo, "dist/cjs/experimental/tasks/helpers.js.map");
if (!existsSync(mapFile)) {
    throw new Error(`build first — missing ${mapFile}`);
}

const map = JSON.parse(readFileSync(mapFile, "utf8"));
console.log("map.sources        =", map.sources);
console.log("has sourcesContent =", Array.isArray(map.sourcesContent) && map.sourcesContent.some((c: unknown) => typeof c === "string"));

const referenced = resolve(dirname(mapFile), map.sources[0]);
console.log("resolved reference =", referenced.replace(repo, "<repo>"));
console.log("referenced file exists on disk (in checkout, not in tarball) =", existsSync(referenced));

const packJson = JSON.parse(
    execSync("npm pack --dry-run --json", { cwd: repo }).toString()
);
const files: string[] = packJson[0].files.map((f: { path: string }) => f.path);
const srcFiles = files.filter(f => f.startsWith("src/"));
const mapFilesInTarball = files.filter(f => f.endsWith(".js.map"));
console.log("src/*.ts entries in tarball =", srcFiles.length);
console.log(".js.map entries in tarball  =", mapFilesInTarball.length);

const tarballHasReferenced = files.includes(map.sources[0].replace(/^(\.\.\/)+/, ""));
console.log("sources[0] resolvable inside tarball =", tarballHasReferenced);

run + output

$ git checkout v1.x
$ npm ci && npm run build
$ npx tsx repro.ts
map.sources        = [ '../../../../src/experimental/tasks/helpers.ts' ]
has sourcesContent = false
resolved reference = <repo>/src/experimental/tasks/helpers.ts
referenced file exists on disk (in checkout, not in tarball) = true

> @modelcontextprotocol/sdk@1.29.0 prepack
> npm run build:esm && npm run build:cjs
...
src/*.ts entries in tarball = 0
.js.map entries in tarball  = 170
sources[0] resolvable inside tarball = false

.d.ts.map has the same relative sources reference, so the identical breakage applies to declaration maps.

code path

• package.json → "files": ["dist"] — src/ excluded from tarball.
• tsconfig.json → "sourceMap": true, "declarationMap": true", no inlineSources.
• tsconfig.prod.json / tsconfig.cjs.json extend tsconfig.json and set outDir: "./dist/esm" / ./dist/cjs"; the src→out depth is 4, hence ../../../../src/... in every emitted map.
• tsc emits sources relative + no sourcesContent; publisher ships the maps without the referenced files.

not pushing a patch from here: the only viable fix is "inlineSources": true in tsconfig.json (or equivalently, sourceRoot/shipping src/), which is a build-config change and verifying it requires running tsc and inspecting emitted .js.map files — build-integration territory rather than a unit test. leaving the change to a maintainer who can pair it with a .d.ts.map decision (accept the residual declaration-map warning, ship src/, or drop declarationMap).

[rinaldofesta]

Re-verified against the current v1.x tip (69749aa5, the same sha as the repro above): rinaldofesta:fix/v1x-sourcemap-sources (8bfe5de7) cherry-picks clean, and after npm ci && npm run build 170/170 .js.map carry sourcesContent. 0/170 .d.ts.map do, as expected: tsc has no inlineSources equivalent for declaration maps (microsoft/TypeScript#38966 is the open feature request), so a tsconfig-only fix can't reach them.

The breakage reported here (source-map-loader/webpack) is all on .js.map, so the branch fixes it as-is and leaves declaration maps exactly as they are today. If you want .d.ts.map resolution handled too, I can extend the branch to drop declarationMap on v1.x or to ship src/, whichever you prefer. PR creation against v1.x is still blocked from forks, so it needs a cherry-pick or a maintainer-opened PR.