From a2383c14f79f12739241a93598a9a22c386a059e Mon Sep 17 00:00:00 2001 From: Matthew Podwysocki Date: Wed, 21 Oct 2026 19:13:37 -0400 Subject: [PATCH 1/2] fix: CommonJS build fails on import.meta in versionUtils Adds versionUtils-cjs.cts, which tshy uses for dist/commonjs in place of versionUtils.ts, reading version.json from __dirname. Same approach as mcp-server. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 1 + src/utils/versionUtils-cjs.cts | 35 ++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 src/utils/versionUtils-cjs.cts diff --git a/CHANGELOG.md b/CHANGELOG.md index 3f9c55e..ac2e823 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,6 @@ ## Unreleased +- fix: the CommonJS build works again. `require('@mapbox/mcp-docs-server/tools')` (and `/resources`, `/utils`) threw "Cannot use 'import.meta' outside a module", since `src/utils/versionUtils.ts` uses `import.meta.url` and tshy compiled it into `dist/commonjs` as is. There's now a `versionUtils-cjs.cts` that tshy uses for the CommonJS build instead, reading `version.json` from `__dirname`, same as mcp-server does. ESM was never affected, and hosted-mcp-server uses ESM. (#PR) - docs: fix two stale tool descriptions left over from the Algolia-to-`llms.txt` search migration. `search_mapbox_docs_tool`'s README entry still said it used "Algolia full-text search" — that was removed a while back (see the "Replace Algolia search with self-contained llms.txt search" entry below) and it now searches the self-hosted `llms.txt` index. Separately, `get_document_tool`'s own description (the text shown to the LLM, not just docs) referenced a tool named `get_latest_mapbox_docs_tool`, which doesn't exist — it should have said `search_mapbox_docs_tool`, and was actively misdirecting tool-chaining behavior. - fix: startup/shutdown/error logging messages now actually reach clients. The `McpServer` never declared the `logging` capability, so every `sendLoggingMessage` call (including the existing "server started"/"shutting down"/"Fatal error" messages) was a silent no-op regardless of when it was sent. Declared `logging: {}` in the server's capabilities. - feat: the server now identifies which MCP client connected to it. `server.server.getClientVersion()` (populated from the `clientInfo` sent in the client's `initialize` request) is now logged on connect, e.g. `Client identified as: claude-ai v1.0.0`. Reading it required moving the read to a `server.server.oninitialized` callback rather than right after `server.connect()`, since `getClientVersion()` is only populated once the client's `initialize` request has actually been processed, which is not guaranteed by the time `connect()`'s promise resolves. Also recorded as `mcp.client.name`/`mcp.client.version` on every subsequent tool-execution trace span (`withToolSpan`), so OTel-backed traces can be filtered or grouped by client. Matches the equivalent changes landing in `@mapbox/mcp-server` and `@mapbox/mcp-devkit-server`. diff --git a/src/utils/versionUtils-cjs.cts b/src/utils/versionUtils-cjs.cts new file mode 100644 index 0000000..77a149e --- /dev/null +++ b/src/utils/versionUtils-cjs.cts @@ -0,0 +1,35 @@ +// Copyright (c) Mapbox, Inc. +// Licensed under the MIT License. + +// CommonJS build of versionUtils.ts. tshy uses this file in place of +// versionUtils.ts for dist/commonjs, since import.meta doesn't exist there. + +import { readFileSync } from 'node:fs'; +import path from 'node:path'; + +export interface VersionInfo { + name: string; + version: string; + sha: string; + tag: string; + branch: string; +} + +export function getVersionInfo(): VersionInfo { + const name = 'Mapbox Documentation MCP Server'; + try { + const filePath = path.resolve(__dirname, '..', 'version.json'); + const data = readFileSync(filePath, 'utf-8'); + const info = JSON.parse(data) as VersionInfo; + info.name = name; + return info; + } catch { + return { + name: name, + version: '0.0.0', + sha: 'unknown', + tag: 'unknown', + branch: 'unknown' + }; + } +} From 5062c441c76894acd83568b933ea79e806bddca1 Mon Sep 17 00:00:00 2001 From: Matthew Podwysocki Date: Wed, 21 Oct 2026 19:13:56 -0400 Subject: [PATCH 2/2] docs: add PR number to CHANGELOG Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ac2e823..643f7ce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ ## Unreleased -- fix: the CommonJS build works again. `require('@mapbox/mcp-docs-server/tools')` (and `/resources`, `/utils`) threw "Cannot use 'import.meta' outside a module", since `src/utils/versionUtils.ts` uses `import.meta.url` and tshy compiled it into `dist/commonjs` as is. There's now a `versionUtils-cjs.cts` that tshy uses for the CommonJS build instead, reading `version.json` from `__dirname`, same as mcp-server does. ESM was never affected, and hosted-mcp-server uses ESM. (#PR) +- fix: the CommonJS build works again. `require('@mapbox/mcp-docs-server/tools')` (and `/resources`, `/utils`) threw "Cannot use 'import.meta' outside a module", since `src/utils/versionUtils.ts` uses `import.meta.url` and tshy compiled it into `dist/commonjs` as is. There's now a `versionUtils-cjs.cts` that tshy uses for the CommonJS build instead, reading `version.json` from `__dirname`, same as mcp-server does. ESM was never affected, and hosted-mcp-server uses ESM. (#47) - docs: fix two stale tool descriptions left over from the Algolia-to-`llms.txt` search migration. `search_mapbox_docs_tool`'s README entry still said it used "Algolia full-text search" — that was removed a while back (see the "Replace Algolia search with self-contained llms.txt search" entry below) and it now searches the self-hosted `llms.txt` index. Separately, `get_document_tool`'s own description (the text shown to the LLM, not just docs) referenced a tool named `get_latest_mapbox_docs_tool`, which doesn't exist — it should have said `search_mapbox_docs_tool`, and was actively misdirecting tool-chaining behavior. - fix: startup/shutdown/error logging messages now actually reach clients. The `McpServer` never declared the `logging` capability, so every `sendLoggingMessage` call (including the existing "server started"/"shutting down"/"Fatal error" messages) was a silent no-op regardless of when it was sent. Declared `logging: {}` in the server's capabilities. - feat: the server now identifies which MCP client connected to it. `server.server.getClientVersion()` (populated from the `clientInfo` sent in the client's `initialize` request) is now logged on connect, e.g. `Client identified as: claude-ai v1.0.0`. Reading it required moving the read to a `server.server.oninitialized` callback rather than right after `server.connect()`, since `getClientVersion()` is only populated once the client's `initialize` request has actually been processed, which is not guaranteed by the time `connect()`'s promise resolves. Also recorded as `mcp.client.name`/`mcp.client.version` on every subsequent tool-execution trace span (`withToolSpan`), so OTel-backed traces can be filtered or grouped by client. Matches the equivalent changes landing in `@mapbox/mcp-server` and `@mapbox/mcp-devkit-server`.