n2-qln 3.4.2 → 4.1.1

package/dist/types.d.ts

@@ -0,0 +1,243 @@
+/** Normalized tool entry stored in registry + SQLite */
+export interface ToolEntry {
+    name: string;
+    description: string;
+    source: string;
+    category: string;
+    provider: string;
+    inputSchema: Record<string, unknown> | null;
+    triggers: string[];
+    tags: string[];
+    examples: string[];
+    endpoint: string;
+    searchText: string;
+    /** 3-10 word capability phrase for BM25 search boosting */
+    boostKeywords: string;
+    usageCount: number;
+    successRate: number;
+    /** Consecutive failure count for circuit breaker */
+    consecutiveFailures: number;
+    lastUsedAt: string | null;
+    embedding: number[] | null;
+    registeredAt: string;
+    updatedAt: string;
+}
+/** Raw tool data before normalization (partial fields accepted) */
+export interface RawToolEntry {
+    name: string;
+    description?: string;
+    source?: string;
+    category?: string;
+    provider?: string;
+    pluginName?: string;
+    inputSchema?: Record<string, unknown> | null;
+    triggers?: string[];
+    tags?: string[];
+    examples?: string[];
+    endpoint?: string;
+    /** 3-10 word capability phrase for BM25 search boosting */
+    boostKeywords?: string;
+    usageCount?: number;
+    successRate?: number;
+    lastUsedAt?: string | null;
+    embedding?: number[] | null;
+    registeredAt?: string;
+}
+/** QLN configuration (config.js + config.local.js merged) */
+export interface QLNConfig {
+    dataDir: string;
+    embedding: {
+        enabled: boolean;
+        model: string;
+        endpoint: string;
+    };
+    executor: {
+        httpEndpoint: string | null;
+        timeout: number;
+    };
+    providers: {
+        enabled: boolean;
+        dir: string;
+    };
+    search: {
+        defaultTopK: number;
+        threshold: number;
+        /** Per-source score multiplier (default: 1.0 for all) */
+        sourceWeights: Record<string, number>;
+    };
+}
+/** Search result returned by Router */
+export interface SearchResult {
+    name: string;
+    score: number;
+    stages: {
+        trigger: number;
+        keyword: number;
+        semantic: number;
+        usage: number;
+        success: number;
+        recencyFactor: number;
+    };
+    description: string;
+    source: string;
+    category: string;
+    inputSchema: Record<string, unknown> | null;
+    explorer?: boolean;
+}
+/** Timing info from Router search */
+export interface SearchTiming {
+    stage1: number;
+    stage2: number;
+    stage3: number;
+    merge: number;
+    total: number;
+}
+/** Validation error from validator */
+export interface ValidationError {
+    field: string;
+    message: string;
+    severity: 'error' | 'warning';
+}
+/** Provider manifest JSON structure */
+export interface ProviderManifest {
+    provider: string;
+    version?: string;
+    description?: string;
+    endpoint?: string;
+    tools: Array<{
+        name: string;
+        description: string;
+        category?: string;
+        inputSchema?: Record<string, unknown>;
+        triggers?: string[];
+        tags?: string[];
+        examples?: string[];
+        endpoint?: string;
+        boostKeywords?: string;
+    }>;
+}
+/** Tool execution result */
+export interface ExecResult {
+    result: unknown;
+    source: 'local' | 'http';
+    elapsed: number;
+    /** Whether this result came from a fallback tool */
+    fallback?: boolean;
+    /** Original tool name if fallback was used */
+    originalTool?: string;
+}
+/** Circuit breaker configuration */
+export interface CircuitBreakerConfig {
+    /** Consecutive failures before tripping (default: 3) */
+    failureThreshold: number;
+    /** Milliseconds before attempting recovery (default: 60000) */
+    recoveryTimeout: number;
+}
+/** Circuit breaker states */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+/** MCP tool response content */
+export interface McpToolResponse {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/** SQLite row from tools table (snake_case columns) */
+export interface ToolRow {
+    name: string;
+    description: string;
+    source: string;
+    category: string;
+    provider: string;
+    plugin_name?: string;
+    input_schema: string;
+    triggers: string;
+    tags: string;
+    examples: string;
+    endpoint: string;
+    search_text: string;
+    embedding: string;
+    usage_count: number;
+    success_rate: number;
+    last_used_at: string | null;
+    registered_at: string;
+    updated_at: string;
+}
+/** sql.js Database interface (minimal) */
+export interface SqlJsDatabase {
+    run(sql: string, params?: unknown[]): void;
+    exec(sql: string): Array<{
+        columns: string[];
+        values: unknown[][];
+    }>;
+    export(): Uint8Array;
+    close(): void;
+}
+/** sql.js static module interface */
+export interface SqlJsStatic {
+    Database: new (data?: ArrayLike<number>) => SqlJsDatabase;
+}
+/** Stage score accumulator used internally by Router */
+export interface StageScores {
+    stage1: number;
+    stage2: number;
+    stage3: number;
+}
+/** Registry stats */
+export interface RegistryStats {
+    total: number;
+    bySource: Record<string, number>;
+    byCategory: Record<string, number>;
+    withEmbedding: number;
+    embeddingCoverage: string;
+}
+/** VectorIndex build result */
+export interface VectorBuildResult {
+    indexed: number;
+    categories: number;
+    dimension: number;
+}
+/** VectorIndex stats */
+export interface VectorStats {
+    built: boolean;
+    tools: number;
+    dimension: number;
+    categories: number;
+    categoryList: string[];
+    memoryKB: number;
+}
+/** Router stats */
+export interface RouterStats {
+    registrySize: number;
+    vectorIndex: VectorStats;
+    embeddingAvailable: boolean;
+    bm25: {
+        idfTerms: number;
+        avgDocLen: number;
+        k1: number;
+        b: number;
+    };
+}
+/** Provider load result */
+export interface ProviderLoadResult {
+    loaded: number;
+    skipped: number;
+    failed: number;
+    details: Array<{
+        file: string;
+        status: 'loaded' | 'skipped' | 'failed';
+        reason?: string;
+        provider?: string;
+        toolCount?: number;
+    }>;
+}
+/** Embedding precompute result */
+export interface EmbeddingPrecomputeResult {
+    embedded: number;
+    skipped: number;
+    failed: number;
+}
+/** Tool handler function signature */
+export type ToolHandler = (args: Record<string, unknown>) => Promise<unknown>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// QLN — Shared type definitions for all modules
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -1,13 +1,16 @@
 {
     "name": "n2-qln",
-    "version": "3.4.2",
+    "version": "4.1.1",
     "description": "Query Layer Network — Semantic tool dispatcher for MCP. Route 1000 tools through 1 router.",
-    "main": "index.js",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
     "bin": {
-        "n2-qln": "./index.js"
+        "n2-qln": "./dist/index.js"
     },
     "scripts": {
-        "start": "node index.js",
+        "build": "tsc",
+        "start": "node dist/index.js",
+        "dev": "tsc --watch",
         "test": "node test/test-provider-loader.js"
     },
     "dependencies": {
@@ -30,5 +33,9 @@
     },
     "engines": {
         "node": ">=18.0.0"
+    },
+    "devDependencies": {
+        "@types/node": "^25.5.0",
+        "typescript": "^6.0.2"
     }
 }

package/.github/FUNDING.yml

@@ -1,3 +0,0 @@
-# QLN MCP — Funding configuration
-# This enables the 💖 Sponsor button on the GitHub repository
-github: [choihyunsus]

package/docs/README.md

@@ -1,2 +0,0 @@
-# QLN docs directory
-Architecture diagrams and documentation assets.

package/index.js

@@ -1,80 +0,0 @@
-#!/usr/bin/env node
-// QLN — Query Layer Network MCP server entry point
-// Semantic tool dispatcher: route 1000 tools through 1 router
-const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
-const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
-const { z } = require('zod');
-
-// Core
-const path = require('path');
-const { loadConfig } = require('./lib/config');
-const { Store } = require('./lib/store');
-const { Embedding } = require('./lib/embedding');
-const { Registry } = require('./lib/registry');
-const { VectorIndex } = require('./lib/vector-index');
-const { Router } = require('./lib/router');
-const { Executor } = require('./lib/executor');
-const { loadProviders } = require('./lib/provider-loader');
-
-// MCP Tool (unified)
-const { registerQlnCall } = require('./tools/qln-call');
-
-async function main() {
-    const config = loadConfig();
-
-    // 1. Core engine initialization
-    const store = new Store(config.dataDir);
-    await store.init();
-
-    const embedding = config.embedding?.enabled
-        ? new Embedding(config.embedding)
-        : null;
-
-    const registry = new Registry(store, embedding);
-    registry.load();
-
-    // 1.5. Provider auto-indexing (providers/*.json → registry)
-    if (config.providers?.enabled !== false) {
-        const provDir = config.providers?.dir || path.join(__dirname, 'providers');
-        const provResult = loadProviders(provDir, registry);
-        if (provResult.loaded > 0) {
-            console.error(`[QLN] Providers: ${provResult.loaded} tools from ${provResult.details.filter(d => d.status === 'loaded').length} files`);
-        }
-        if (provResult.failed > 0) {
-            console.error(`[QLN] Provider warnings: ${provResult.failed} files failed to load`);
-        }
-    }
-
-    const vectorIndex = new VectorIndex();
-    const router = new Router(registry, vectorIndex, embedding);
-    const executor = new Executor(config.executor || {});
-
-    // 2. Precompute embeddings + build vector index (async, non-blocking)
-    if (embedding) {
-        setImmediate(async () => {
-            try {
-                await registry.precomputeEmbeddings();
-                router.buildIndex();
-            } catch { /* Ollama not available — Stage 1+2 still work */ }
-        });
-    }
-
-    // 3. Create MCP server
-    const pkg = require('./package.json');
-    const server = new McpServer({
-        name: 'n2-qln',
-        version: pkg.version,
-    });
-
-    // 4. Register unified MCP tool (1 tool, 5 actions)
-    registerQlnCall(server, z, router, executor, registry);
-
-    // 5. Connect stdio transport
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-}
-
-main().catch(err => {
-    console.error(`[QLN] Fatal: ${err.message}`);
-    process.exit(1);
-});

package/lib/executor.js

@@ -1,104 +0,0 @@
-// QLN — L3 tool executor
-// Execute tools via HTTP (localhost) or registered local handlers
-const http = require('http');
-
-/**
- * Tool executor — HTTP proxy + local function calls.
- *
- * Execution priority:
- *   1. Local registered handler (via addHandler)
- *   2. HTTP proxy (when endpoint configured)
- */
-class Executor {
-    /**
-     * @param {object} config
-     * @param {string} [config.httpEndpoint] - Tool execution HTTP endpoint (e.g. "http://127.0.0.1:PORT")
-     * @param {number} [config.timeout=20000] - HTTP timeout (ms)
-     */
-    constructor(config = {}) {
-        this._httpEndpoint = config.httpEndpoint || null;
-        this._timeout = config.timeout || 20000;
-        /** @type {Map<string, Function>} Local handlers */
-        this._handlers = new Map();
-    }
-
-    /**
-     * Register a local tool handler.
-     * @param {string} name - Tool name
-     * @param {Function} handler - (args) => Promise<unknown>
-     */
-    addHandler(name, handler) {
-        this._handlers.set(name, handler);
-    }
-
-    /**
-     * Execute a tool.
-     * @param {string} name - Tool name
-     * @param {object} args - Tool arguments
-     * @returns {Promise<{result: unknown, source: string, elapsed: number}>}
-     */
-    async exec(name, args = {}) {
-        const t0 = Date.now();
-
-        // 1. Local handler first
-        if (this._handlers.has(name)) {
-            const handler = this._handlers.get(name);
-            const result = await handler(args);
-            return { result, source: 'local', elapsed: Date.now() - t0 };
-        }
-
-        // 2. HTTP proxy
-        if (this._httpEndpoint) {
-            const result = await this._execHttp(name, args);
-            return { result, source: 'http', elapsed: Date.now() - t0 };
-        }
-
-        throw new Error(`No handler found for tool: ${name}. Register with addHandler() or set httpEndpoint.`);
-    }
-
-    /**
-     * Dynamically set HTTP endpoint.
-     * @param {string} endpoint - "http://127.0.0.1:PORT" format
-     */
-    setHttpEndpoint(endpoint) {
-        this._httpEndpoint = endpoint;
-    }
-
-    /** @private HTTP POST /call → tool execution */
-    _execHttp(name, args) {
-        return new Promise((resolve, reject) => {
-            const url = new URL(this._httpEndpoint);
-            const bodyStr = JSON.stringify({ tool: name, args });
-            const timer = setTimeout(() => reject(new Error(`timeout (${this._timeout}ms)`)), this._timeout);
-
-            const req = http.request({
-                hostname: url.hostname,
-                port: url.port,
-                path: '/call',
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'Content-Length': Buffer.byteLength(bodyStr),
-                },
-            }, (res) => {
-                let body = '';
-                res.on('data', c => body += c);
-                res.on('end', () => {
-                    clearTimeout(timer);
-                    try {
-                        const parsed = JSON.parse(body);
-                        if (parsed.error) reject(new Error(parsed.error));
-                        else resolve(parsed.result);
-                    } catch {
-                        reject(new Error(`Invalid response: ${body.slice(0, 200)}`));
-                    }
-                });
-            });
-            req.on('error', e => { clearTimeout(timer); reject(e); });
-            req.write(bodyStr);
-            req.end();
-        });
-    }
-}
-
-module.exports = { Executor };

package/lib/provider-loader.js

@@ -1,126 +0,0 @@
-// QLN — Provider manifest loader (providers/*.json → registry auto-registration)
-const fs = require('fs');
-const path = require('path');
-const { inferCategory } = require('./schema');
-
-/**
- * Required fields for a valid provider manifest.
- * @type {string[]}
- */
-const REQUIRED_MANIFEST_FIELDS = ['provider', 'tools'];
-
-/**
- * Required fields for each tool entry within a manifest.
- * @type {string[]}
- */
-const REQUIRED_TOOL_FIELDS = ['name', 'description'];
-
-/**
- * Load all provider manifests from a directory and register their tools.
- *
- * @param {string} providersDir - Absolute path to providers/ directory
- * @param {import('./registry').Registry} registry - QLN registry instance
- * @returns {{ loaded: number, skipped: number, failed: number, details: object[] }}
- */
-function loadProviders(providersDir, registry) {
-    const result = { loaded: 0, skipped: 0, failed: 0, details: [] };
-
-    if (!fs.existsSync(providersDir)) return result;
-
-    /** @type {string[]} */
-    const files = fs.readdirSync(providersDir)
-        .filter(f => f.endsWith('.json'));
-
-    if (files.length === 0) return result;
-
-    for (const file of files) {
-        const filePath = path.join(providersDir, file);
-        try {
-            const manifest = _parseManifest(filePath);
-            if (!manifest) {
-                result.skipped++;
-                result.details.push({ file, status: 'skipped', reason: 'invalid manifest' });
-                continue;
-            }
-
-            const tools = _normalizeTools(manifest);
-            if (tools.length === 0) {
-                result.skipped++;
-                result.details.push({ file, status: 'skipped', reason: 'no valid tools' });
-                continue;
-            }
-
-            // Idempotent: purge old entries from this provider before re-registering
-            registry.purgeBySource(`provider:${manifest.provider}`);
-
-            const count = registry.registerBatch(tools);
-            result.loaded += count;
-            result.details.push({
-                file,
-                status: 'loaded',
-                provider: manifest.provider,
-                toolCount: count,
-            });
-        } catch (err) {
-            result.failed++;
-            result.details.push({ file, status: 'failed', reason: err.message });
-        }
-    }
-
-    return result;
-}
-
-/**
- * Parse and validate a manifest JSON file.
- *
- * @param {string} filePath - Absolute path to JSON file
- * @returns {object|null} Parsed manifest or null if invalid
- */
-function _parseManifest(filePath) {
-    const raw = fs.readFileSync(filePath, 'utf-8');
-    const manifest = JSON.parse(raw);
-
-    // Validate required fields
-    for (const field of REQUIRED_MANIFEST_FIELDS) {
-        if (!manifest[field]) return null;
-    }
-
-    // tools must be a non-empty array
-    if (!Array.isArray(manifest.tools)) return null;
-
-    return manifest;
-}
-
-/**
- * Normalize tool entries from a manifest for registry registration.
- * Injects provider metadata and assigns source = "provider:{name}".
- *
- * @param {object} manifest - Validated manifest object
- * @returns {object[]} Array of normalized tool entries ready for registerBatch()
- */
-function _normalizeTools(manifest) {
-    const providerName = manifest.provider;
-    const tools = [];
-
-    for (const raw of manifest.tools) {
-        // Skip tools missing required fields
-        if (!raw.name || !raw.description) continue;
-
-        tools.push({
-            name: raw.name,
-            description: raw.description,
-            source: `provider:${providerName}`,
-            category: raw.category || inferCategory(raw.name, 'provider'),
-            provider: providerName,
-            inputSchema: raw.inputSchema || null,
-            triggers: raw.triggers || undefined, // let schema.js extract
-            tags: raw.tags || [],
-            examples: raw.examples || [],
-            endpoint: raw.endpoint || '',
-        });
-    }
-
-    return tools;
-}
-
-module.exports = { loadProviders };