@metaneutrons/doc-tools-mcp 0.1.0

package/dist/providers/bib/store.js

@@ -0,0 +1,90 @@
+import { readFile, writeFile, copyFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import yaml from 'js-yaml';
+import { cslEntrySchema } from './schema.js';
+import { FileError } from '../../shared/errors.js';
+import { rootLogger } from '../../shared/logger.js';
+const logger = rootLogger.child({ module: 'bib-store' });
+export class BibStore {
+    /** Read and parse a CSL-YAML file */
+    async read(filePath) {
+        if (!existsSync(filePath)) {
+            throw new FileError(`File not found: ${filePath}`, filePath);
+        }
+        try {
+            const content = await readFile(filePath, 'utf-8');
+            const doc = yaml.load(content);
+            if (!doc || !Array.isArray(doc.references)) {
+                throw new FileError('Invalid CSL-YAML: missing "references" array', filePath);
+            }
+            return doc.references.map((entry) => {
+                const result = cslEntrySchema.safeParse(entry);
+                if (!result.success) {
+                    logger.warn('Entry failed schema validation', { id: entry?.id, errors: result.error.issues });
+                    return entry;
+                }
+                return result.data;
+            });
+        }
+        catch (error) {
+            if (error instanceof FileError)
+                throw error;
+            throw new FileError(`Failed to parse YAML: ${error instanceof Error ? error.message : String(error)}`, filePath, error instanceof Error ? error : undefined);
+        }
+    }
+    /** Write entries back to a CSL-YAML file, creating a .bak backup first */
+    async write(filePath, entries) {
+        // Backup
+        if (existsSync(filePath)) {
+            const backupPath = `${filePath}.bak`;
+            await copyFile(filePath, backupPath);
+            logger.info('Backup created', { backupPath });
+        }
+        const doc = { references: entries };
+        const content = '---\n' + yaml.dump(doc, {
+            indent: 2,
+            lineWidth: -1,
+            noRefs: true,
+            quotingType: '"',
+            forceQuotes: false,
+            sortKeys: false,
+        });
+        await writeFile(filePath, content, 'utf-8');
+        logger.info('File written', { filePath, count: entries.length });
+    }
+    /** Get a single entry by ID */
+    async get(filePath, id) {
+        const entries = await this.read(filePath);
+        return entries.find((e) => e.id === id);
+    }
+    /** Check if an ID exists */
+    async exists(filePath, id) {
+        const entries = await this.read(filePath);
+        return entries.some((e) => e.id === id);
+    }
+    /** Add a new entry (appends to end) */
+    async add(filePath, entry) {
+        const entries = await this.read(filePath);
+        entries.push(entry);
+        await this.write(filePath, entries);
+    }
+    /** Update fields of an existing entry */
+    async update(filePath, id, fields) {
+        const entries = await this.read(filePath);
+        const index = entries.findIndex((e) => e.id === id);
+        if (index === -1)
+            throw new Error(`Entry '${id}' not found`);
+        entries[index] = { ...entries[index], ...fields, id };
+        await this.write(filePath, entries);
+        return entries[index];
+    }
+    /** Delete an entry by ID */
+    async delete(filePath, id) {
+        const entries = await this.read(filePath);
+        const filtered = entries.filter((e) => e.id !== id);
+        if (filtered.length === entries.length)
+            throw new Error(`Entry '${id}' not found`);
+        await this.write(filePath, filtered);
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/providers/bib/store.js.map

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

package/dist/providers/bib/tools/index.d.ts

@@ -0,0 +1,2 @@
+import { ToolDefinition } from '../../../shared/types.js';
+export declare const bibTools: ToolDefinition[];

package/dist/providers/bib/tools/index.js

@@ -0,0 +1,4 @@
+import { readTools } from './read.js';
+import { writeTools } from './write.js';
+export const bibTools = [...readTools, ...writeTools];
+//# sourceMappingURL=index.js.map

package/dist/providers/bib/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/providers/bib/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,MAAM,CAAC,MAAM,QAAQ,GAAqB,CAAC,GAAG,SAAS,EAAE,GAAG,UAAU,CAAC,CAAC"}

package/dist/providers/bib/tools/read.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import { ToolDefinition } from '../../../shared/types.js';
+/** Shared file parameter — every bib tool needs this */
+export declare const fileParam: z.ZodString;
+export declare const readTools: ToolDefinition[];

package/dist/providers/bib/tools/read.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+/** Shared file parameter — every bib tool needs this */
+export const fileParam = z.string().describe('Absolute path to the CSL-YAML bibliography file. ' +
+    'Look for "bibliography:" in pandoc.yaml or the YAML frontmatter of .md files to find the path.');
+export const readTools = [
+    {
+        name: 'bib:get',
+        description: 'Retrieve a single bibliography entry by ID. Returns the full YAML block.',
+        inputSchema: z.object({
+            file: fileParam,
+            id: z.string().describe('The citation ID (e.g., "BGH_I_ZR_73_79")'),
+        }),
+    },
+    {
+        name: 'bib:search',
+        description: 'Search bibliography entries across all fields: author, title, type, year, editor, container-title. Returns matching entries.',
+        inputSchema: z.object({
+            file: fileParam,
+            query: z.string().describe('Search term (case-insensitive, matches any field)'),
+            limit: z.number().optional().default(20).describe('Maximum results to return (default: 20)'),
+        }),
+    },
+    {
+        name: 'bib:list',
+        description: 'List all bibliography entries of a given CSL type (e.g., "legal_case", "book", "article-journal", "chapter").',
+        inputSchema: z.object({
+            file: fileParam,
+            type: z.string().describe('CSL type to filter by (e.g., "legal_case", "book", "article-journal")'),
+            limit: z.number().optional().default(50).describe('Maximum results to return (default: 50)'),
+        }),
+    },
+    {
+        name: 'bib:exists',
+        description: 'Check if a citation ID exists in the bibliography. Fast boolean check before citing.',
+        inputSchema: z.object({
+            file: fileParam,
+            id: z.string().describe('The citation ID to check'),
+        }),
+    },
+    {
+        name: 'bib:stats',
+        description: 'Get bibliography statistics: total entry count and breakdown by CSL type.',
+        inputSchema: z.object({
+            file: fileParam,
+        }),
+    },
+];
+//# sourceMappingURL=read.js.map

package/dist/providers/bib/tools/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../../src/providers/bib/tools/read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,wDAAwD;AACxD,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAC1C,mDAAmD;IACnD,gGAAgG,CACjG,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAqB;IACzC;QACE,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,0EAA0E;QACvF,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,IAAI,EAAE,SAAS;YACf,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;SACpE,CAAC;KACH;IACD;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,8HAA8H;QAC3I,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;YAC/E,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,yCAAyC,CAAC;SAC7F,CAAC;KACH;IACD;QACE,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,+GAA+G;QAC5H,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uEAAuE,CAAC;YAClG,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,yCAAyC,CAAC;SAC7F,CAAC;KACH;IACD;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,sFAAsF;QACnG,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,IAAI,EAAE,SAAS;YACf,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;SACpD,CAAC;KACH;IACD;QACE,IAAI,EAAE,WAAW;QACjB,WAAW,EAAE,2EAA2E;QACxF,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,IAAI,EAAE,SAAS;SAChB,CAAC;KACH;CACF,CAAC"}

package/dist/providers/bib/tools/write.d.ts

@@ -0,0 +1,2 @@
+import { ToolDefinition } from '../../../shared/types.js';
+export declare const writeTools: ToolDefinition[];

package/dist/providers/bib/tools/write.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { fileParam } from './read.js';
+export const writeTools = [
+    {
+        name: 'bib:add',
+        description: 'Add a new bibliography entry. Validates required fields per CSL type, checks for duplicate IDs, ' +
+            'and creates a .bak backup before writing. Returns the created YAML block for confirmation.',
+        inputSchema: z.object({
+            file: fileParam,
+            entry: z.object({
+                id: z.string().describe('Unique citation ID (e.g., "BGH_I_ZR_42_22")'),
+                type: z.string().describe('CSL type (e.g., "legal_case", "book", "article-journal", "chapter")'),
+                title: z.string().optional().describe('Title of the work'),
+                author: z.array(z.object({
+                    family: z.string(),
+                    given: z.string().optional(),
+                })).optional().describe('Author(s)'),
+                editor: z.array(z.object({
+                    family: z.string(),
+                    given: z.string().optional(),
+                })).optional().describe('Editor(s)'),
+                issued: z.object({
+                    'date-parts': z.array(z.array(z.number())).optional(),
+                }).optional().describe('Publication date, e.g., {"date-parts": [[2024]]}'),
+                'container-title': z.string().optional().describe('Journal, reporter, or book title'),
+                volume: z.string().optional(),
+                page: z.string().optional(),
+                publisher: z.string().optional(),
+                'publisher-place': z.string().optional(),
+                edition: z.string().optional(),
+                authority: z.string().optional().describe('Court name (for legal_case)'),
+                number: z.string().optional().describe('Case number or report number'),
+                genre: z.string().optional().describe('e.g., "Urt.", "Beschl."'),
+                url: z.string().optional(),
+                note: z.string().optional(),
+            }).passthrough().describe('The CSL-YAML entry to add'),
+        }),
+    },
+    {
+        name: 'bib:update',
+        description: 'Update fields of an existing bibliography entry. Only the specified fields are changed; ' +
+            'all other fields remain untouched. Creates a .bak backup before writing.',
+        inputSchema: z.object({
+            file: fileParam,
+            id: z.string().describe('The citation ID to update'),
+            fields: z.record(z.string(), z.unknown()).describe('Fields to update (e.g., {"url": "https://...", "page": "123"})'),
+        }),
+    },
+    {
+        name: 'bib:delete',
+        description: 'Remove a bibliography entry by ID. Creates a .bak backup before writing.',
+        inputSchema: z.object({
+            file: fileParam,
+            id: z.string().describe('The citation ID to delete'),
+        }),
+    },
+    {
+        name: 'bib:validate',
+        description: 'Validate the entire bibliography file: YAML syntax, required fields per CSL type, ' +
+            'duplicate IDs, and missing issued dates. Returns a list of errors and warnings.',
+        inputSchema: z.object({
+            file: fileParam,
+        }),
+    },
+];
+//# sourceMappingURL=write.js.map

package/dist/providers/bib/tools/write.js.map

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

package/dist/shared/errors.d.ts

@@ -0,0 +1,34 @@
+export declare abstract class BaseError extends Error {
+    readonly cause?: Error | undefined;
+    abstract readonly code: string;
+    abstract readonly userMessage: string;
+    abstract readonly recoveryHint?: string;
+    constructor(message: string, cause?: Error | undefined);
+    toString(): string;
+}
+export declare class ValidationError extends BaseError {
+    readonly field?: string | undefined;
+    readonly code = "VALIDATION_ERROR";
+    readonly userMessage: string;
+    readonly recoveryHint: string;
+    constructor(message: string, field?: string | undefined, cause?: Error);
+}
+export declare class FileError extends BaseError {
+    readonly filePath: string;
+    readonly code = "FILE_ERROR";
+    readonly userMessage: string;
+    readonly recoveryHint: string;
+    constructor(message: string, filePath: string, cause?: Error);
+}
+export declare class NotFoundError extends BaseError {
+    readonly code = "NOT_FOUND";
+    readonly userMessage: string;
+    readonly recoveryHint = "Use bib:search or bib:list to find available entries.";
+    constructor(id: string);
+}
+export declare class DuplicateError extends BaseError {
+    readonly code = "DUPLICATE_ID";
+    readonly userMessage: string;
+    readonly recoveryHint = "Use a different ID or update the existing entry with bib:update.";
+    constructor(id: string);
+}

package/dist/shared/errors.js

@@ -0,0 +1,60 @@
+export class BaseError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = this.constructor.name;
+        Error.captureStackTrace(this, this.constructor);
+    }
+    toString() {
+        let msg = `${this.userMessage}\n\nError Code: ${this.code}`;
+        if (this.recoveryHint)
+            msg += `\n\nHow to fix: ${this.recoveryHint}`;
+        if (this.cause)
+            msg += `\n\nTechnical details: ${this.cause.message}`;
+        return msg;
+    }
+}
+export class ValidationError extends BaseError {
+    field;
+    code = 'VALIDATION_ERROR';
+    userMessage;
+    recoveryHint;
+    constructor(message, field, cause) {
+        super(message, cause);
+        this.field = field;
+        this.userMessage = message;
+        this.recoveryHint = field ? `Check the '${field}' parameter.` : 'Check your input parameters.';
+    }
+}
+export class FileError extends BaseError {
+    filePath;
+    code = 'FILE_ERROR';
+    userMessage;
+    recoveryHint;
+    constructor(message, filePath, cause) {
+        super(message, cause);
+        this.filePath = filePath;
+        this.userMessage = message;
+        this.recoveryHint = `Check that '${filePath}' exists and is readable.`;
+    }
+}
+export class NotFoundError extends BaseError {
+    code = 'NOT_FOUND';
+    userMessage;
+    recoveryHint = 'Use bib:search or bib:list to find available entries.';
+    constructor(id) {
+        super(`Entry '${id}' not found`);
+        this.userMessage = `Entry '${id}' not found in the bibliography.`;
+    }
+}
+export class DuplicateError extends BaseError {
+    code = 'DUPLICATE_ID';
+    userMessage;
+    recoveryHint = 'Use a different ID or update the existing entry with bib:update.';
+    constructor(id) {
+        super(`Entry '${id}' already exists`);
+        this.userMessage = `Entry '${id}' already exists in the bibliography.`;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/shared/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAgB,SAAU,SAAQ,KAAK;IAKE;IAA7C,YAAY,OAAe,EAAkB,KAAa;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,UAAK,GAAL,KAAK,CAAQ;QAExD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAClC,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IAClD,CAAC;IAED,QAAQ;QACN,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,WAAW,mBAAmB,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5D,IAAI,IAAI,CAAC,YAAY;YAAE,GAAG,IAAI,mBAAmB,IAAI,CAAC,YAAY,EAAE,CAAC;QACrE,IAAI,IAAI,CAAC,KAAK;YAAE,GAAG,IAAI,0BAA0B,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACtE,OAAO,GAAG,CAAC;IACb,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAKC;IAJpC,IAAI,GAAG,kBAAkB,CAAC;IAC1B,WAAW,CAAS;IACpB,YAAY,CAAS;IAE9B,YAAY,OAAe,EAAkB,KAAc,EAAE,KAAa;QACxE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QADqB,UAAK,GAAL,KAAK,CAAS;QAEzD,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,cAAc,KAAK,cAAc,CAAC,CAAC,CAAC,8BAA8B,CAAC;IACjG,CAAC;CACF;AAED,MAAM,OAAO,SAAU,SAAQ,SAAS;IAKO;IAJpC,IAAI,GAAG,YAAY,CAAC;IACpB,WAAW,CAAS;IACpB,YAAY,CAAS;IAE9B,YAAY,OAAe,EAAkB,QAAgB,EAAE,KAAa;QAC1E,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QADqB,aAAQ,GAAR,QAAQ,CAAQ;QAE3D,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,eAAe,QAAQ,2BAA2B,CAAC;IACzE,CAAC;CACF;AAED,MAAM,OAAO,aAAc,SAAQ,SAAS;IACjC,IAAI,GAAG,WAAW,CAAC;IACnB,WAAW,CAAS;IACpB,YAAY,GAAG,uDAAuD,CAAC;IAEhF,YAAY,EAAU;QACpB,KAAK,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;QACjC,IAAI,CAAC,WAAW,GAAG,UAAU,EAAE,kCAAkC,CAAC;IACpE,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,SAAS;IAClC,IAAI,GAAG,cAAc,CAAC;IACtB,WAAW,CAAS;IACpB,YAAY,GAAG,kEAAkE,CAAC;IAE3F,YAAY,EAAU;QACpB,KAAK,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC;QACtC,IAAI,CAAC,WAAW,GAAG,UAAU,EAAE,uCAAuC,CAAC;IACzE,CAAC;CACF"}

package/dist/shared/logger.d.ts

@@ -0,0 +1,17 @@
+export type LogContext = {
+    requestId?: string;
+    operation?: string;
+    file?: string;
+    duration?: number;
+    [key: string]: unknown;
+};
+export declare class Logger {
+    private context;
+    constructor(context?: LogContext);
+    child(additionalContext: LogContext): Logger;
+    debug(msg: string, context?: LogContext): void;
+    info(msg: string, context?: LogContext): void;
+    warn(msg: string, context?: LogContext): void;
+    error(msg: string, error?: Error | unknown, context?: LogContext): void;
+}
+export declare const rootLogger: Logger;

package/dist/shared/logger.js

@@ -0,0 +1,40 @@
+import pino from 'pino';
+const level = process.env.LOG_LEVEL ?? 'info';
+const logger = pino({
+    level,
+    transport: process.env.NODE_ENV !== 'production' ? {
+        target: 'pino-pretty',
+        options: {
+            colorize: true,
+            translateTime: 'SYS:standard',
+            ignore: 'pid,hostname',
+            destination: 2,
+        },
+    } : undefined,
+}, pino.destination({ dest: 2, sync: false }));
+export class Logger {
+    context;
+    constructor(context = {}) {
+        this.context = context;
+    }
+    child(additionalContext) {
+        return new Logger({ ...this.context, ...additionalContext });
+    }
+    debug(msg, context) {
+        logger.debug({ ...this.context, ...context }, msg);
+    }
+    info(msg, context) {
+        logger.info({ ...this.context, ...context }, msg);
+    }
+    warn(msg, context) {
+        logger.warn({ ...this.context, ...context }, msg);
+    }
+    error(msg, error, context) {
+        const errorContext = error instanceof Error
+            ? { error: { message: error.message, stack: error.stack, name: error.name } }
+            : { error };
+        logger.error({ ...this.context, ...context, ...errorContext }, msg);
+    }
+}
+export const rootLogger = new Logger();
+//# sourceMappingURL=logger.js.map

package/dist/shared/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/shared/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM,CAAC;AAE9C,MAAM,MAAM,GAAG,IAAI,CAAC;IAClB,KAAK;IACL,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC,CAAC,CAAC;QACjD,MAAM,EAAE,aAAa;QACrB,OAAO,EAAE;YACP,QAAQ,EAAE,IAAI;YACd,aAAa,EAAE,cAAc;YAC7B,MAAM,EAAE,cAAc;YACtB,WAAW,EAAE,CAAC;SACf;KACF,CAAC,CAAC,CAAC,SAAS;CACd,EAAE,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;AAU/C,MAAM,OAAO,MAAM;IACT,OAAO,CAAa;IAE5B,YAAY,UAAsB,EAAE;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,iBAA6B;QACjC,OAAO,IAAI,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,iBAAiB,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,GAAW,EAAE,OAAoB;QACrC,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,CAAC,GAAW,EAAE,OAAoB;QACpC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,CAAC,GAAW,EAAE,OAAoB;QACpC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,GAAW,EAAE,KAAuB,EAAE,OAAoB;QAC9D,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK;YACzC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE;YAC7E,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;QACd,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,OAAO,EAAE,GAAG,YAAY,EAAE,EAAE,GAAG,CAAC,CAAC;IACtE,CAAC;CACF;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,MAAM,EAAE,CAAC"}

package/dist/shared/types.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+/** MCP tool definition with Zod input schema */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: z.ZodTypeAny;
+}
+/** MCP tool result */
+export interface ToolResult {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/** Provider interface — all tool providers must implement this */
+export interface Provider {
+    readonly name: string;
+    getTools(): ToolDefinition[];
+    handleToolCall(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+    initialize?(): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/shared/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/shared/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@metaneutrons/doc-tools-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for managing pandoc/CSL-YAML bibliographies",
+  "main": "dist/index.js",
+  "bin": {
+    "doc-tools-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/metaneutrons/doc-tools-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/metaneutrons/doc-tools-mcp/issues"
+  },
+  "homepage": "https://github.com/metaneutrons/doc-tools-mcp#readme",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "husky"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "bibliography",
+    "csl",
+    "yaml",
+    "pandoc",
+    "citations"
+  ],
+  "author": {
+    "name": "Fabian Schmieder"
+  },
+  "license": "GPL-3.0",
+  "type": "module",
+  "lint-staged": {
+    "package.json": [
+      "npm audit --audit-level=moderate"
+    ],
+    "*.ts": [
+      "eslint --fix",
+      "vitest related --run"
+    ]
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@types/node": "^22.0.0",
+    "js-yaml": "^4.1.0",
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.0.0",
+    "@commitlint/config-conventional": "^19.0.0",
+    "@eslint/js": "^9.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^9.0.0",
+    "husky": "^9.0.0",
+    "lint-staged": "^15.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}