@forestadmin/mcp-server 0.1.0

package/dist/utils/schema-fetcher.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Schema Fetcher Utility
+ *
+ * Fetches the Forest Admin schema from the `/liana/forest-schema` endpoint
+ * and caches it for 24 hours.
+ */
+export interface ForestField {
+    field: string;
+    type: string;
+    isFilterable?: boolean;
+    isSortable?: boolean;
+    enum: string[] | null;
+    inverseOf?: string | null;
+    reference: string | null;
+    isReadOnly: boolean;
+    isRequired: boolean;
+    integration?: string | null;
+    validations?: unknown[];
+    defaultValue?: unknown;
+    isPrimaryKey: boolean;
+}
+export interface ForestCollection {
+    name: string;
+    fields: ForestField[];
+}
+export interface ForestSchema {
+    collections: ForestCollection[];
+}
+/**
+ * Fetches the Forest Admin schema from the server.
+ * The schema is cached for 24 hours to reduce API calls.
+ *
+ * @param forestServerUrl - The Forest Admin server URL
+ * @returns The Forest Admin schema containing collections
+ */
+export declare function fetchForestSchema(forestServerUrl: string): Promise<ForestSchema>;
+/**
+ * Extracts collection names from the Forest Admin schema.
+ *
+ * @param schema - The Forest Admin schema
+ * @returns Array of collection names
+ */
+export declare function getCollectionNames(schema: ForestSchema): string[];
+export declare function getFieldsOfCollection(schema: ForestSchema, collectionName: string): ForestField[];
+/**
+ * Clears the schema cache. Useful for testing.
+ */
+export declare function clearSchemaCache(): void;
+/**
+ * Sets the schema cache. Useful for testing.
+ */
+export declare function setSchemaCache(schema: ForestSchema, fetchedAt?: number): void;
+//# sourceMappingURL=schema-fetcher.d.ts.map

package/dist/utils/schema-fetcher.js

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchForestSchema = fetchForestSchema;
+exports.getCollectionNames = getCollectionNames;
+exports.getFieldsOfCollection = getFieldsOfCollection;
+exports.clearSchemaCache = clearSchemaCache;
+exports.setSchemaCache = setSchemaCache;
+const jsonapi_serializer_1 = __importDefault(require("jsonapi-serializer"));
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+let schemaCache = null;
+/**
+ * Fetches the Forest Admin schema from the server.
+ * The schema is cached for 24 hours to reduce API calls.
+ *
+ * @param forestServerUrl - The Forest Admin server URL
+ * @returns The Forest Admin schema containing collections
+ */
+async function fetchForestSchema(forestServerUrl) {
+    const now = Date.now();
+    // Return cached schema if it's still valid (less than 24 hours old)
+    if (schemaCache && now - schemaCache.fetchedAt < ONE_DAY_MS) {
+        return schemaCache.schema;
+    }
+    const envSecret = process.env.FOREST_ENV_SECRET;
+    if (!envSecret) {
+        throw new Error('FOREST_ENV_SECRET environment variable is not set');
+    }
+    const response = await fetch(`${forestServerUrl}/liana/forest-schema`, {
+        method: 'GET',
+        headers: {
+            'forest-secret-key': envSecret,
+            'Content-Type': 'application/json',
+        },
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Failed to fetch forest schema: ${errorText}`);
+    }
+    const schema = (await response.json());
+    const serializer = new jsonapi_serializer_1.default.Deserializer({
+        keyForAttribute: 'camelCase',
+    });
+    const collections = (await serializer.deserialize(schema));
+    // Update cache
+    schemaCache = {
+        schema: { collections },
+        fetchedAt: now,
+    };
+    return { collections };
+}
+/**
+ * Extracts collection names from the Forest Admin schema.
+ *
+ * @param schema - The Forest Admin schema
+ * @returns Array of collection names
+ */
+function getCollectionNames(schema) {
+    return schema.collections.map(collection => collection.name);
+}
+function getFieldsOfCollection(schema, collectionName) {
+    const collection = schema.collections.find(col => col.name === collectionName);
+    if (!collection) {
+        throw new Error(`Collection "${collectionName}" not found in schema`);
+    }
+    return collection.fields;
+}
+/**
+ * Clears the schema cache. Useful for testing.
+ */
+function clearSchemaCache() {
+    schemaCache = null;
+}
+/**
+ * Sets the schema cache. Useful for testing.
+ */
+function setSchemaCache(schema, fetchedAt) {
+    schemaCache = {
+        schema,
+        fetchedAt: fetchedAt ?? Date.now(),
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2NoZW1hLWZldGNoZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdXRpbHMvc2NoZW1hLWZldGNoZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7QUF5REEsOENBNENDO0FBUUQsZ0RBRUM7QUFFRCxzREFRQztBQUtELDRDQUVDO0FBS0Qsd0NBS0M7QUExSUQsNEVBQW1EO0FBOENuRCxNQUFNLFVBQVUsR0FBRyxFQUFFLEdBQUcsRUFBRSxHQUFHLEVBQUUsR0FBRyxJQUFJLENBQUM7QUFFdkMsSUFBSSxXQUFXLEdBQXVCLElBQUksQ0FBQztBQUUzQzs7Ozs7O0dBTUc7QUFDSSxLQUFLLFVBQVUsaUJBQWlCLENBQUMsZUFBdUI7SUFDN0QsTUFBTSxHQUFHLEdBQUcsSUFBSSxDQUFDLEdBQUcsRUFBRSxDQUFDO0lBRXZCLG9FQUFvRTtJQUNwRSxJQUFJLFdBQVcsSUFBSSxHQUFHLEdBQUcsV0FBVyxDQUFDLFNBQVMsR0FBRyxVQUFVLEVBQUUsQ0FBQztRQUM1RCxPQUFPLFdBQVcsQ0FBQyxNQUFNLENBQUM7SUFDNUIsQ0FBQztJQUVELE1BQU0sU0FBUyxHQUFHLE9BQU8sQ0FBQyxHQUFHLENBQUMsaUJBQWlCLENBQUM7SUFFaEQsSUFBSSxDQUFDLFNBQVMsRUFBRSxDQUFDO1FBQ2YsTUFBTSxJQUFJLEtBQUssQ0FBQyxtREFBbUQsQ0FBQyxDQUFDO0lBQ3ZFLENBQUM7SUFFRCxNQUFNLFFBQVEsR0FBRyxNQUFNLEtBQUssQ0FBQyxHQUFHLGVBQWUsc0JBQXNCLEVBQUU7UUFDckUsTUFBTSxFQUFFLEtBQUs7UUFDYixPQUFPLEVBQUU7WUFDUCxtQkFBbUIsRUFBRSxTQUFTO1lBQzlCLGNBQWMsRUFBRSxrQkFBa0I7U0FDbkM7S0FDRixDQUFDLENBQUM7SUFFSCxJQUFJLENBQUMsUUFBUSxDQUFDLEVBQUUsRUFBRSxDQUFDO1FBQ2pCLE1BQU0sU0FBUyxHQUFHLE1BQU0sUUFBUSxDQUFDLElBQUksRUFBRSxDQUFDO1FBQ3hDLE1BQU0sSUFBSSxLQUFLLENBQUMsa0NBQWtDLFNBQVMsRUFBRSxDQUFDLENBQUM7SUFDakUsQ0FBQztJQUVELE1BQU0sTUFBTSxHQUFHLENBQUMsTUFBTSxRQUFRLENBQUMsSUFBSSxFQUFFLENBSXBDLENBQUM7SUFDRixNQUFNLFVBQVUsR0FBRyxJQUFJLDRCQUFpQixDQUFDLFlBQVksQ0FBQztRQUNwRCxlQUFlLEVBQUUsV0FBVztLQUM3QixDQUFDLENBQUM7SUFDSCxNQUFNLFdBQVcsR0FBRyxDQUFDLE1BQU0sVUFBVSxDQUFDLFdBQVcsQ0FBQyxNQUFNLENBQUMsQ0FBdUIsQ0FBQztJQUVqRixlQUFlO0lBQ2YsV0FBVyxHQUFHO1FBQ1osTUFBTSxFQUFFLEVBQUUsV0FBVyxFQUFFO1FBQ3ZCLFNBQVMsRUFBRSxHQUFHO0tBQ2YsQ0FBQztJQUVGLE9BQU8sRUFBRSxXQUFXLEVBQUUsQ0FBQztBQUN6QixDQUFDO0FBRUQ7Ozs7O0dBS0c7QUFDSCxTQUFnQixrQkFBa0IsQ0FBQyxNQUFvQjtJQUNyRCxPQUFPLE1BQU0sQ0FBQyxXQUFXLENBQUMsR0FBRyxDQUFDLFVBQVUsQ0FBQyxFQUFFLENBQUMsVUFBVSxDQUFDLElBQUksQ0FBQyxDQUFDO0FBQy9ELENBQUM7QUFFRCxTQUFnQixxQkFBcUIsQ0FBQyxNQUFvQixFQUFFLGNBQXNCO0lBQ2hGLE1BQU0sVUFBVSxHQUFHLE1BQU0sQ0FBQyxXQUFXLENBQUMsSUFBSSxDQUFDLEdBQUcsQ0FBQyxFQUFFLENBQUMsR0FBRyxDQUFDLElBQUksS0FBSyxjQUFjLENBQUMsQ0FBQztJQUUvRSxJQUFJLENBQUMsVUFBVSxFQUFFLENBQUM7UUFDaEIsTUFBTSxJQUFJLEtBQUssQ0FBQyxlQUFlLGNBQWMsdUJBQXVCLENBQUMsQ0FBQztJQUN4RSxDQUFDO0lBRUQsT0FBTyxVQUFVLENBQUMsTUFBTSxDQUFDO0FBQzNCLENBQUM7QUFFRDs7R0FFRztBQUNILFNBQWdCLGdCQUFnQjtJQUM5QixXQUFXLEdBQUcsSUFBSSxDQUFDO0FBQ3JCLENBQUM7QUFFRDs7R0FFRztBQUNILFNBQWdCLGNBQWMsQ0FBQyxNQUFvQixFQUFFLFNBQWtCO0lBQ3JFLFdBQVcsR0FBRztRQUNaLE1BQU07UUFDTixTQUFTLEVBQUUsU0FBUyxJQUFJLElBQUksQ0FBQyxHQUFHLEVBQUU7S0FDbkMsQ0FBQztBQUNKLENBQUMifQ==

package/dist/utils/schema-fetcher.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schema-fetcher.test.d.ts.map

package/dist/utils/schema-fetcher.test.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const schema_fetcher_1 = require("./schema-fetcher");
+describe('schema-fetcher', () => {
+    const originalFetch = global.fetch;
+    const originalEnv = process.env.FOREST_ENV_SECRET;
+    let mockFetch;
+    beforeEach(() => {
+        mockFetch = jest.fn();
+        global.fetch = mockFetch;
+        process.env.FOREST_ENV_SECRET = 'test-env-secret';
+        (0, schema_fetcher_1.clearSchemaCache)();
+    });
+    afterAll(() => {
+        global.fetch = originalFetch;
+        process.env.FOREST_ENV_SECRET = originalEnv;
+    });
+    // Helper to create JSON:API formatted schema response
+    const createJsonApiSchema = (collections) => ({
+        data: collections.map((col, index) => ({
+            id: `collection-${index}`,
+            type: 'collections',
+            attributes: {
+                name: col.name,
+                fields: col.fields,
+            },
+        })),
+        meta: {
+            liana: 'forest-express-sequelize',
+            liana_version: '9.0.0',
+            liana_features: null,
+        },
+    });
+    describe('fetchForestSchema', () => {
+        const mockJsonApiResponse = createJsonApiSchema([
+            { name: 'users', fields: [{ field: 'id', type: 'Number' }] },
+            { name: 'products', fields: [{ field: 'name', type: 'String' }] },
+        ]);
+        it('should fetch schema from forest server and deserialize JSON:API response', async () => {
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve(mockJsonApiResponse),
+            });
+            const result = await (0, schema_fetcher_1.fetchForestSchema)('https://api.forestadmin.com');
+            expect(mockFetch).toHaveBeenCalledWith('https://api.forestadmin.com/liana/forest-schema', {
+                method: 'GET',
+                headers: {
+                    'forest-secret-key': 'test-env-secret',
+                    'Content-Type': 'application/json',
+                },
+            });
+            expect(result.collections).toHaveLength(2);
+            expect(result.collections[0].name).toBe('users');
+            expect(result.collections[1].name).toBe('products');
+        });
+        it('should use cached schema on subsequent calls', async () => {
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve(mockJsonApiResponse),
+            });
+            const result1 = await (0, schema_fetcher_1.fetchForestSchema)('https://api.forestadmin.com');
+            const result2 = await (0, schema_fetcher_1.fetchForestSchema)('https://api.forestadmin.com');
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            expect(result1).toEqual(result2);
+        });
+        it('should refetch schema after cache expires (24 hours)', async () => {
+            const oldSchema = {
+                collections: [{ name: 'old_collection', fields: [] }],
+            };
+            const newJsonApiResponse = createJsonApiSchema([{ name: 'new_collection', fields: [] }]);
+            // Set cache with an old timestamp (more than 24 hours ago)
+            const oneDayAgo = Date.now() - 25 * 60 * 60 * 1000;
+            (0, schema_fetcher_1.setSchemaCache)(oldSchema, oneDayAgo);
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve(newJsonApiResponse),
+            });
+            const result = await (0, schema_fetcher_1.fetchForestSchema)('https://api.forestadmin.com');
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            expect(result.collections).toHaveLength(1);
+            expect(result.collections[0].name).toBe('new_collection');
+        });
+        it('should not refetch schema before cache expires', async () => {
+            const cachedSchema = {
+                collections: [{ name: 'cached_collection', fields: [] }],
+            };
+            // Set cache with a recent timestamp (less than 24 hours ago)
+            const recentTime = Date.now() - 1 * 60 * 60 * 1000; // 1 hour ago
+            (0, schema_fetcher_1.setSchemaCache)(cachedSchema, recentTime);
+            const result = await (0, schema_fetcher_1.fetchForestSchema)('https://api.forestadmin.com');
+            expect(mockFetch).not.toHaveBeenCalled();
+            expect(result).toEqual(cachedSchema);
+        });
+        it('should throw error when FOREST_ENV_SECRET is not set', async () => {
+            delete process.env.FOREST_ENV_SECRET;
+            await expect((0, schema_fetcher_1.fetchForestSchema)('https://api.forestadmin.com')).rejects.toThrow('FOREST_ENV_SECRET environment variable is not set');
+        });
+        it('should throw error when response is not ok', async () => {
+            mockFetch.mockResolvedValue({
+                ok: false,
+                text: () => Promise.resolve('Server error message'),
+            });
+            await expect((0, schema_fetcher_1.fetchForestSchema)('https://api.forestadmin.com')).rejects.toThrow('Failed to fetch forest schema: Server error message');
+        });
+        it('should use custom forest server URL', async () => {
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve(mockJsonApiResponse),
+            });
+            await (0, schema_fetcher_1.fetchForestSchema)('https://custom.forestadmin.com');
+            expect(mockFetch).toHaveBeenCalledWith('https://custom.forestadmin.com/liana/forest-schema', expect.any(Object));
+        });
+    });
+    describe('getCollectionNames', () => {
+        it('should extract collection names from schema', () => {
+            const schema = {
+                collections: [
+                    { name: 'users', fields: [] },
+                    { name: 'products', fields: [] },
+                    { name: 'orders', fields: [] },
+                ],
+            };
+            const result = (0, schema_fetcher_1.getCollectionNames)(schema);
+            expect(result).toEqual(['users', 'products', 'orders']);
+        });
+        it('should return empty array for empty collections', () => {
+            const schema = {
+                collections: [],
+            };
+            const result = (0, schema_fetcher_1.getCollectionNames)(schema);
+            expect(result).toEqual([]);
+        });
+    });
+    describe('clearSchemaCache', () => {
+        // Helper to create JSON:API formatted schema response
+        const createJsonApiSchema = (collections) => ({
+            data: collections.map((col, index) => ({
+                id: `collection-${index}`,
+                type: 'collections',
+                attributes: {
+                    name: col.name,
+                    fields: col.fields,
+                },
+            })),
+            meta: {
+                liana: 'forest-express-sequelize',
+                liana_version: '9.0.0',
+                liana_features: null,
+            },
+        });
+        it('should clear the cache so next fetch makes API call', async () => {
+            const jsonApiResponse = createJsonApiSchema([{ name: 'test', fields: [] }]);
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve(jsonApiResponse),
+            });
+            // First fetch
+            await (0, schema_fetcher_1.fetchForestSchema)('https://api.forestadmin.com');
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            // Clear cache
+            (0, schema_fetcher_1.clearSchemaCache)();
+            // Second fetch should make API call
+            await (0, schema_fetcher_1.fetchForestSchema)('https://api.forestadmin.com');
+            expect(mockFetch).toHaveBeenCalledTimes(2);
+        });
+    });
+    describe('setSchemaCache', () => {
+        // Helper to create JSON:API formatted schema response
+        const createJsonApiSchema = (collections) => ({
+            data: collections.map((col, index) => ({
+                id: `collection-${index}`,
+                type: 'collections',
+                attributes: {
+                    name: col.name,
+                    fields: col.fields,
+                },
+            })),
+            meta: {
+                liana: 'forest-express-sequelize',
+                liana_version: '9.0.0',
+                liana_features: null,
+            },
+        });
+        it('should set cache with current timestamp by default', async () => {
+            const schema = {
+                collections: [{ name: 'cached', fields: [] }],
+            };
+            (0, schema_fetcher_1.setSchemaCache)(schema);
+            const result = await (0, schema_fetcher_1.fetchForestSchema)('https://api.forestadmin.com');
+            expect(mockFetch).not.toHaveBeenCalled();
+            expect(result).toEqual(schema);
+        });
+        it('should set cache with custom timestamp', async () => {
+            const schema = {
+                collections: [{ name: 'old_cached', fields: [] }],
+            };
+            const newJsonApiResponse = createJsonApiSchema([{ name: 'new', fields: [] }]);
+            // Set cache with old timestamp
+            const oldTime = Date.now() - 25 * 60 * 60 * 1000;
+            (0, schema_fetcher_1.setSchemaCache)(schema, oldTime);
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve(newJsonApiResponse),
+            });
+            const result = await (0, schema_fetcher_1.fetchForestSchema)('https://api.forestadmin.com');
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            expect(result.collections).toHaveLength(1);
+            expect(result.collections[0].name).toBe('new');
+        });
+    });
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2NoZW1hLWZldGNoZXIudGVzdC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy91dGlscy9zY2hlbWEtZmV0Y2hlci50ZXN0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBQUEscURBTTBCO0FBRTFCLFFBQVEsQ0FBQyxnQkFBZ0IsRUFBRSxHQUFHLEVBQUU7SUFDOUIsTUFBTSxhQUFhLEdBQUcsTUFBTSxDQUFDLEtBQUssQ0FBQztJQUNuQyxNQUFNLFdBQVcsR0FBRyxPQUFPLENBQUMsR0FBRyxDQUFDLGlCQUFpQixDQUFDO0lBQ2xELElBQUksU0FBb0IsQ0FBQztJQUV6QixVQUFVLENBQUMsR0FBRyxFQUFFO1FBQ2QsU0FBUyxHQUFHLElBQUksQ0FBQyxFQUFFLEVBQUUsQ0FBQztRQUN0QixNQUFNLENBQUMsS0FBSyxHQUFHLFNBQVMsQ0FBQztRQUN6QixPQUFPLENBQUMsR0FBRyxDQUFDLGlCQUFpQixHQUFHLGlCQUFpQixDQUFDO1FBQ2xELElBQUEsaUNBQWdCLEdBQUUsQ0FBQztJQUNyQixDQUFDLENBQUMsQ0FBQztJQUVILFFBQVEsQ0FBQyxHQUFHLEVBQUU7UUFDWixNQUFNLENBQUMsS0FBSyxHQUFHLGFBQWEsQ0FBQztRQUM3QixPQUFPLENBQUMsR0FBRyxDQUFDLGlCQUFpQixHQUFHLFdBQVcsQ0FBQztJQUM5QyxDQUFDLENBQUMsQ0FBQztJQUVILHNEQUFzRDtJQUN0RCxNQUFNLG1CQUFtQixHQUFHLENBQzFCLFdBQW9GLEVBQ3BGLEVBQUUsQ0FBQyxDQUFDO1FBQ0osSUFBSSxFQUFFLFdBQVcsQ0FBQyxHQUFHLENBQUMsQ0FBQyxHQUFHLEVBQUUsS0FBSyxFQUFFLEVBQUUsQ0FBQyxDQUFDO1lBQ3JDLEVBQUUsRUFBRSxjQUFjLEtBQUssRUFBRTtZQUN6QixJQUFJLEVBQUUsYUFBYTtZQUNuQixVQUFVLEVBQUU7Z0JBQ1YsSUFBSSxFQUFFLEdBQUcsQ0FBQyxJQUFJO2dCQUNkLE1BQU0sRUFBRSxHQUFHLENB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

package/dist/utils/sse-error-logger.d.ts

@@ -0,0 +1,14 @@
+import type { Logger } from '../server.js';
+import type { Response } from 'express';
+/**
+ * Wraps an Express response to intercept and log MCP errors from SSE streams.
+ *
+ * Why we need this:
+ * The MCP SDK sends errors as SSE events, not HTTP errors. To log these errors
+ * server-side, we intercept the response stream and parse each chunk for errors.
+ *
+ * This function modifies res.write() and res.end() to add logging without
+ * affecting the actual response sent to the client.
+ */
+export default function interceptResponseForErrorLogging(res: Response, logger: Logger): void;
+//# sourceMappingURL=sse-error-logger.d.ts.map

package/dist/utils/sse-error-logger.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = interceptResponseForErrorLogging;
+// -----------------------------------------------------------------------------
+// Chunk Conversion
+// -----------------------------------------------------------------------------
+/**
+ * Converts various chunk types to a UTF-8 string.
+ * Handles Buffer, Uint8Array, and string inputs.
+ */
+function chunkToString(chunk) {
+    if (typeof chunk === 'string') {
+        return chunk;
+    }
+    if (Buffer.isBuffer(chunk)) {
+        return chunk.toString('utf8');
+    }
+    return new TextDecoder('utf8').decode(chunk);
+}
+// -----------------------------------------------------------------------------
+// SSE Parsing
+// -----------------------------------------------------------------------------
+/**
+ * Extracts the JSON payload from an SSE data line.
+ * SSE format: "event: message\ndata: {...}\n\n"
+ */
+function extractJsonFromSseData(data) {
+    const match = data.match(/data:\s*({.+})/s);
+    return match ? match[1] : null;
+}
+/**
+ * Parses SSE data and logs any MCP errors found.
+ *
+ * MCP errors come in two forms:
+ * 1. JSON-RPC errors: { error: { message: "..." } }
+ * 2. Tool errors: { result: { isError: true, content: [{ text: "..." }] } }
+ */
+function parseAndLogMcpErrors(data, logger) {
+    const jsonString = extractJsonFromSseData(data);
+    if (!jsonString) {
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonString);
+    }
+    catch (error) {
+        // SyntaxError is expected for non-JSON SSE events (like "ping")
+        if (!(error instanceof SyntaxError)) {
+            logger('Warn', `[MCP] Failed to parse SSE response: ${error}`);
+        }
+        return;
+    }
+    // Log JSON-RPC level errors
+    if (parsed.error?.message) {
+        logger('Error', `[MCP] ${parsed.error.message}`);
+    }
+    // Log tool execution errors (isError: true in result)
+    if (parsed.result?.isError) {
+        const errorText = parsed.result.content?.[0]?.text || 'Unknown error';
+        logger('Error', `[MCP] Tool error: ${errorText}`);
+    }
+}
+// -----------------------------------------------------------------------------
+// Response Chunk Logging
+// -----------------------------------------------------------------------------
+/**
+ * Safely attempts to log errors from a response chunk.
+ * Never throws - logging failures should not affect the response.
+ */
+function logChunkErrors(chunk, logger) {
+    if (chunk == null) {
+        return;
+    }
+    try {
+        const data = chunkToString(chunk);
+        parseAndLogMcpErrors(data, logger);
+    }
+    catch (error) {
+        logger('Warn', `[MCP] Failed to parse response for error logging: ${error}`);
+    }
+}
+// -----------------------------------------------------------------------------
+// Response Interceptor
+// -----------------------------------------------------------------------------
+/**
+ * Wraps an Express response to intercept and log MCP errors from SSE streams.
+ *
+ * Why we need this:
+ * The MCP SDK sends errors as SSE events, not HTTP errors. To log these errors
+ * server-side, we intercept the response stream and parse each chunk for errors.
+ *
+ * This function modifies res.write() and res.end() to add logging without
+ * affecting the actual response sent to the client.
+ */
+function interceptResponseForErrorLogging(res, logger) {
+    const originalWrite = res.write.bind(res);
+    const originalEnd = res.end.bind(res);
+    // Intercept streaming chunks (res.write)
+    res.write = function interceptedWrite(chunk, encodingOrCallback, callback) {
+        logChunkErrors(chunk, logger);
+        return originalWrite(chunk, encodingOrCallback, callback);
+    };
+    // Intercept final chunk (res.end)
+    res.end = function interceptedEnd(chunk, encodingOrCallback, callback) {
+        if (chunk && typeof chunk !== 'function') {
+            logChunkErrors(chunk, logger);
+        }
+        return originalEnd(chunk, encodingOrCallback, callback);
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3NlLWVycm9yLWxvZ2dlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy91dGlscy9zc2UtZXJyb3ItbG9nZ2VyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBZ0lBLG1EQTJCQztBQTFJRCxnRkFBZ0Y7QUFDaEYsbUJBQW1CO0FBQ25CLGdGQUFnRjtBQUVoRjs7O0dBR0c7QUFDSCxTQUFTLGFBQWEsQ0FBQyxLQUFtQztJQUN4RCxJQUFJLE9BQU8sS0FBSyxLQUFLLFFBQVEsRUFBRSxDQUFDO1FBQzlCLE9BQU8sS0FBSyxDQUFDO0lBQ2YsQ0FBQztJQUVELElBQUksTUFBTSxDQUFDLFFBQVEsQ0FBQyxLQUFLLENBQUMsRUFBRSxDQUFDO1FBQzNCLE9BQU8sS0FBSyxDQUFDLFFBQVEsQ0FBQyxNQUFNLENBQUMsQ0FBQztJQUNoQyxDQUFDO0lBRUQsT0FBTyxJQUFJLFdBQVcsQ0FBQyxNQUFNLENBQUMsQ0FBQyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUM7QUFDL0MsQ0FBQztBQUVELGdGQUFnRjtBQUNoRixjQUFjO0FBQ2QsZ0ZBQWdGO0FBRWhGOzs7R0FHRztBQUNILFNBQVMsc0JBQXNCLENBQUMsSUFBWTtJQUMxQyxNQUFNLEtBQUssR0FBRyxJQUFJLENBQUMsS0FBSyxDQUFDLGlCQUFpQixDQUFDLENBQUM7SUFFNUMsT0FBTyxLQUFLLENBQUMsQ0FBQyxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsSUFBSSxDQUFDO0FBQ2pDLENBQUM7QUFFRDs7Ozs7O0dBTUc7QUFDSCxTQUFTLG9CQUFvQixDQUFDLElBQVksRUFBRSxNQUFjO0lBQ3hELE1BQU0sVUFBVSxHQUFHLHNCQUFzQixDQUFDLElBQUksQ0FBQyxDQUFDO0lBRWhELElBQUksQ0FBQyxVQUFVLEVBQUUsQ0FBQztRQUNoQixPQUFPO0lBQ1QsQ0FBQztJQUVELElBQUksTUFBMEIsQ0FBQztJQUUvQixJQUFJLENBQUM7UUFDSCxNQUFNLEdB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

package/dist/utils/tool-with-logging.d.ts

@@ -0,0 +1,44 @@
+import type { Logger } from '../server.js';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+type ZodRawShape = Record<string, z.ZodTypeAny>;
+interface ToolConfig<TSchema extends ZodRawShape> {
+    title: string;
+    description: string;
+    inputSchema: TSchema;
+}
+type ToolResult = {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: boolean;
+};
+/**
+ * Registers an MCP tool with automatic validation error logging.
+ *
+ * This wrapper logs validation errors with detailed field information,
+ * which helps debug tool calls when clients send invalid arguments.
+ *
+ * Note: Execution errors are logged by the SSE response interceptor in server.ts,
+ * so we don't duplicate that logging here.
+ *
+ * @example
+ * registerToolWithLogging(
+ *   mcpServer,
+ *   'list',
+ *   {
+ *     title: 'List Records',
+ *     description: 'Lists records from a collection',
+ *     inputSchema: { collectionName: z.string() },
+ *   },
+ *   async (args) => {
+ *     const records = await fetchRecords(args.collectionName);
+ *     return { content: [{ type: 'text', text: JSON.stringify(records) }] };
+ *   },
+ *   logger,
+ * );
+ */
+export default function registerToolWithLogging<TSchema extends ZodRawShape, TArgs = z.infer<z.ZodObject<TSchema>>>(mcpServer: McpServer, toolName: string, config: ToolConfig<TSchema>, handler: (args: TArgs, extra: any) => Promise<ToolResult>, logger: Logger): void;
+export {};
+//# sourceMappingURL=tool-with-logging.d.ts.map

package/dist/utils/tool-with-logging.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = registerToolWithLogging;
+const zod_1 = require("zod");
+// -----------------------------------------------------------------------------
+// Validation Helpers
+// -----------------------------------------------------------------------------
+/**
+ * Formats a Zod error into a human-readable string.
+ * Example: "collectionName: Required, sort.field: Expected string"
+ */
+function formatZodError(error) {
+    return error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`).join(', ');
+}
+/**
+ * Validates arguments against a schema and logs errors if validation fails.
+ * This is a pre-validation step for logging purposes only - the SDK handles actual validation.
+ */
+function logValidationErrorsIfAny(args, schema, toolName, logger) {
+    const result = schema.safeParse(args);
+    if (!result.success) {
+        const errorMessage = formatZodError(result.error);
+        logger('Error', `[MCP] Tool "${toolName}" validation error: ${errorMessage}`);
+    }
+}
+// -----------------------------------------------------------------------------
+// Tool Registration
+// -----------------------------------------------------------------------------
+/**
+ * Registers an MCP tool with automatic validation error logging.
+ *
+ * This wrapper logs validation errors with detailed field information,
+ * which helps debug tool calls when clients send invalid arguments.
+ *
+ * Note: Execution errors are logged by the SSE response interceptor in server.ts,
+ * so we don't duplicate that logging here.
+ *
+ * @example
+ * registerToolWithLogging(
+ *   mcpServer,
+ *   'list',
+ *   {
+ *     title: 'List Records',
+ *     description: 'Lists records from a collection',
+ *     inputSchema: { collectionName: z.string() },
+ *   },
+ *   async (args) => {
+ *     const records = await fetchRecords(args.collectionName);
+ *     return { content: [{ type: 'text', text: JSON.stringify(records) }] };
+ *   },
+ *   logger,
+ * );
+ */
+function registerToolWithLogging(mcpServer, toolName, config, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+handler, logger) {
+    const schema = zod_1.z.object(config.inputSchema);
+    mcpServer.registerTool(toolName, config, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (async (args, extra) => {
+        logValidationErrorsIfAny(args, schema, toolName, logger);
+        return handler(args, extra);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }));
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidG9vbC13aXRoLWxvZ2dpbmcuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdXRpbHMvdG9vbC13aXRoLWxvZ2dpbmcudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7QUFpRkEsMENBd0JDO0FBdEdELDZCQUF3QjtBQW1CeEIsZ0ZBQWdGO0FBQ2hGLHFCQUFxQjtBQUNyQixnRkFBZ0Y7QUFFaEY7OztHQUdHO0FBQ0gsU0FBUyxjQUFjLENBQUMsS0FBaUI7SUFDdkMsT0FBTyxLQUFLLENBQUMsTUFBTSxDQUFDLEdBQUcsQ0FBQyxLQUFLLENBQUMsRUFBRSxDQUFDLEdBQUcsS0FBSyxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsR0FBRyxDQUFDLEtBQUssS0FBSyxDQUFDLE9BQU8sRUFBRSxDQUFDLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxDQUFDO0FBQzNGLENBQUM7QUFFRDs7O0dBR0c7QUFDSCxTQUFTLHdCQUF3QixDQUMvQixJQUFhLEVBQ2IsTUFBbUIsRUFDbkIsUUFBZ0IsRUFDaEIsTUFBYztJQUVkLE1BQU0sTUFBTSxHQUFHLE1BQU0sQ0FBQyxTQUFTLENBQUMsSUFBSSxDQUFDLENBQUM7SUFFdEMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxPQUFPLEVBQUUsQ0FBQztRQUNwQixNQUFNLFlBQVksR0FBRyxjQUFjLENBQUMsTUFBTSxDQUFDLEtBQUssQ0FBQyxDQUFDO1FBQ2xELE1BQU0sQ0FBQyxPQUFPLEVBQUUsZUFBZSxRQUFRLHVCQUF1QixZQUFZLEVBQUUsQ0FBQyxDQUFDO0lBQ2hGLENBQUM7QUFDSCxDQUFDO0FBRUQsZ0ZBQWdGO0FBQ2hGLG9CQUFvQjtBQUNwQixnRkFBZ0Y7QUFFaEY7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXdCRztBQUNILFNBQXdCLHVCQUF1QixDQUk3QyxTQUFvQixFQUNwQixRQUFnQixFQUNoQixNQUEyQjtBQUMzQiw4REFBOEQ7QUFDOUQsT0FBeUQsRUFDekQsTUFBYztJQUVkLE1BQU0sTUFBTSxHQUFHLE9BQUMsQ0FBQyxNQUFNLENBQUMsTUFBTSxDQUFDLFdBQVcsQ0FBQyxDQUFDO0lBRTVDLFNBQVMsQ0FBQyxZQUFZLENBQ3BCLFFBQVEsRUFDUixNQUFNO0lBQ04sOERBQThEO0lBQzlELENBQUMsS0FBSyxFQUFFLElBQVMsRUFBRSxLQUFVLEVBQUUsRUFBRTtRQUMvQix3QkFBd0IsQ0FBQyxJQUFJLEVBQUUsTUFBTSxFQUFFLFFBQVEsRUFBRSxNQUFNLENBQUMsQ0FBQztRQUV6RCxPQUFPLE9BQU8sQ0FBQyxJQUFhLEVBQUUsS0FBSyxDQUFDLENBQUM7UUFDckMsOERBQThEO0lBQ2hFLENBQUMsQ0FBUSxDQUNWLENBQUM7QUFDSixDQUFDIn0=

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+export declare const VERSION: string;
+export declare const NAME: string;
+//# sourceMappingURL=version.d.ts.map