@hailer/mcp 1.1.11 → 1.1.13

package/dist/plugins/vipunen/client.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Weaviate HTTP Client
+ *
+ * Lightweight client that talks to Weaviate's GraphQL and REST APIs directly.
+ * No heavy SDK dependency — just fetch calls with proper auth headers.
+ */
+export interface WeaviateClientConfig {
+    host: string;
+    apiKey?: string;
+}
+export interface WhereFilter {
+    path?: string[];
+    operator: string;
+    valueText?: string;
+    valueInt?: number;
+    valueBoolean?: boolean;
+    valueDate?: string;
+    operands?: WhereFilter[];
+}
+export interface WeaviateObject {
+    [key: string]: any;
+}
+export interface WeaviateQueryResult {
+    objects: WeaviateObject[];
+    totalCount?: number;
+}
+export interface WeaviateInsertResult {
+    uuid: string;
+}
+export interface WeaviateDeleteResult {
+    matches: number;
+    successful: number;
+}
+export interface WeaviateBatchInsertResult {
+    inserted: number;
+    errors: number;
+    errorDetails: Array<{
+        index: number;
+        error: string;
+    }>;
+}
+export interface WeaviateExportResult {
+    objects: WeaviateObject[];
+    totalCount: number;
+}
+/**
+ * Thrown when Weaviate returns 401/403 — signals invalid server API key.
+ */
+export declare class WeaviateAuthError extends Error {
+    status: number;
+    constructor(status: number);
+}
+export declare class WeaviateClient {
+    private host;
+    private headers;
+    private static readonly SCHEMA_TTL_MS;
+    private schemaCache;
+    constructor(config: WeaviateClientConfig);
+    /**
+     * Shared fetch with auth-error and response-error handling.
+     * All HTTP calls go through this to avoid repeating 401/403 checks.
+     */
+    private _fetch;
+    /**
+     * Execute a GraphQL query against Weaviate
+     */
+    graphql(query: string, variables?: Record<string, any>): Promise<any>;
+    /**
+     * Hybrid search (BM25 + vector) — the main query tool
+     */
+    hybridSearch(collection: string, query: string, targetProperties: string[], limit?: number, where?: WhereFilter): Promise<WeaviateQueryResult>;
+    /**
+     * Pure vector (nearText) search — for dedup/similarity detection
+     */
+    nearTextSearch(collection: string, query: string, limit?: number, targetProperties?: string[]): Promise<WeaviateQueryResult>;
+    /**
+     * GraphQL Get with where filter only (no vector/BM25 search).
+     * Works on all collections including non-vectorized ones like VipunenConfig.
+     */
+    filterQuery(collection: string, where: WhereFilter, properties?: string[], limit?: number): Promise<WeaviateQueryResult>;
+    /**
+     * Aggregate query grouped by a property
+     */
+    aggregateGroupBy(collection: string, groupByProperty: string): Promise<Array<{
+        value: string;
+        count: number;
+    }>>;
+    /**
+     * Insert a single object into a collection
+     */
+    insertObject(collection: string, properties: Record<string, any>): Promise<WeaviateInsertResult>;
+    /**
+     * Batch insert objects into a collection.
+     * Splits into batches and returns aggregate result.
+     */
+    batchInsert(collection: string, objects: Array<Record<string, any>>, batchSize?: number): Promise<WeaviateBatchInsertResult>;
+    /**
+     * Batch delete objects matching a where filter
+     */
+    batchDelete(collection: string, where: any): Promise<WeaviateDeleteResult>;
+    /**
+     * Delete objects where a property equals a specific value
+     */
+    deleteByProperty(collection: string, property: string, value: string): Promise<WeaviateDeleteResult>;
+    /**
+     * Delete objects matching multiple AND conditions.
+     * Supports mixed types: string values use valueText, numbers use valueInt.
+     */
+    deleteByMultipleProperties(collection: string, conditions: Array<{
+        property: string;
+        value: string | number;
+    }>): Promise<WeaviateDeleteResult>;
+    /**
+     * Get collection schema (for discovering properties). Cached per collection.
+     */
+    getCollectionSchema(collection: string): Promise<any>;
+    /**
+     * Export all objects from a collection using cursor-based pagination.
+     */
+    exportCollection(collection: string, properties?: string[], pageSize?: number): Promise<WeaviateExportResult>;
+    /**
+     * Create a collection with a given schema. Idempotent — returns existing if already present.
+     */
+    createCollection(collection: string, schema: Record<string, any>): Promise<{
+        created: boolean;
+        objectCount: number;
+    }>;
+    /**
+     * Count objects in a collection. Validates collection name before querying.
+     */
+    countCollection(collection: string): Promise<number>;
+    /**
+     * Delete a collection. Idempotent — no error if it doesn't exist.
+     */
+    deleteCollection(collection: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * Serialize a WhereFilter into Weaviate GraphQL inline syntax.
+     * Validates operators and paths to prevent injection.
+     */
+    private serializeWhereFilter;
+    /**
+     * Escape special characters for GraphQL string literals
+     */
+    private escapeGraphQL;
+    private validateCollectionName;
+    private validatePropertyNames;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/plugins/vipunen/client.js

@@ -0,0 +1,535 @@
+"use strict";
+/**
+ * Weaviate HTTP Client
+ *
+ * Lightweight client that talks to Weaviate's GraphQL and REST APIs directly.
+ * No heavy SDK dependency — just fetch calls with proper auth headers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WeaviateClient = exports.WeaviateAuthError = void 0;
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)({ component: 'weaviate-client' });
+// Validation patterns for GraphQL injection prevention
+const COLLECTION_PATTERN = /^[A-Z][a-zA-Z0-9]*$/;
+const PROPERTY_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const VALID_WHERE_OPERATORS = new Set([
+    'Equal', 'NotEqual', 'GreaterThan', 'GreaterThanEqual',
+    'LessThan', 'LessThanEqual', 'Like', 'WithinGeoRange',
+    'IsNull', 'ContainsAny', 'ContainsAll', 'And', 'Or',
+]);
+/**
+ * Thrown when Weaviate returns 401/403 — signals invalid server API key.
+ */
+class WeaviateAuthError extends Error {
+    status;
+    constructor(status) {
+        super(`Weaviate authentication failed (${status})`);
+        this.status = status;
+        this.name = 'WeaviateAuthError';
+    }
+}
+exports.WeaviateAuthError = WeaviateAuthError;
+class WeaviateClient {
+    host;
+    headers;
+    static SCHEMA_TTL_MS = 5 * 60 * 1000; // 5 minutes
+    schemaCache = new Map();
+    constructor(config) {
+        // Remove trailing slash
+        this.host = config.host.replace(/\/$/, '');
+        this.headers = {
+            'Content-Type': 'application/json',
+        };
+        if (config.apiKey) {
+            this.headers['Authorization'] = `Bearer ${config.apiKey}`;
+        }
+        logger.debug('Weaviate client initialized', { host: this.host, hasApiKey: !!config.apiKey });
+    }
+    /**
+     * Shared fetch with auth-error and response-error handling.
+     * All HTTP calls go through this to avoid repeating 401/403 checks.
+     */
+    async _fetch(url, init) {
+        let response;
+        try {
+            response = await fetch(url, { ...init, headers: { ...this.headers, ...init.headers } });
+        }
+        catch (err) {
+            throw new Error(`Weaviate request to ${url} failed: ${err.message}`);
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new WeaviateAuthError(response.status);
+        }
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Weaviate error (${response.status}): ${text}`);
+        }
+        return response;
+    }
+    /**
+     * Execute a GraphQL query against Weaviate
+     */
+    async graphql(query, variables) {
+        const url = `${this.host}/v1/graphql`;
+        const body = { query };
+        if (variables) {
+            body.variables = variables;
+        }
+        const response = await this._fetch(url, {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        const result = await response.json();
+        if (result.errors && result.errors.length > 0) {
+            throw new Error(`Weaviate GraphQL error: ${result.errors.map((e) => e.message).join(', ')}`);
+        }
+        return result.data;
+    }
+    /**
+     * Hybrid search (BM25 + vector) — the main query tool
+     */
+    async hybridSearch(collection, query, targetProperties, limit = 5, where) {
+        this.validateCollectionName(collection);
+        this.validatePropertyNames(targetProperties);
+        const returnFields = targetProperties.join('\n        ');
+        const safeLimit = Math.floor(Math.max(1, Math.min(25, limit)));
+        const whereClause = where ? `\n          where: ${this.serializeWhereFilter(where)}` : '';
+        const gql = `{
+      Get {
+        ${collection}(
+          hybrid: {
+            query: "${this.escapeGraphQL(query)}"
+            properties: [${targetProperties.map(p => `"${p}"`).join(', ')}]
+            alpha: 0.5
+          }
+          limit: ${safeLimit}${whereClause}
+        ) {
+          ${returnFields}
+          _additional {
+            score
+            id
+          }
+        }
+      }
+    }`;
+        const data = await this.graphql(gql);
+        const objects = data?.Get?.[collection] || [];
+        return {
+            objects: objects.map((obj) => {
+                const { _additional, ...props } = obj;
+                return {
+                    ...props,
+                    _score: parseFloat(_additional?.score || '0'),
+                    _id: _additional?.id,
+                };
+            }),
+        };
+    }
+    /**
+     * Pure vector (nearText) search — for dedup/similarity detection
+     */
+    async nearTextSearch(collection, query, limit = 5, targetProperties) {
+        this.validateCollectionName(collection);
+        // Use provided properties, or fall back to cached schema discovery
+        let propNames;
+        if (targetProperties) {
+            propNames = targetProperties;
+        }
+        else {
+            const schema = await this.getCollectionSchema(collection);
+            propNames = schema.properties?.map((p) => p.name) || ['title', 'content'];
+        }
+        this.validatePropertyNames(propNames);
+        const returnFields = propNames.join('\n        ');
+        const safeLimit = Math.floor(Math.max(1, Math.min(25, limit)));
+        const gql = `{
+      Get {
+        ${collection}(
+          nearText: {
+            concepts: ["${this.escapeGraphQL(query)}"]
+          }
+          limit: ${safeLimit}
+        ) {
+          ${returnFields}
+          _additional {
+            certainty
+            distance
+            id
+          }
+        }
+      }
+    }`;
+        const data = await this.graphql(gql);
+        const objects = data?.Get?.[collection] || [];
+        return {
+            objects: objects.map((obj) => {
+                const { _additional, ...rest } = obj;
+                return {
+                    ...rest,
+                    _certainty: parseFloat(_additional?.certainty || '0'),
+                    _distance: parseFloat(_additional?.distance || '0'),
+                    _id: _additional?.id,
+                };
+            }),
+        };
+    }
+    /**
+     * GraphQL Get with where filter only (no vector/BM25 search).
+     * Works on all collections including non-vectorized ones like VipunenConfig.
+     */
+    async filterQuery(collection, where, properties, limit = 25) {
+        this.validateCollectionName(collection);
+        let propNames;
+        if (properties && properties.length > 0) {
+            propNames = properties;
+        }
+        else {
+            const schema = await this.getCollectionSchema(collection);
+            propNames = schema.properties?.map((p) => p.name) || ['title', 'content'];
+        }
+        this.validatePropertyNames(propNames);
+        const returnFields = propNames.join('\n        ');
+        const safeLimit = Math.floor(Math.max(1, Math.min(100, limit)));
+        const whereClause = this.serializeWhereFilter(where);
+        const gql = `{
+      Get {
+        ${collection}(
+          where: ${whereClause}
+          limit: ${safeLimit}
+        ) {
+          ${returnFields}
+          _additional {
+            id
+            creationTimeUnix
+            lastUpdateTimeUnix
+          }
+        }
+      }
+    }`;
+        const data = await this.graphql(gql);
+        const objects = data?.Get?.[collection] || [];
+        return {
+            objects: objects.map((obj) => {
+                const { _additional, ...rest } = obj;
+                return {
+                    ...rest,
+                    _id: _additional?.id,
+                    _creationTimeUnix: _additional?.creationTimeUnix,
+                    _lastUpdateTimeUnix: _additional?.lastUpdateTimeUnix,
+                };
+            }),
+        };
+    }
+    /**
+     * Aggregate query grouped by a property
+     */
+    async aggregateGroupBy(collection, groupByProperty) {
+        this.validateCollectionName(collection);
+        this.validatePropertyNames([groupByProperty]);
+        const gql = `{
+      Aggregate {
+        ${collection}(
+          groupBy: ["${groupByProperty}"]
+        ) {
+          groupedBy {
+            value
+          }
+          meta {
+            count
+          }
+        }
+      }
+    }`;
+        const data = await this.graphql(gql);
+        const groups = data?.Aggregate?.[collection] || [];
+        return groups.map((g) => ({
+            value: g.groupedBy?.value || '',
+            count: g.meta?.count || 0,
+        }));
+    }
+    /**
+     * Insert a single object into a collection
+     */
+    async insertObject(collection, properties) {
+        this.validateCollectionName(collection);
+        const response = await this._fetch(`${this.host}/v1/objects`, {
+            method: 'POST',
+            body: JSON.stringify({ class: collection, properties }),
+        });
+        const result = await response.json();
+        if (!result?.id) {
+            throw new Error(`Weaviate insert response missing id field: ${JSON.stringify(result)}`);
+        }
+        return { uuid: result.id };
+    }
+    /**
+     * Batch insert objects into a collection.
+     * Splits into batches and returns aggregate result.
+     */
+    async batchInsert(collection, objects, batchSize = 20) {
+        this.validateCollectionName(collection);
+        const safeBatchSize = Math.floor(Math.max(1, Math.min(100, batchSize)));
+        let inserted = 0;
+        let errors = 0;
+        const errorDetails = [];
+        for (let i = 0; i < objects.length; i += safeBatchSize) {
+            const batch = objects.slice(i, i + safeBatchSize);
+            const weaviateObjects = batch.map(props => ({
+                class: collection,
+                properties: props,
+            }));
+            const response = await this._fetch(`${this.host}/v1/batch/objects`, {
+                method: 'POST',
+                body: JSON.stringify({ objects: weaviateObjects }),
+            });
+            const raw = await response.json();
+            const results = Array.isArray(raw) ? raw : [];
+            if (!Array.isArray(raw)) {
+                // Log warning but don't crash — treat as all-errors batch
+                logger.warn('batchInsert: unexpected non-array response from Weaviate batch API', { batch: i });
+                errors += batch.length;
+                for (let j = 0; j < batch.length; j++) {
+                    errorDetails.push({ index: i + j, error: 'Unexpected non-array response from Weaviate batch API' });
+                }
+                continue;
+            }
+            for (let j = 0; j < results.length; j++) {
+                const r = results[j];
+                if (r.result?.errors?.error?.length > 0) {
+                    errors++;
+                    errorDetails.push({
+                        index: i + j,
+                        error: r.result.errors.error.map((e) => e.message).join(', '),
+                    });
+                }
+                else {
+                    inserted++;
+                }
+            }
+        }
+        return { inserted, errors, errorDetails };
+    }
+    /**
+     * Batch delete objects matching a where filter
+     */
+    async batchDelete(collection, where) {
+        this.validateCollectionName(collection);
+        const response = await this._fetch(`${this.host}/v1/batch/objects`, {
+            method: 'DELETE',
+            body: JSON.stringify({ match: { class: collection, where }, output: 'minimal' }),
+        });
+        const result = await response.json();
+        return {
+            matches: result.results?.matches || 0,
+            successful: result.results?.successful || 0,
+        };
+    }
+    /**
+     * Delete objects where a property equals a specific value
+     */
+    async deleteByProperty(collection, property, value) {
+        return this.batchDelete(collection, {
+            operator: 'Equal',
+            path: [property],
+            valueText: value,
+        });
+    }
+    /**
+     * Delete objects matching multiple AND conditions.
+     * Supports mixed types: string values use valueText, numbers use valueInt.
+     */
+    async deleteByMultipleProperties(collection, conditions) {
+        const operands = conditions.map(c => ({
+            operator: 'Equal',
+            path: [c.property],
+            ...(typeof c.value === 'number'
+                ? { valueInt: c.value }
+                : { valueText: c.value }),
+        }));
+        return this.batchDelete(collection, {
+            operator: 'And',
+            operands,
+        });
+    }
+    /**
+     * Get collection schema (for discovering properties). Cached per collection.
+     */
+    async getCollectionSchema(collection) {
+        this.validateCollectionName(collection);
+        const cached = this.schemaCache.get(collection);
+        if (cached && cached.expiresAt > Date.now())
+            return cached.schema;
+        const response = await this._fetch(`${this.host}/v1/schema/${collection}`, { method: 'GET' });
+        const schema = await response.json();
+        this.schemaCache.set(collection, { schema, expiresAt: Date.now() + WeaviateClient.SCHEMA_TTL_MS });
+        return schema;
+    }
+    /**
+     * Export all objects from a collection using cursor-based pagination.
+     */
+    async exportCollection(collection, properties, pageSize = 100) {
+        this.validateCollectionName(collection);
+        let propNames;
+        if (properties && properties.length > 0) {
+            propNames = properties;
+        }
+        else {
+            const schema = await this.getCollectionSchema(collection);
+            propNames = schema.properties?.map((p) => p.name) || ['title', 'content'];
+        }
+        this.validatePropertyNames(propNames);
+        const returnFields = propNames.join('\n        ');
+        const safePageSize = Math.floor(Math.max(1, Math.min(500, pageSize)));
+        const allObjects = [];
+        let cursor = null;
+        while (true) {
+            const afterClause = cursor ? `after: "${this.escapeGraphQL(cursor)}"` : '';
+            const gql = `{
+        Get {
+          ${collection}(
+            limit: ${safePageSize}
+            ${afterClause}
+          ) {
+            ${returnFields}
+            _additional {
+              id
+              creationTimeUnix
+              lastUpdateTimeUnix
+            }
+          }
+        }
+      }`;
+            const data = await this.graphql(gql);
+            const objects = data?.Get?.[collection] || [];
+            if (objects.length === 0)
+                break;
+            for (const obj of objects) {
+                const { _additional, ...rest } = obj;
+                allObjects.push({
+                    ...rest,
+                    _id: _additional?.id,
+                    _creationTimeUnix: _additional?.creationTimeUnix,
+                    _lastUpdateTimeUnix: _additional?.lastUpdateTimeUnix,
+                });
+            }
+            const lastId = objects[objects.length - 1]?._additional?.id;
+            if (!lastId)
+                break; // no cursor available — cannot paginate further
+            cursor = lastId;
+            if (objects.length < safePageSize)
+                break;
+        }
+        return { objects: allObjects, totalCount: allObjects.length };
+    }
+    /**
+     * Create a collection with a given schema. Idempotent — returns existing if already present.
+     */
+    async createCollection(collection, schema) {
+        this.validateCollectionName(collection);
+        // Check if already exists
+        try {
+            await this._fetch(`${this.host}/v1/schema/${collection}`, { method: 'GET' });
+            // Collection exists — count objects
+            const countData = await this.graphql(`{ Aggregate { ${collection} { meta { count } } } }`);
+            const count = countData?.Aggregate?.[collection]?.[0]?.meta?.count || 0;
+            return { created: false, objectCount: count };
+        }
+        catch (err) {
+            if (err instanceof WeaviateAuthError)
+                throw err;
+            if (err instanceof Error && err.message.includes('(404)')) {
+                // Collection doesn't exist — proceed to create
+            }
+            else {
+                throw err; // network error or unexpected status
+            }
+        }
+        const fullSchema = { class: collection, ...schema };
+        await this._fetch(`${this.host}/v1/schema`, {
+            method: 'POST',
+            body: JSON.stringify(fullSchema),
+        });
+        return { created: true, objectCount: 0 };
+    }
+    /**
+     * Count objects in a collection. Validates collection name before querying.
+     */
+    async countCollection(collection) {
+        this.validateCollectionName(collection);
+        const data = await this.graphql(`{ Aggregate { ${collection} { meta { count } } } }`);
+        return data?.Aggregate?.[collection]?.[0]?.meta?.count || 0;
+    }
+    /**
+     * Delete a collection. Idempotent — no error if it doesn't exist.
+     */
+    async deleteCollection(collection) {
+        this.validateCollectionName(collection);
+        try {
+            await this._fetch(`${this.host}/v1/schema/${collection}`, { method: 'DELETE' });
+            return { deleted: true };
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.includes('404')) {
+                return { deleted: false };
+            }
+            throw err;
+        }
+    }
+    /**
+     * Serialize a WhereFilter into Weaviate GraphQL inline syntax.
+     * Validates operators and paths to prevent injection.
+     */
+    serializeWhereFilter(filter) {
+        if (!VALID_WHERE_OPERATORS.has(filter.operator)) {
+            throw new Error(`Invalid where operator: "${filter.operator}" — allowed: ${[...VALID_WHERE_OPERATORS].join(', ')}`);
+        }
+        const parts = [];
+        parts.push(`operator: ${filter.operator}`);
+        if (filter.path) {
+            this.validatePropertyNames(filter.path);
+            parts.push(`path: [${filter.path.map(p => `"${p}"`).join(', ')}]`);
+        }
+        if (filter.valueText !== undefined) {
+            parts.push(`valueText: "${this.escapeGraphQL(filter.valueText)}"`);
+        }
+        if (filter.valueInt !== undefined) {
+            parts.push(`valueInt: ${Math.floor(filter.valueInt)}`);
+        }
+        if (filter.valueBoolean !== undefined) {
+            parts.push(`valueBoolean: ${filter.valueBoolean}`);
+        }
+        if (filter.valueDate !== undefined) {
+            parts.push(`valueDate: "${this.escapeGraphQL(filter.valueDate)}"`);
+        }
+        if (filter.operands) {
+            const serializedOperands = filter.operands.map(op => this.serializeWhereFilter(op));
+            parts.push(`operands: [${serializedOperands.join(', ')}]`);
+        }
+        return `{ ${parts.join(', ')} }`;
+    }
+    /**
+     * Escape special characters for GraphQL string literals
+     */
+    escapeGraphQL(str) {
+        return str
+            .replace(/\\/g, '\\\\')
+            .replace(/"/g, '\\"')
+            .replace(/\n/g, '\\n')
+            .replace(/\r/g, '\\r')
+            .replace(/\t/g, '\\t');
+    }
+    validateCollectionName(name) {
+        if (!COLLECTION_PATTERN.test(name)) {
+            throw new Error(`Invalid collection name: "${name}" — must match ${COLLECTION_PATTERN}`);
+        }
+    }
+    validatePropertyNames(names) {
+        for (const name of names) {
+            if (!PROPERTY_PATTERN.test(name)) {
+                throw new Error(`Invalid property name: "${name}" — must match ${PROPERTY_PATTERN}`);
+            }
+        }
+    }
+}
+exports.WeaviateClient = WeaviateClient;
+//# sourceMappingURL=client.js.map