@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/parsing/frontmatterParser.js

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Provides a utility class for extracting and parsing YAML frontmatter from markdown.
+ * Supports Obsidian-style and Jekyll-style frontmatter (YAML between --- delimiters).
+ * Leverages the existing yamlParser for parsing extracted YAML content.
+ * @module src/utils/parsing/frontmatterParser
+ */
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+import { logger } from '../../utils/internal/logger.js';
+import { requestContextService } from '../../utils/internal/requestContext.js';
+import { yamlParser } from './yamlParser.js';
+/**
+ * Regular expression to extract frontmatter from markdown.
+ * Matches YAML content between --- delimiters at the start of the document.
+ * - Group 1: YAML content between delimiters
+ * - Group 2: Remaining markdown content
+ * @private
+ */
+const frontmatterRegex = /^---\s*\n([\s\S]*?)^---\s*([\s\S]*)$/m;
+/**
+ * Utility class for extracting and parsing YAML frontmatter from markdown documents.
+ * Supports Obsidian-style and Jekyll-style frontmatter (YAML between `---` delimiters).
+ * Delegates YAML parsing to {@link yamlParser}.
+ */
+export class FrontmatterParser {
+    /**
+     * Extracts and parses YAML frontmatter from a markdown string.
+     *
+     * Looks for a `---`-delimited block at the very start of the document. If
+     * found, the YAML inside is parsed via {@link yamlParser} and the remaining
+     * markdown is returned separately. An empty `---\n---` block is accepted and
+     * returns `frontmatter: {}` with `hasFrontmatter: true`. If no frontmatter
+     * block is present, the original string is returned unchanged.
+     *
+     * @template T - The expected shape of the parsed frontmatter object. Defaults to `unknown`.
+     * @param markdown - The markdown string that may contain a frontmatter block.
+     * @param context - Optional {@link RequestContext} used for correlated logging.
+     * @returns A {@link FrontmatterResult} with `frontmatter`, `content`, and `hasFrontmatter`.
+     * @throws {McpError} With code `ValidationError` if the YAML content is present but malformed.
+     * @example
+     * ```typescript
+     * import { frontmatterParser } from './frontmatterParser.js';
+     *
+     * const md = `---\ntitle: Hello\ntags: [a, b]\n---\n\n# Body`;
+     * const result = await frontmatterParser.parse<{ title: string; tags: string[] }>(md);
+     * // result.frontmatter → { title: 'Hello', tags: ['a', 'b'] }
+     * // result.content     → '\n# Body'
+     * // result.hasFrontmatter → true
+     * ```
+     */
+    async parse(markdown, context) {
+        const match = markdown.match(frontmatterRegex);
+        if (!match) {
+            // No frontmatter found - return original content
+            const logContext = context ||
+                requestContextService.createRequestContext({
+                    operation: 'FrontmatterParser.noFrontmatter',
+                });
+            logger.debug('No frontmatter detected in markdown.', logContext);
+            return {
+                frontmatter: {},
+                content: markdown,
+                hasFrontmatter: false,
+            };
+        }
+        const yamlContent = match[1] ?? '';
+        const markdownContent = match[2] ?? '';
+        const logContext = context ||
+            requestContextService.createRequestContext({
+                operation: 'FrontmatterParser.parse',
+            });
+        logger.debug('Frontmatter detected, extracting and parsing.', {
+            ...logContext,
+            yamlLength: yamlContent.length,
+            contentLength: markdownContent.length,
+        });
+        // Validate that we have YAML content
+        const trimmedYaml = yamlContent.trim();
+        if (!trimmedYaml) {
+            logger.debug('Empty frontmatter block detected.', logContext);
+            return {
+                frontmatter: {},
+                content: markdownContent,
+                hasFrontmatter: true,
+            };
+        }
+        try {
+            // Use existing yamlParser for parsing (handles <think> blocks too)
+            const parsedFrontmatter = await yamlParser.parse(yamlContent, context);
+            logger.debug('Frontmatter parsed successfully.', {
+                ...logContext,
+                frontmatterKeys: parsedFrontmatter &&
+                    typeof parsedFrontmatter === 'object' &&
+                    !Array.isArray(parsedFrontmatter)
+                    ? Object.keys(parsedFrontmatter)
+                    : [],
+            });
+            return {
+                frontmatter: parsedFrontmatter,
+                content: markdownContent,
+                hasFrontmatter: true,
+            };
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            const errorLogContext = context ||
+                requestContextService.createRequestContext({
+                    operation: 'FrontmatterParser.parseError',
+                });
+            logger.error('Failed to parse frontmatter YAML content.', {
+                ...errorLogContext,
+                errorDetails: error.message,
+                yamlContentSample: yamlContent.substring(0, 200),
+            });
+            // Re-throw McpError from yamlParser or create new one
+            if (error instanceof McpError) {
+                throw error;
+            }
+            throw new McpError(JsonRpcErrorCode.ValidationError, `Failed to parse frontmatter: ${error.message}`, {
+                ...context,
+                yamlContentSample: yamlContent.substring(0, 200) + (yamlContent.length > 200 ? '...' : ''),
+                rawError: error instanceof Error ? error.stack : String(error),
+            });
+        }
+    }
+}
+/**
+ * Singleton instance of {@link FrontmatterParser}.
+ *
+ * Use this shared instance to extract and parse YAML frontmatter from markdown
+ * documents rather than constructing a new parser per call.
+ *
+ * @example
+ * ```typescript
+ * import { frontmatterParser } from './frontmatterParser.js';
+ * import { requestContextService } from '../../utils/internal/requestContext.js';
+ *
+ * const context = requestContextService.createRequestContext({ operation: 'ParseObsidianNote' });
+ *
+ * // Markdown with frontmatter
+ * const markdown = `---
+ * title: My Note
+ * tags: [productivity, notes]
+ * date: 2025-01-15
+ * ---
+ *
+ * # Note Content
+ * This is the actual note.`;
+ *
+ * const result = await frontmatterParser.parse(markdown, context);
+ * console.log(result.frontmatter);    // { title: 'My Note', tags: [...], date: '2025-01-15' }
+ * console.log(result.content);        // '\n# Note Content\nThis is the actual note.'
+ * console.log(result.hasFrontmatter); // true
+ *
+ * // Markdown without frontmatter
+ * const plainMarkdown = '# Just Content';
+ * const result2 = await frontmatterParser.parse(plainMarkdown, context);
+ * console.log(result2.frontmatter);    // {}
+ * console.log(result2.content);        // '# Just Content'
+ * console.log(result2.hasFrontmatter); // false
+ * ```
+ */
+export const frontmatterParser = new FrontmatterParser();
+//# sourceMappingURL=frontmatterParser.js.map

package/dist/utils/parsing/frontmatterParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatterParser.js","sourceRoot":"","sources":["../../../src/utils/parsing/frontmatterParser.ts"],"names":[],"mappings":"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"}

package/dist/utils/parsing/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Barrel export for content parsing utilities.
+ * All parsers use lazy dynamic imports — install the underlying dependency
+ * only when you need a specific parser.
+ * @module utils/parsing
+ */
+export { CsvParser, csvParser } from './csvParser.js';
+export { dateParser, parseDateString, parseDateStringDetailed } from './dateParser.js';
+export { FrontmatterParser, type FrontmatterResult, frontmatterParser, } from './frontmatterParser.js';
+export { Allow, JsonParser, jsonParser } from './jsonParser.js';
+export { type AddPageOptions, type DrawImageOptions, type DrawTextOptions, type EmbedImageOptions, type ExtractTextOptions, type ExtractTextResult, type FillFormOptions, type PageRange, type PdfMetadata, PdfParser, pdfParser, type SetMetadataOptions, } from './pdfParser.js';
+export { thinkBlockRegex } from './thinkBlock.js';
+export { XmlParser, xmlParser } from './xmlParser.js';
+export { YamlParser, yamlParser } from './yamlParser.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/parsing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/parsing/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EACL,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,SAAS,EACT,SAAS,EACT,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/utils/parsing/index.js

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Barrel export for content parsing utilities.
+ * All parsers use lazy dynamic imports — install the underlying dependency
+ * only when you need a specific parser.
+ * @module utils/parsing
+ */
+export { CsvParser, csvParser } from './csvParser.js';
+export { dateParser, parseDateString, parseDateStringDetailed } from './dateParser.js';
+export { FrontmatterParser, frontmatterParser, } from './frontmatterParser.js';
+export { Allow, JsonParser, jsonParser } from './jsonParser.js';
+export { PdfParser, pdfParser, } from './pdfParser.js';
+export { thinkBlockRegex } from './thinkBlock.js';
+export { XmlParser, xmlParser } from './xmlParser.js';
+export { YamlParser, yamlParser } from './yamlParser.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/parsing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/parsing/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EACL,iBAAiB,EAEjB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAUL,SAAS,EACT,SAAS,GAEV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/utils/parsing/jsonParser.d.ts

@@ -0,0 +1,115 @@
+import { type RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Bit flags specifying which partial JSON types are permissible during parsing.
+ * Mirrors `partial-json`'s `Allow` constants. Combine flags with bitwise OR
+ * to allow multiple partial types simultaneously.
+ *
+ * @example
+ * ```typescript
+ * // Allow only partial strings and arrays
+ * const result = await jsonParser.parse(str, Allow.STR | Allow.ARR);
+ *
+ * // Allow everything (default)
+ * const result = await jsonParser.parse(str, Allow.ALL);
+ * ```
+ */
+export declare const Allow: {
+    /** Allow partial strings. */
+    readonly STR: 1;
+    /** Allow partial numbers. */
+    readonly NUM: 2;
+    /** Allow partial arrays. */
+    readonly ARR: 4;
+    /** Allow partial objects. */
+    readonly OBJ: 8;
+    /** Allow partial null values. */
+    readonly NULL: 16;
+    /** Allow partial booleans. */
+    readonly BOOL: 32;
+    /** Allow NaN values. */
+    readonly NAN: 64;
+    /** Allow positive Infinity. */
+    readonly INFINITY: 128;
+    /** Allow negative Infinity. */
+    readonly _INFINITY: 256;
+    /** Allow both positive and negative Infinity (`INFINITY | _INFINITY`). */
+    readonly INF: number;
+    /** Allow all special values: NULL, BOOL, NAN, INFINITY, _INFINITY. */
+    readonly SPECIAL: number;
+    /** Allow all atomic types: STR, NUM, NULL, BOOL, NAN, INFINITY, _INFINITY. */
+    readonly ATOM: number;
+    /** Allow partial collections: ARR and OBJ. */
+    readonly COLLECTION: number;
+    /** Allow all partial types. */
+    readonly ALL: number;
+};
+/**
+ * Utility class for parsing potentially partial JSON strings.
+ * Wraps the `partial-json` library for robust JSON parsing, handling
+ * incomplete structures and optional `<think>` blocks from LLM outputs.
+ *
+ * All parse methods are async due to lazy loading of the `partial-json` peer dependency.
+ * Install it with: `bun add partial-json`
+ */
+export declare class JsonParser {
+    /**
+     * Parses a JSON string, which may be partial or prefixed with a `<think>` block.
+     *
+     * If a `<think>...</think>` block is present at the start of the string, its content
+     * is logged at debug level and stripped before parsing. The remainder is then parsed
+     * using `partial-json`, which tolerates incomplete JSON structures.
+     *
+     * This method is async due to lazy loading of the `partial-json` peer dependency
+     * (`bun add partial-json`).
+     *
+     * @template T - The expected type of the parsed result. Defaults to `unknown`.
+     * @param jsonString - The raw string to parse. May include a leading `<think>` block
+     *   and/or be a partial (incomplete) JSON value.
+     * @param allowPartial - Bitwise OR combination of `Allow` flags controlling which
+     *   partial JSON types are accepted. Defaults to `Allow.ALL`.
+     * @param context - Optional `RequestContext` for correlated logging and error metadata.
+     * @returns The parsed JavaScript value cast to `T`.
+     * @throws {McpError} With `ValidationError` if the string is empty after stripping the
+     *   `<think>` block and trimming, or if `partial-json` fails to parse the content.
+     * @throws {McpError} With `ConfigurationError` if the `partial-json` package is not installed.
+     * @example
+     * ```typescript
+     * import { jsonParser, Allow } from '../../utils/parsing/jsonParser.js';
+     *
+     * // Parse complete JSON
+     * const obj = await jsonParser.parse<{ key: string }>('{"key": "value"}');
+     * console.log(obj.key); // "value"
+     *
+     * // Parse partial JSON with a <think> prefix
+     * const partial = '<think>reasoning...</think>{"items": [1, 2,';
+     * const result = await jsonParser.parse(partial, Allow.ALL);
+     * console.log(result); // { items: [1, 2] }
+     * ```
+     */
+    parse<T = unknown>(jsonString: string, allowPartial?: number, context?: RequestContext): Promise<T>;
+}
+/**
+ * Singleton instance of `JsonParser`.
+ *
+ * Provides partial JSON parsing with `<think>` block stripping. Methods are async
+ * due to lazy loading of the `partial-json` peer dependency (`bun add partial-json`).
+ *
+ * @example
+ * ```typescript
+ * import { jsonParser, Allow } from '../../utils/parsing/jsonParser.js';
+ * import { requestContextService } from '../../utils/internal/requestContext.js';
+ *
+ * const ctx = requestContextService.createRequestContext({ operation: 'myOp' });
+ *
+ * // Full JSON
+ * const obj = await jsonParser.parse<{ key: string }>('{"key": "value"}', Allow.ALL, ctx);
+ * console.log(obj.key); // "value"
+ *
+ * // Partial JSON with think block
+ * const raw = '<think>reasoning...</think>{"key": "value", "arr": [1,';
+ * const partial = await jsonParser.parse(raw, Allow.ALL, ctx);
+ * console.log(partial); // { key: 'value', arr: [1] }
+ * ```
+ */
+export declare const jsonParser: JsonParser;
+//# sourceMappingURL=jsonParser.d.ts.map

package/dist/utils/parsing/jsonParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonParser.d.ts","sourceRoot":"","sources":["../../../src/utils/parsing/jsonParser.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,oCAAoC,CAAC;AAchG;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK;IAChB,6BAA6B;;IAE7B,6BAA6B;;IAE7B,4BAA4B;;IAE5B,6BAA6B;;IAE7B,iCAAiC;;IAEjC,8BAA8B;;IAE9B,wBAAwB;;IAExB,+BAA+B;;IAE/B,+BAA+B;;IAE/B,0EAA0E;;IAE1E,sEAAsE;;IAEtE,8EAA8E;;IAE9E,8CAA8C;;IAE9C,+BAA+B;;CAEvB,CAAC;AAEX;;;;;;;GAOG;AACH,qBAAa,UAAU;IACrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EACrB,UAAU,EAAE,MAAM,EAClB,YAAY,GAAE,MAAkB,EAChC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,CAAC,CAAC;CA8Dd;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,UAAU,YAAmB,CAAC"}

package/dist/utils/parsing/jsonParser.js

@@ -0,0 +1,177 @@
+/**
+ * @fileoverview Provides a utility class for parsing potentially partial JSON strings.
+ * It wraps the 'partial-json' npm library and includes functionality to handle
+ * optional <think>...</think> blocks often found at the beginning of LLM outputs.
+ * @module src/utils/parsing/jsonParser
+ */
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+import { logger } from '../../utils/internal/logger.js';
+import { requestContextService } from '../../utils/internal/requestContext.js';
+import { thinkBlockRegex } from './thinkBlock.js';
+let _partialJson;
+async function getPartialJson() {
+    _partialJson ??= await import('partial-json').catch(() => {
+        throw new McpError(JsonRpcErrorCode.ConfigurationError, 'Install "partial-json" to use partial JSON parsing: bun add partial-json');
+    });
+    return _partialJson;
+}
+/**
+ * Bit flags specifying which partial JSON types are permissible during parsing.
+ * Mirrors `partial-json`'s `Allow` constants. Combine flags with bitwise OR
+ * to allow multiple partial types simultaneously.
+ *
+ * @example
+ * ```typescript
+ * // Allow only partial strings and arrays
+ * const result = await jsonParser.parse(str, Allow.STR | Allow.ARR);
+ *
+ * // Allow everything (default)
+ * const result = await jsonParser.parse(str, Allow.ALL);
+ * ```
+ */
+export const Allow = {
+    /** Allow partial strings. */
+    STR: 0x1,
+    /** Allow partial numbers. */
+    NUM: 0x2,
+    /** Allow partial arrays. */
+    ARR: 0x4,
+    /** Allow partial objects. */
+    OBJ: 0x8,
+    /** Allow partial null values. */
+    NULL: 0x10,
+    /** Allow partial booleans. */
+    BOOL: 0x20,
+    /** Allow NaN values. */
+    NAN: 0x40,
+    /** Allow positive Infinity. */
+    INFINITY: 0x80,
+    /** Allow negative Infinity. */
+    _INFINITY: 0x100,
+    /** Allow both positive and negative Infinity (`INFINITY | _INFINITY`). */
+    INF: 0x80 | 0x100,
+    /** Allow all special values: NULL, BOOL, NAN, INFINITY, _INFINITY. */
+    SPECIAL: 0x10 | 0x20 | 0x40 | 0x80 | 0x100,
+    /** Allow all atomic types: STR, NUM, NULL, BOOL, NAN, INFINITY, _INFINITY. */
+    ATOM: 0x1 | 0x2 | 0x10 | 0x20 | 0x40 | 0x80 | 0x100,
+    /** Allow partial collections: ARR and OBJ. */
+    COLLECTION: 0x4 | 0x8,
+    /** Allow all partial types. */
+    ALL: 0x1 | 0x2 | 0x4 | 0x8 | 0x10 | 0x20 | 0x40 | 0x80 | 0x100,
+};
+/**
+ * Utility class for parsing potentially partial JSON strings.
+ * Wraps the `partial-json` library for robust JSON parsing, handling
+ * incomplete structures and optional `<think>` blocks from LLM outputs.
+ *
+ * All parse methods are async due to lazy loading of the `partial-json` peer dependency.
+ * Install it with: `bun add partial-json`
+ */
+export class JsonParser {
+    /**
+     * Parses a JSON string, which may be partial or prefixed with a `<think>` block.
+     *
+     * If a `<think>...</think>` block is present at the start of the string, its content
+     * is logged at debug level and stripped before parsing. The remainder is then parsed
+     * using `partial-json`, which tolerates incomplete JSON structures.
+     *
+     * This method is async due to lazy loading of the `partial-json` peer dependency
+     * (`bun add partial-json`).
+     *
+     * @template T - The expected type of the parsed result. Defaults to `unknown`.
+     * @param jsonString - The raw string to parse. May include a leading `<think>` block
+     *   and/or be a partial (incomplete) JSON value.
+     * @param allowPartial - Bitwise OR combination of `Allow` flags controlling which
+     *   partial JSON types are accepted. Defaults to `Allow.ALL`.
+     * @param context - Optional `RequestContext` for correlated logging and error metadata.
+     * @returns The parsed JavaScript value cast to `T`.
+     * @throws {McpError} With `ValidationError` if the string is empty after stripping the
+     *   `<think>` block and trimming, or if `partial-json` fails to parse the content.
+     * @throws {McpError} With `ConfigurationError` if the `partial-json` package is not installed.
+     * @example
+     * ```typescript
+     * import { jsonParser, Allow } from '../../utils/parsing/jsonParser.js';
+     *
+     * // Parse complete JSON
+     * const obj = await jsonParser.parse<{ key: string }>('{"key": "value"}');
+     * console.log(obj.key); // "value"
+     *
+     * // Parse partial JSON with a <think> prefix
+     * const partial = '<think>reasoning...</think>{"items": [1, 2,';
+     * const result = await jsonParser.parse(partial, Allow.ALL);
+     * console.log(result); // { items: [1, 2] }
+     * ```
+     */
+    async parse(jsonString, allowPartial = Allow.ALL, context) {
+        let stringToParse = jsonString;
+        const match = jsonString.match(thinkBlockRegex);
+        if (match) {
+            const thinkContent = match[1]?.trim() ?? '';
+            const restOfString = match[2] ?? '';
+            const logContext = context ||
+                requestContextService.createRequestContext({
+                    operation: 'JsonParser.thinkBlock',
+                });
+            if (thinkContent) {
+                logger.debug('LLM <think> block detected and logged.', {
+                    ...logContext,
+                    thinkContent,
+                });
+            }
+            else {
+                logger.debug('Empty LLM <think> block detected.', logContext);
+            }
+            stringToParse = restOfString;
+        }
+        stringToParse = stringToParse.trim();
+        if (!stringToParse) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'JSON string is empty after removing <think> block and trimming.', context);
+        }
+        try {
+            const { parse: parsePartialJson } = await getPartialJson();
+            return parsePartialJson(stringToParse, allowPartial);
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            const errorLogContext = context ||
+                requestContextService.createRequestContext({
+                    operation: 'JsonParser.parseError',
+                });
+            logger.error('Failed to parse JSON content.', {
+                ...errorLogContext,
+                errorDetails: error.message,
+                contentAttempted: stringToParse.substring(0, 200),
+            });
+            throw new McpError(JsonRpcErrorCode.ValidationError, `Failed to parse JSON: ${error.message}`, {
+                ...context,
+                originalContentSample: stringToParse.substring(0, 200) + (stringToParse.length > 200 ? '...' : ''),
+                rawError: error instanceof Error ? error.stack : String(error),
+            });
+        }
+    }
+}
+/**
+ * Singleton instance of `JsonParser`.
+ *
+ * Provides partial JSON parsing with `<think>` block stripping. Methods are async
+ * due to lazy loading of the `partial-json` peer dependency (`bun add partial-json`).
+ *
+ * @example
+ * ```typescript
+ * import { jsonParser, Allow } from '../../utils/parsing/jsonParser.js';
+ * import { requestContextService } from '../../utils/internal/requestContext.js';
+ *
+ * const ctx = requestContextService.createRequestContext({ operation: 'myOp' });
+ *
+ * // Full JSON
+ * const obj = await jsonParser.parse<{ key: string }>('{"key": "value"}', Allow.ALL, ctx);
+ * console.log(obj.key); // "value"
+ *
+ * // Partial JSON with think block
+ * const raw = '<think>reasoning...</think>{"key": "value", "arr": [1,';
+ * const partial = await jsonParser.parse(raw, Allow.ALL, ctx);
+ * console.log(partial); // { key: 'value', arr: [1] }
+ * ```
+ */
+export const jsonParser = new JsonParser();
+//# sourceMappingURL=jsonParser.js.map

package/dist/utils/parsing/jsonParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonParser.js","sourceRoot":"","sources":["../../../src/utils/parsing/jsonParser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAuB,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChG,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,IAAI,YAAuD,CAAC;AAC5D,KAAK,UAAU,cAAc;IAC3B,YAAY,KAAK,MAAM,MAAM,CAAC,cAAc,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;QACvD,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,kBAAkB,EACnC,0EAA0E,CAC3E,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,6BAA6B;IAC7B,GAAG,EAAE,GAAG;IACR,6BAA6B;IAC7B,GAAG,EAAE,GAAG;IACR,4BAA4B;IAC5B,GAAG,EAAE,GAAG;IACR,6BAA6B;IAC7B,GAAG,EAAE,GAAG;IACR,iCAAiC;IACjC,IAAI,EAAE,IAAI;IACV,8BAA8B;IAC9B,IAAI,EAAE,IAAI;IACV,wBAAwB;IACxB,GAAG,EAAE,IAAI;IACT,+BAA+B;IAC/B,QAAQ,EAAE,IAAI;IACd,+BAA+B;IAC/B,SAAS,EAAE,KAAK;IAChB,0EAA0E;IAC1E,GAAG,EAAE,IAAI,GAAG,KAAK;IACjB,sEAAsE;IACtE,OAAO,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK;IAC1C,8EAA8E;IAC9E,IAAI,EAAE,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK;IACnD,8CAA8C;IAC9C,UAAU,EAAE,GAAG,GAAG,GAAG;IACrB,+BAA+B;IAC/B,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK;CACtD,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,OAAO,UAAU;IACrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,KAAK,CAAC,KAAK,CACT,UAAkB,EAClB,eAAuB,KAAK,CAAC,GAAG,EAChC,OAAwB;QAExB,IAAI,aAAa,GAAG,UAAU,CAAC;QAC/B,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QAEhD,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YAC5C,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAEpC,MAAM,UAAU,GACd,OAAO;gBACP,qBAAqB,CAAC,oBAAoB,CAAC;oBACzC,SAAS,EAAE,uBAAuB;iBACnC,CAAC,CAAC;YACL,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,CAAC,KAAK,CAAC,wCAAwC,EAAE;oBACrD,GAAG,UAAU;oBACb,YAAY;iBACb,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,KAAK,CAAC,mCAAmC,EAAE,UAAU,CAAC,CAAC;YAChE,CAAC;YACD,aAAa,GAAG,YAAY,CAAC;QAC/B,CAAC;QAED,aAAa,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC;QAErC,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,iEAAiE,EACjE,OAAO,CACR,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,MAAM,cAAc,EAAE,CAAC;YAC3D,OAAO,gBAAgB,CAAC,aAAa,EAAE,YAAY,CAAM,CAAC;QAC5D,CAAC;QAAC,OAAO,CAAU,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5D,MAAM,eAAe,GACnB,OAAO;gBACP,qBAAqB,CAAC,oBAAoB,CAAC;oBACzC,SAAS,EAAE,uBAAuB;iBACnC,CAAC,CAAC;YACL,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAAE;gBAC5C,GAAG,eAAe;gBAClB,YAAY,EAAE,KAAK,CAAC,OAAO;gBAC3B,gBAAgB,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC;aAClD,CAAC,CAAC;YAEH,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,yBAAyB,KAAK,CAAC,OAAO,EAAE,EACxC;gBACE,GAAG,OAAO;gBACV,qBAAqB,EACnB,aAAa,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7E,QAAQ,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC/D,CACF,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,UAAU,EAAE,CAAC"}