@novorb/mcp-core 2.1.0

package/dist/logger.js

@@ -0,0 +1,236 @@
+/**
+ * @novorb/mcp-core — Logger
+ *
+ * Unified logger for MCP servers. Supports two output modes:
+ * - file: writes to rotating log files (for stdio-based MCP servers)
+ * - stderr: writes to stderr (for Docker / HTTP transport)
+ *
+ * Log format (text): 2026-03-22T13:27:58.513Z | INFO  | Server | Starting...
+ * Log format (json): {"level":"INFO","timestamp":"...","component":"Server","message":"Starting..."}
+ *
+ * Environment variables (read once at first logger creation):
+ * - LOG_LEVEL: DEBUG, INFO, WARN, ERROR (default: INFO)
+ * - LOG_PATH: log directory (default: ./logs)
+ * - LOG_FILE: log file name (default: mcp.log)
+ *
+ * Security: `meta` is passed through `redactSecrets()` before serialisation — sensitive-keyed fields
+ * (authorization/token/api_key/secret/password/cookie/...) are replaced with `[REDACTED]` so a
+ * consumer that logs an error object or request params never writes a credential in cleartext. In
+ * text mode the message + component are also stripped of CR/LF so a logged value can't forge log lines.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+})(LogLevel || (LogLevel = {}));
+/** Map string → LogLevel, case-insensitive */
+function parseLogLevel(value) {
+    if (!value)
+        return undefined;
+    const upper = value.toUpperCase();
+    if (upper in LogLevel && typeof LogLevel[upper] === 'number') {
+        return LogLevel[upper];
+    }
+    return undefined;
+}
+const DEFAULT_CONFIG = {
+    level: LogLevel.INFO,
+    output: 'stderr',
+    format: 'text',
+    logDir: 'logs',
+    logFile: 'mcp.log',
+    maxLogSize: 10 * 1024 * 1024,
+    maxLogFiles: 5,
+};
+/** Build config from defaults + env vars + explicit overrides */
+function buildConfig(overrides) {
+    const envLevel = parseLogLevel(process.env.LOG_LEVEL);
+    const envDir = process.env.LOG_PATH;
+    const envFile = process.env.LOG_FILE;
+    return {
+        ...DEFAULT_CONFIG,
+        ...(envLevel !== undefined ? { level: envLevel } : {}),
+        ...(envDir ? { logDir: envDir } : {}),
+        ...(envFile ? { logFile: envFile } : {}),
+        ...overrides,
+    };
+}
+// Keys whose values are redacted before a `meta` object is serialised. Defense-in-depth: consumers
+// commonly pass error objects / request params carrying credentials, and a log sink must never write
+// them in cleartext. Matched case-insensitively against each object key.
+const SENSITIVE_KEY = /(authorization|cookie|password|secret|client[_-]?secret|access[_-]?token|refresh[_-]?token|token|api[_-]?key|apikey|bearer|private[_-]?key|signature|x-api-key)/i;
+const REDACTED = '[REDACTED]';
+/** Recursively copy a value, replacing any sensitive-keyed field with `[REDACTED]`. */
+export function redactSecrets(value, depth = 0) {
+    if (depth > 6 || value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(v => redactSecrets(v, depth + 1));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = SENSITIVE_KEY.test(k) ? REDACTED : redactSecrets(v, depth + 1);
+    }
+    return out;
+}
+/** Collapse C0 control chars (incl. CR/LF) + DEL to spaces so a logged value can't forge log lines. */
+function stripControlChars(s) {
+    let out = '';
+    for (let i = 0; i < s.length; i++) {
+        const code = s.charCodeAt(i);
+        out += (code < 0x20 || code === 0x7f) ? ' ' : s[i];
+    }
+    return out;
+}
+// Padded level names — fixed 5 chars for alignment
+const LEVEL_NAMES = {
+    [LogLevel.DEBUG]: 'DEBUG',
+    [LogLevel.INFO]: 'INFO ',
+    [LogLevel.WARN]: 'WARN ',
+    [LogLevel.ERROR]: 'ERROR',
+};
+export class Logger {
+    config;
+    logPath;
+    constructor(config) {
+        this.config = buildConfig(config);
+        this.logPath = path.join(this.config.logDir, this.config.logFile);
+        if (this.config.output === 'file') {
+            this.ensureLogDirectory();
+        }
+    }
+    ensureLogDirectory() {
+        if (!fs.existsSync(this.config.logDir)) {
+            fs.mkdirSync(this.config.logDir, { recursive: true });
+        }
+    }
+    shouldLog(level) {
+        return level >= this.config.level;
+    }
+    formatText(level, message, context, meta) {
+        const timestamp = new Date().toISOString();
+        const levelStr = LEVEL_NAMES[level] ?? LogLevel[level].padEnd(5);
+        const contextStr = stripControlChars(context ?? 'General');
+        const safeMessage = stripControlChars(message);
+        const metaStr = meta !== undefined ? ` | ${JSON.stringify(redactSecrets(meta))}` : '';
+        return `${timestamp} | ${levelStr} | ${contextStr} | ${safeMessage}${metaStr}\n`;
+    }
+    formatJson(level, message, context, meta) {
+        const entry = {
+            level: LogLevel[level],
+            timestamp: new Date().toISOString(),
+            component: context ?? 'General',
+            message,
+        };
+        if (meta !== undefined) {
+            const safeMeta = redactSecrets(meta);
+            if (typeof safeMeta === 'object' && safeMeta !== null) {
+                Object.assign(entry, safeMeta);
+            }
+            else {
+                entry.meta = safeMeta;
+            }
+        }
+        return JSON.stringify(entry) + '\n';
+    }
+    format(level, message, context, meta) {
+        return this.config.format === 'json'
+            ? this.formatJson(level, message, context, meta)
+            : this.formatText(level, message, context, meta);
+    }
+    write(level, message, context, meta) {
+        if (!this.shouldLog(level))
+            return;
+        const formatted = this.format(level, message, context, meta);
+        if (this.config.output === 'file') {
+            this.writeToFile(formatted);
+        }
+        else {
+            process.stderr.write(formatted);
+        }
+    }
+    writeToFile(message) {
+        try {
+            if (fs.existsSync(this.logPath)) {
+                const stats = fs.statSync(this.logPath);
+                if (stats.size > this.config.maxLogSize) {
+                    this.rotateLog();
+                }
+            }
+            fs.appendFileSync(this.logPath, message, 'utf8');
+        }
+        catch {
+            // Silently fail — can't log to console in MCP stdio context
+        }
+    }
+    rotateLog() {
+        try {
+            for (let i = this.config.maxLogFiles - 1; i > 0; i--) {
+                const oldPath = `${this.logPath}.${i}`;
+                const newPath = `${this.logPath}.${i + 1}`;
+                if (fs.existsSync(oldPath)) {
+                    if (i === this.config.maxLogFiles - 1) {
+                        fs.unlinkSync(oldPath);
+                    }
+                    else {
+                        fs.renameSync(oldPath, newPath);
+                    }
+                }
+            }
+            if (fs.existsSync(this.logPath)) {
+                fs.renameSync(this.logPath, `${this.logPath}.1`);
+            }
+        }
+        catch {
+            // Silently fail
+        }
+    }
+    debug(message, context, meta) {
+        this.write(LogLevel.DEBUG, message, context, meta);
+    }
+    info(message, context, meta) {
+        this.write(LogLevel.INFO, message, context, meta);
+    }
+    warn(message, context, meta) {
+        this.write(LogLevel.WARN, message, context, meta);
+    }
+    error(message, context, meta) {
+        this.write(LogLevel.ERROR, message, context, meta);
+    }
+    setLevel(level) {
+        this.config.level = level;
+    }
+}
+// Singleton management
+let loggerInstance = null;
+/**
+ * Initialize logger with custom config.
+ * Should be called once at application startup.
+ * Reads LOG_LEVEL, LOG_PATH, LOG_FILE from env (overrides take precedence).
+ */
+export function initLogger(config) {
+    loggerInstance = new Logger(config);
+    return loggerInstance;
+}
+/**
+ * Get the logger instance.
+ * Creates a default stderr/text instance if initLogger was not called.
+ * Reads LOG_LEVEL, LOG_PATH, LOG_FILE from env on first creation.
+ */
+export function getLogger(config) {
+    if (!loggerInstance) {
+        loggerInstance = new Logger(config);
+    }
+    return loggerInstance;
+}
+/**
+ * Reset the singleton (for testing).
+ */
+export function resetLogger() {
+    loggerInstance = null;
+}
+export default getLogger;
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

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

package/dist/pagination.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @novorb/mcp-core — Pagination utilities
+ *
+ * Normalize and compute pagination metadata across MCP servers.
+ */
+export interface PaginationParams {
+    /** Page number (1-based, default: 1) */
+    page?: number;
+    /** Items per page (default: 20, max: 100) */
+    per_page?: number;
+}
+export interface NormalizedPagination {
+    page: number;
+    per_page: number;
+}
+export interface PaginationMetadata {
+    totalCount: number;
+    page: number;
+    perPage: number;
+    totalPages: number;
+}
+/**
+ * Normalize pagination parameters with sensible bounds.
+ *
+ * @param params - Raw pagination params
+ * @param maxPerPage - Maximum allowed per_page (default: 100)
+ * @param defaultPerPage - Default per_page (default: 20)
+ */
+export declare function normalizePagination(params?: PaginationParams, maxPerPage?: number, defaultPerPage?: number): NormalizedPagination;
+/**
+ * Create pagination metadata from total count and normalized params.
+ */
+export declare function createPaginationMetadata(totalCount: number, params: NormalizedPagination): PaginationMetadata;
+/**
+ * Calculate offset for SQL/API pagination from 1-based page number.
+ */
+export declare function pageToOffset(page: number, perPage: number): number;
+/**
+ * Apply in-memory pagination to an array.
+ */
+export declare function paginateArray<T>(items: T[], params: NormalizedPagination): {
+    data: T[];
+    metadata: PaginationMetadata;
+};
+//# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,CAAC,EAAE,gBAAgB,EACzB,UAAU,SAAM,EAChB,cAAc,SAAK,GAClB,oBAAoB,CAItB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,oBAAoB,GAC3B,kBAAkB,CAOpB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,MAAM,EAAE,oBAAoB,GAC3B;IAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,QAAQ,EAAE,kBAAkB,CAAA;CAAE,CAO7C"}

package/dist/pagination.js

@@ -0,0 +1,46 @@
+/**
+ * @novorb/mcp-core — Pagination utilities
+ *
+ * Normalize and compute pagination metadata across MCP servers.
+ */
+/**
+ * Normalize pagination parameters with sensible bounds.
+ *
+ * @param params - Raw pagination params
+ * @param maxPerPage - Maximum allowed per_page (default: 100)
+ * @param defaultPerPage - Default per_page (default: 20)
+ */
+export function normalizePagination(params, maxPerPage = 100, defaultPerPage = 20) {
+    const page = Math.max(1, params?.page ?? 1);
+    const per_page = Math.min(maxPerPage, Math.max(1, params?.per_page ?? defaultPerPage));
+    return { page, per_page };
+}
+/**
+ * Create pagination metadata from total count and normalized params.
+ */
+export function createPaginationMetadata(totalCount, params) {
+    return {
+        totalCount,
+        page: params.page,
+        perPage: params.per_page,
+        totalPages: Math.ceil(totalCount / params.per_page),
+    };
+}
+/**
+ * Calculate offset for SQL/API pagination from 1-based page number.
+ */
+export function pageToOffset(page, perPage) {
+    return (Math.max(1, page) - 1) * perPage;
+}
+/**
+ * Apply in-memory pagination to an array.
+ */
+export function paginateArray(items, params) {
+    const offset = pageToOffset(params.page, params.per_page);
+    const data = items.slice(offset, offset + params.per_page);
+    return {
+        data,
+        metadata: createPaginationMetadata(items.length, params),
+    };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqBH;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAyB,EACzB,UAAU,GAAG,GAAG,EAChB,cAAc,GAAG,EAAE;IAEnB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,IAAI,cAAc,CAAC,CAAC,CAAC;IACvF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CACtC,UAAkB,EAClB,MAA4B;IAE5B,OAAO;QACL,UAAU;QACV,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO,EAAE,MAAM,CAAC,QAAQ;QACxB,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC;KACpD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,OAAe;IACxD,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAU,EACV,MAA4B;IAE5B,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC3D,OAAO;QACL,IAAI;QACJ,QAAQ,EAAE,wBAAwB,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC;KACzD,CAAC;AACJ,CAAC"}

package/dist/retry.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @novorb/mcp-core — Retry utilities
+ *
+ * Exponential backoff with jitter for retrying failed HTTP requests.
+ */
+export interface RetryOptions {
+    /** Maximum number of retries (default: 3) */
+    maxRetries?: number;
+    /** Initial delay in milliseconds (default: 1000) */
+    initialDelayMs?: number;
+    /** Maximum delay in milliseconds (default: 10000) */
+    maxDelayMs?: number;
+    /** Backoff multiplier (default: 2) */
+    backoffMultiplier?: number;
+    /** Jitter factor 0-1 (default: 0.1 = 10%) */
+    jitterFactor?: number;
+}
+export interface RetryContext {
+    /** Current attempt number (0-based) */
+    attempt: number;
+    /** Maximum retries configured */
+    maxRetries: number;
+    /** Last error encountered */
+    lastError?: Error;
+}
+/**
+ * Calculate retry delay with exponential backoff and jitter.
+ */
+export declare function calculateRetryDelay(attempt: number, options?: RetryOptions): number;
+/**
+ * Sleep for specified milliseconds.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Determine if an error is retryable.
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Retry a function with exponential backoff.
+ *
+ * @param fn - Async function to retry (receives RetryContext)
+ * @param options - Retry options
+ * @returns Result of successful function call
+ * @throws Last error if all retries exhausted or error is not retryable
+ */
+export declare function retryWithBackoff<T>(fn: (context: RetryContext) => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Parse Retry-After header value to milliseconds.
+ */
+export declare function parseRetryAfter(retryAfter: string | undefined): number | undefined;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,KAAK,CAAC;CACnB;AAUD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,GACzB,MAAM,CAOR;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAQD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAiBxD;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,EAAE,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,EACzC,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAUlF"}

package/dist/retry.js

@@ -0,0 +1,94 @@
+/**
+ * @novorb/mcp-core — Retry utilities
+ *
+ * Exponential backoff with jitter for retrying failed HTTP requests.
+ */
+const DEFAULT_OPTIONS = {
+    maxRetries: 3,
+    initialDelayMs: 1000,
+    maxDelayMs: 10000,
+    backoffMultiplier: 2,
+    jitterFactor: 0.1,
+};
+/**
+ * Calculate retry delay with exponential backoff and jitter.
+ */
+export function calculateRetryDelay(attempt, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const exponentialDelay = opts.initialDelayMs * Math.pow(opts.backoffMultiplier, attempt);
+    const cappedDelay = Math.min(exponentialDelay, opts.maxDelayMs);
+    const jitterRange = cappedDelay * opts.jitterFactor;
+    const jitter = (Math.random() * 2 - 1) * jitterRange;
+    return Math.max(0, cappedDelay + jitter);
+}
+/**
+ * Sleep for specified milliseconds.
+ */
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/** HTTP status codes that should be retried */
+const RETRYABLE_STATUS_CODES = [408, 429, 502, 503, 504];
+/** Network error codes that should be retried */
+const RETRYABLE_NETWORK_CODES = ['ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'ECONNREFUSED'];
+/**
+ * Determine if an error is retryable.
+ */
+export function isRetryableError(error) {
+    if (error && typeof error === 'object') {
+        const err = error;
+        // Network errors
+        if (typeof err.code === 'string' && RETRYABLE_NETWORK_CODES.includes(err.code)) {
+            return true;
+        }
+        // HTTP status codes
+        const response = err.response;
+        const status = response?.status;
+        if (typeof status === 'number') {
+            return RETRYABLE_STATUS_CODES.includes(status);
+        }
+    }
+    return false;
+}
+/**
+ * Retry a function with exponential backoff.
+ *
+ * @param fn - Async function to retry (receives RetryContext)
+ * @param options - Retry options
+ * @returns Result of successful function call
+ * @throws Last error if all retries exhausted or error is not retryable
+ */
+export async function retryWithBackoff(fn, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    let lastError;
+    for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+        const context = { attempt, maxRetries: opts.maxRetries, lastError };
+        try {
+            return await fn(context);
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === opts.maxRetries || !isRetryableError(error)) {
+                throw error;
+            }
+            const delay = calculateRetryDelay(attempt, options);
+            await sleep(delay);
+        }
+    }
+    throw lastError || new Error('Retry exhausted');
+}
+/**
+ * Parse Retry-After header value to milliseconds.
+ */
+export function parseRetryAfter(retryAfter) {
+    if (!retryAfter)
+        return undefined;
+    const seconds = parseInt(retryAfter, 10);
+    if (!isNaN(seconds))
+        return seconds * 1000;
+    const date = new Date(retryAfter);
+    if (!isNaN(date.getTime()))
+        return Math.max(0, date.getTime() - Date.now());
+    return undefined;
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @novorb/mcp-core — Server
+ *
+ * Re-exports and base patterns for building MCP servers with the high-level McpServer API.
+ * Import from here instead of the SDK directly — one centralised import point for all
+ * server-building primitives.
+ *
+ * Usage:
+ *   import { createMcpServer, TOOL_ANNOTATIONS, completable } from '@novorb/mcp-core/server';
+ *   import type { McpToolAnnotations, McpCallToolResult } from '@novorb/mcp-core/server';
+ *
+ *   const server = createMcpServer('my-mcp', '1.0.0');
+ *
+ *   server.registerTool('lookup', {
+ *     description: 'Look up data by key',
+ *     inputSchema: { key: z.string() },
+ *     outputSchema: { value: z.string(), found: z.boolean() },
+ *     annotations: TOOL_ANNOTATIONS.readOnly,
+ *   }, async ({ key }) => {
+ *     const value = await lookup(key);
+ *     return {
+ *       content: [{ type: 'text', text: value ?? 'not found' }],
+ *       structuredContent: { value: value ?? '', found: value !== null },
+ *     };
+ *   });
+ *
+ *   server.registerPrompt('find-and-summarise', {
+ *     title: 'Find and summarise',
+ *     description: 'Look up a key and summarise the value',
+ *     argsSchema: { key: completable(z.string(), val => ['foo', 'bar'].filter(k => k.startsWith(val))) },
+ *   }, ({ key }) => ({
+ *     messages: [{ role: 'user', content: { type: 'text', text: `Look up "${key}" and summarise the result.` } }],
+ *   }));
+ */
+export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { completable } from '@modelcontextprotocol/sdk/server/completable.js';
+export type { ToolAnnotations as McpToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+export type { CallToolResult as McpCallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Standard tool annotation presets.
+ *
+ * Pass one of these (or a spread of multiple) to `annotations` in `registerTool`.
+ * These are HINTS — clients may or may not act on them.
+ *
+ * @example
+ *   annotations: TOOL_ANNOTATIONS.readOnly
+ *   annotations: { ...TOOL_ANNOTATIONS.readOnly, title: 'Domain lookup' }
+ */
+export declare const TOOL_ANNOTATIONS: {
+    /** Read-only, safe-to-retry. Use for all lookup / search / status tools. */
+    readonly readOnly: {
+        readOnlyHint: true;
+        idempotentHint: true;
+    };
+    /** Write that is idempotent (calling N times = calling once). */
+    readonly idempotentWrite: {
+        readOnlyHint: false;
+        idempotentHint: true;
+    };
+    /** Mutating write that may behave differently on repeat calls. */
+    readonly mutableWrite: {
+        readOnlyHint: false;
+        idempotentHint: false;
+    };
+    /** Destructive / irreversible (delete, overwrite). */
+    readonly destructive: {
+        readOnlyHint: false;
+        destructiveHint: true;
+        idempotentHint: false;
+    };
+};
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Create a pre-configured McpServer instance.
+ *
+ * Thin wrapper kept so individual servers import only from @novorb/mcp-core and
+ * don't carry a direct @modelcontextprotocol/sdk import.
+ */
+export declare function createMcpServer(name: string, version: string): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,iDAAiD,CAAC;AAC9E,YAAY,EAAE,eAAe,IAAI,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAChG,YAAY,EAAE,cAAc,IAAI,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAQ9F;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;IAC3B,4EAA4E;;;;;IAE5E,iEAAiE;;;;;IAEjE,kEAAkE;;;;;IAElE,sDAAsD;;;;;;CAE9C,CAAC;AAMX,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAExE"}

package/dist/server.js

@@ -0,0 +1,73 @@
+/**
+ * @novorb/mcp-core — Server
+ *
+ * Re-exports and base patterns for building MCP servers with the high-level McpServer API.
+ * Import from here instead of the SDK directly — one centralised import point for all
+ * server-building primitives.
+ *
+ * Usage:
+ *   import { createMcpServer, TOOL_ANNOTATIONS, completable } from '@novorb/mcp-core/server';
+ *   import type { McpToolAnnotations, McpCallToolResult } from '@novorb/mcp-core/server';
+ *
+ *   const server = createMcpServer('my-mcp', '1.0.0');
+ *
+ *   server.registerTool('lookup', {
+ *     description: 'Look up data by key',
+ *     inputSchema: { key: z.string() },
+ *     outputSchema: { value: z.string(), found: z.boolean() },
+ *     annotations: TOOL_ANNOTATIONS.readOnly,
+ *   }, async ({ key }) => {
+ *     const value = await lookup(key);
+ *     return {
+ *       content: [{ type: 'text', text: value ?? 'not found' }],
+ *       structuredContent: { value: value ?? '', found: value !== null },
+ *     };
+ *   });
+ *
+ *   server.registerPrompt('find-and-summarise', {
+ *     title: 'Find and summarise',
+ *     description: 'Look up a key and summarise the value',
+ *     argsSchema: { key: completable(z.string(), val => ['foo', 'bar'].filter(k => k.startsWith(val))) },
+ *   }, ({ key }) => ({
+ *     messages: [{ role: 'user', content: { type: 'text', text: `Look up "${key}" and summarise the result.` } }],
+ *   }));
+ */
+// ---------------------------------------------------------------------------
+// Re-exports — individual servers import ONLY from @novorb/mcp-core
+// ---------------------------------------------------------------------------
+export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { completable } from '@modelcontextprotocol/sdk/server/completable.js';
+/**
+ * Standard tool annotation presets.
+ *
+ * Pass one of these (or a spread of multiple) to `annotations` in `registerTool`.
+ * These are HINTS — clients may or may not act on them.
+ *
+ * @example
+ *   annotations: TOOL_ANNOTATIONS.readOnly
+ *   annotations: { ...TOOL_ANNOTATIONS.readOnly, title: 'Domain lookup' }
+ */
+export const TOOL_ANNOTATIONS = {
+    /** Read-only, safe-to-retry. Use for all lookup / search / status tools. */
+    readOnly: { readOnlyHint: true, idempotentHint: true },
+    /** Write that is idempotent (calling N times = calling once). */
+    idempotentWrite: { readOnlyHint: false, idempotentHint: true },
+    /** Mutating write that may behave differently on repeat calls. */
+    mutableWrite: { readOnlyHint: false, idempotentHint: false },
+    /** Destructive / irreversible (delete, overwrite). */
+    destructive: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+};
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Create a pre-configured McpServer instance.
+ *
+ * Thin wrapper kept so individual servers import only from @novorb/mcp-core and
+ * don't carry a direct @modelcontextprotocol/sdk import.
+ */
+export function createMcpServer(name, version) {
+    return new McpServer({ name, version });
+}
+//# sourceMappingURL=server.js.map