@chnxthr/knowledge-mcp 0.0.0-stage → 0.3.0

package/dist/core/scope.js

@@ -0,0 +1,54 @@
+import { getConfig } from './config.js';
+// 도구군 없이도 항상 허용하는 안전 도구(health check). 명시 화이트리스트.
+const NO_SCOPE_TOOLS = new Set(['ping']);
+/**
+ * 이 도구를 노출·호출해도 되는가. group = 도구가 속한 플러그인 id(registry.groupOf), 없으면 null.
+ * admin = 전체, member = allowed_tools(미설정=전체), viewer = config access.viewerTools 로 연 것만.
+ */
+export function isToolAllowed(auth, name, group) {
+    if (auth.role === 'admin')
+        return true;
+    if (group === null)
+        return NO_SCOPE_TOOLS.has(name);
+    if (auth.role !== 'member')
+        return getConfig().access.viewerTools.includes(group);
+    const tools = auth.scopes?.tools;
+    if (!tools || tools.length === 0)
+        return true; // 미설정 = 모든 도구군
+    return tools.includes(group);
+}
+/** 허용 Slack 채널 id Set. null = 전체 허용(admin·미설정). */
+export function allowedSlackChannels(auth) {
+    if (auth.role === 'admin')
+        return null;
+    const ch = auth.scopes?.slackChannels;
+    if (!ch || ch.length === 0)
+        return null;
+    return new Set(ch);
+}
+/** 허용 Drive 폴더 path prefix 배열. null = 전체 허용(admin·미설정). */
+export function allowedDriveFolders(auth) {
+    if (auth.role === 'admin')
+        return null;
+    const f = auth.scopes?.driveFolders;
+    if (!f || f.length === 0)
+        return null;
+    return f;
+}
+/**
+ * path 가 허용 폴더 prefix 하위인가. prefixes null = 전체 허용.
+ * path 예: "개발문서/backend/..." · "01_고객사/Acme/제안서.pptx".
+ * prefix 예: "01_고객사" → 그 하위 전부 허용. 정확 일치 또는 "prefix/" 로 시작.
+ */
+export function isPathInScope(path, prefixes) {
+    if (!prefixes || prefixes.length === 0)
+        return true;
+    const norm = String(path).replace(/^\/+/, '');
+    return prefixes.some((p) => {
+        const pp = String(p).replace(/^\/+|\/+$/g, '');
+        if (!pp)
+            return false;
+        return norm === pp || norm.startsWith(pp + '/');
+    });
+}
+//# sourceMappingURL=scope.js.map

package/dist/core/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/core/scope.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,kDAAkD;AAClD,MAAM,cAAc,GAAG,IAAI,GAAG,CAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AAEjD;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAiB,EAAE,IAAY,EAAE,KAAoB;IACjF,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClF,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC;IACjC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,eAAe;IAC9D,OAAO,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,oBAAoB,CAAC,IAAiB;IACpD,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC;IACtC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC;AACrB,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,mBAAmB,CAAC,IAAiB;IACnD,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC;IACpC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,QAAyB;IACnE,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC9C,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;QACzB,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QAC/C,IAAI,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC;QACtB,OAAO,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/core/upstream.d.ts

@@ -0,0 +1,30 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { UpstreamSpec } from '../plugin/define.js';
+export declare function isExposed(spec: UpstreamSpec, remoteName: string): boolean;
+export declare class UpstreamManager {
+    private upstreams;
+    constructor(entries: Array<{
+        spec: UpstreamSpec;
+        group: string;
+    }>);
+    get size(): number;
+    connectAll(): Promise<void>;
+    /** Tools of connected remotes, with their permission group. */
+    tools(): Array<{
+        tool: Tool;
+        group: string;
+    }>;
+    /** The remote that owns this name, if any. */
+    owner(toolName: string): {
+        group: string;
+        call: (args: Record<string, unknown>) => Promise<unknown>;
+    } | null;
+    /** Prefix match only — used to tell "blocked remote write tool" apart from "unknown tool". */
+    prefixOwner(toolName: string): string | null;
+    statuses(): {
+        name: string;
+        connected: boolean;
+        toolCount: number;
+        error: string | null;
+    }[];
+}

package/dist/core/upstream.js

@@ -0,0 +1,164 @@
+/**
+ * MCP gateway — connects to remote MCP servers as a client and re-exposes their tools under a name prefix,
+ * so one connector gives the user both local plugin tools and remote ones.
+ *
+ * Design:
+ *   - graceful (fail-open): a remote that fails to connect only drops its own tools; the server keeps running.
+ *   - best-effort connect after listen + tools/list cache. Each MCP session reads the cache.
+ *   - names: `{prefix}{remote name}` (e.g. github_search_code). The prefix routes calls back.
+ *   - read-only by default: only tools whose first word is a read verb are listed and callable, so the
+ *     shared server token can't be used to edit code, merge or delete through the gateway.
+ *
+ * Remotes come from plugins (`upstreams` in a plugin) and from the config file (`upstreams: [...]`).
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { VERSION } from '../version.js';
+/**
+ * Allowlist (default-deny) of read verbs. A blocklist of write verbs used to let unknown verbs
+ * (set_, enable_, dispatch_, assign_, submit_ ...) through as "read-only"; now an unknown verb is blocked.
+ * A read tool blocked by a missing verb is a lost feature, but the safe side. Set `expose` to open more.
+ */
+const READ_VERBS = new Set([
+    'get', 'list', 'search', 'read', 'fetch', 'find', 'show', 'describe', 'view',
+    // 'resolve' is not here — it names state-changing tools such as resolving a review thread.
+    'query', 'count', 'check', 'status', 'ping', 'download', 'export',
+    'lookup', 'diff', 'blame', 'compare', 'log', 'history', 'scan', 'inspect',
+]);
+/** First word of a remote tool name: get_file_contents → get, getFile → get, notion-search → notion. */
+function firstWord(remoteName) {
+    return remoteName.replace(/([a-z0-9])([A-Z])/g, '$1_$2').split(/[_\-.\s]/)[0].toLowerCase();
+}
+export function isExposed(spec, remoteName) {
+    const expose = spec.expose ?? 'read';
+    if (expose === 'all')
+        return true;
+    if (Array.isArray(expose))
+        return expose.includes(remoteName);
+    return READ_VERBS.has(firstWord(remoteName));
+}
+class Upstream {
+    spec;
+    group;
+    client = null;
+    transport = null;
+    tools = []; // prefixed, exposed only
+    connected = false;
+    lastError = null;
+    connecting = null; // single-flight: concurrent reconnects share one attempt
+    constructor(spec, group) {
+        this.spec = spec;
+        this.group = group;
+    }
+    /** best-effort connect + tools/list cache. Never throws. */
+    async connect() {
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = this.doConnect().finally(() => {
+            this.connecting = null;
+        });
+        return this.connecting;
+    }
+    async doConnect() {
+        // Close the previous transport before replacing it so sockets and SSE streams don't leak.
+        const prev = this.transport;
+        this.client = null;
+        this.transport = null;
+        this.connected = false;
+        if (prev)
+            await prev.close().catch(() => { });
+        try {
+            const headers = { ...(this.spec.headers ?? {}) };
+            const token = typeof this.spec.token === 'function' ? this.spec.token() : this.spec.token;
+            if (token)
+                headers.Authorization = `Bearer ${token}`;
+            const transport = new StreamableHTTPClientTransport(new URL(this.spec.url), { requestInit: { headers } });
+            const client = new Client({ name: 'knowledge-mcp-gateway', version: VERSION }, { capabilities: {} });
+            await client.connect(transport);
+            const res = await client.listTools();
+            this.tools = res.tools
+                .filter((t) => isExposed(this.spec, t.name))
+                .map((t) => ({ ...t, name: `${this.spec.prefix}${t.name}`, description: `[${this.spec.name}] ${t.description ?? ''}` }));
+            // Commit only after success so a failed reconnect never exposes a half-built state.
+            this.transport = transport;
+            this.client = client;
+            this.connected = true;
+            this.lastError = null;
+            const hidden = res.tools.length - this.tools.length;
+            console.error(`[upstream:${this.spec.name}] connected · ${this.tools.length} tools (prefix ${this.spec.prefix})` +
+                (hidden ? ` · ${hidden} hidden (not read-only)` : ''));
+        }
+        catch (e) {
+            this.lastError = e instanceof Error ? e.message : String(e);
+            this.connected = false;
+            console.error(`[upstream:${this.spec.name}] connect failed (skipped): ${this.lastError}`);
+        }
+    }
+    getTools() {
+        return this.connected ? this.tools : [];
+    }
+    /** Whether this remote handles the name: prefix matches and the remote tool is exposed. */
+    claims(toolName) {
+        return toolName.startsWith(this.spec.prefix) && isExposed(this.spec, toolName.slice(this.spec.prefix.length));
+    }
+    /** Strip the prefix and forward. Reconnects once if the link dropped. */
+    async callTool(toolName, args) {
+        const remoteName = toolName.slice(this.spec.prefix.length);
+        if (!this.client || !this.connected) {
+            await this.connect();
+            if (!this.client || !this.connected) {
+                throw new Error(`[upstream:${this.spec.name}] not connected${this.lastError ? ` (${this.lastError})` : ''}`);
+            }
+        }
+        try {
+            return await this.client.callTool({ name: remoteName, arguments: args });
+        }
+        catch (e) {
+            this.connected = false;
+            await this.connect();
+            if (!this.client || !this.connected)
+                throw e;
+            return await this.client.callTool({ name: remoteName, arguments: args });
+        }
+    }
+    status() {
+        return { name: this.spec.name, connected: this.connected, toolCount: this.tools.length, error: this.lastError };
+    }
+}
+export class UpstreamManager {
+    upstreams = [];
+    constructor(entries) {
+        const prefixes = new Set();
+        for (const { spec, group } of entries) {
+            if (!spec.prefix)
+                throw new Error(`[upstream:${spec.name}] prefix is required`);
+            if (prefixes.has(spec.prefix))
+                throw new Error(`[upstream] two remotes share the prefix "${spec.prefix}"`);
+            prefixes.add(spec.prefix);
+            this.upstreams.push(new Upstream(spec, group));
+        }
+    }
+    get size() {
+        return this.upstreams.length;
+    }
+    async connectAll() {
+        await Promise.all(this.upstreams.map((u) => u.connect()));
+    }
+    /** Tools of connected remotes, with their permission group. */
+    tools() {
+        return this.upstreams.flatMap((u) => u.getTools().map((tool) => ({ tool, group: u.group })));
+    }
+    /** The remote that owns this name, if any. */
+    owner(toolName) {
+        const u = this.upstreams.find((x) => x.claims(toolName));
+        return u ? { group: u.group, call: (args) => u.callTool(toolName, args) } : null;
+    }
+    /** Prefix match only — used to tell "blocked remote write tool" apart from "unknown tool". */
+    prefixOwner(toolName) {
+        return this.upstreams.find((u) => toolName.startsWith(u.spec.prefix))?.spec.name ?? null;
+    }
+    statuses() {
+        return this.upstreams.map((u) => u.status());
+    }
+}
+//# sourceMappingURL=upstream.js.map

package/dist/core/upstream.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @chnxthr/knowledge-mcp — build your own MCP server from plugins.
+ *
+ *   import { run, builtinPlugins, loadPlugins } from '@chnxthr/knowledge-mcp';
+ *   await run({ plugins: [...builtinPlugins, ...(await loadPlugins(new URL('./plugins/', import.meta.url)))] });
+ *
+ * Importing this module loads .env and installs log masking first (bootstrap.ts), so import it before
+ * anything that reads process.env.
+ */
+import './bootstrap.js';
+export { definePlugin, defineTool, ToolError, isPlugin } from './plugin/define.js';
+export type { Plugin, PluginSpec, PluginCommand, PluginState, Tool, ToolSpec, ToolContext, ToolResult, ToolReturn, UpstreamSpec, } from './plugin/define.js';
+export { loadPlugins } from './plugin/load.js';
+export { Registry } from './plugin/registry.js';
+export { run, type RunOptions } from './run.js';
+export { builtinPlugins, drivePlugin, slackPlugin, githubPlugin, railwayPlugin } from './plugins/index.js';
+export { getAuth, getAuthMaybe } from './core/context.js';
+export { getConfig } from './core/config.js';
+export { getStore } from './store/index.js';
+export type { Store } from './store/types.js';
+export type { AuthContext, Role, ResourceScopes } from './core/auth.js';
+export { VERSION } from './version.js';
+export { z } from 'zod';

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * @chnxthr/knowledge-mcp — build your own MCP server from plugins.
+ *
+ *   import { run, builtinPlugins, loadPlugins } from '@chnxthr/knowledge-mcp';
+ *   await run({ plugins: [...builtinPlugins, ...(await loadPlugins(new URL('./plugins/', import.meta.url)))] });
+ *
+ * Importing this module loads .env and installs log masking first (bootstrap.ts), so import it before
+ * anything that reads process.env.
+ */
+import './bootstrap.js';
+export { definePlugin, defineTool, ToolError, isPlugin } from './plugin/define.js';
+export { loadPlugins } from './plugin/load.js';
+export { Registry } from './plugin/registry.js';
+export { run } from './run.js';
+export { builtinPlugins, drivePlugin, slackPlugin, githubPlugin, railwayPlugin } from './plugins/index.js';
+export { getAuth, getAuthMaybe } from './core/context.js';
+export { getConfig } from './core/config.js';
+export { getStore } from './store/index.js';
+export { VERSION } from './version.js';
+export { z } from 'zod';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,gBAAgB,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAInF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,GAAG,EAAmB,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC3G,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC"}

package/dist/plugin/define.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Plugin API — the only thing you need to add tools to Knowledge MCP.
+ *
+ * A plugin is one connector (Drive, Slack, your internal API, ...). Its `id` is also its permission group:
+ * admins see every plugin, members see the groups in their allowed_tools (all when unset), and viewers see
+ * only the groups listed in config `access.viewerTools`.
+ *
+ *   export default definePlugin({
+ *     id: 'weather',
+ *     env: ['WEATHER_API_KEY'],            // tools stay hidden until every name here is set
+ *     tools: [
+ *       defineTool({
+ *         name: 'weather_now',
+ *         description: 'Current weather for a city',
+ *         input: z.object({ city: z.string().describe('City name') }),
+ *         run: async ({ city }) => fetchWeather(city),   // return a string, any JSON value, or an MCP result
+ *       }),
+ *     ],
+ *   });
+ *
+ * The core lists the tools, validates input against the zod schema (zod 3 or 4), checks the caller's
+ * permission, logs the call, and turns return values and thrown errors into MCP results.
+ */
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import type { AnySchema, SchemaOutput } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import type { AuthContext, Role } from '../core/auth.js';
+export declare const PLUGIN_BRAND: unique symbol;
+declare const TOOL_BRAND: unique symbol;
+/** MCP tool result. Returned as is when a tool returns an object with a `content` array. */
+export type ToolResult = {
+    content: Array<{
+        type: string;
+        [k: string]: unknown;
+    }>;
+    isError?: boolean;
+    [k: string]: unknown;
+};
+/** What `run` may return: text, any JSON-serializable value (sent as pretty JSON), or a full MCP result. */
+export type ToolReturn = string | ToolResult | Record<string, unknown> | unknown[] | number | boolean | null | undefined;
+/** Small key-value storage, kept per plugin in the server's store (SQLite file or Supabase). */
+export interface PluginState {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface ToolContext {
+    /** The caller. `role` is admin, member or viewer. */
+    user: {
+        email?: string;
+        role: Role;
+        keyId?: string;
+    };
+    /** Full auth context (scopes for Slack channels and Drive folders, act-as flag). */
+    auth: AuthContext;
+    /** This plugin's section of the config file (`plugins.<id>`), validated by `configSchema` when given. */
+    config: unknown;
+    /** Persistent key-value storage for this plugin. */
+    state: PluginState;
+    /** Log to stderr with the plugin prefix. Secrets are masked. Never use console.log in stdio mode. */
+    log: (...args: unknown[]) => void;
+}
+export interface ToolSpec<S extends AnySchema = AnySchema> {
+    /** Tool name shown to the model. Lowercase letters, digits and underscores; unique across all plugins. */
+    name: string;
+    /** What the tool does and when to use it. The model reads this to pick the tool. */
+    description: string;
+    /** zod object schema for the arguments. Describe each field with `.describe()`. Omit for no arguments. */
+    input?: S;
+    /** MCP tool hints (readOnlyHint, destructiveHint, ...). */
+    annotations?: ToolAnnotations;
+    /** Extra condition on top of the plugin's. Return true, or a short reason why the tool is off. */
+    enabled?: () => boolean | string;
+    run: (input: SchemaOutput<S>, ctx: ToolContext) => Promise<ToolReturn> | ToolReturn;
+}
+/** A remote MCP server whose tools are re-exposed under a name prefix (the server is a gateway). */
+export interface UpstreamSpec {
+    /** Name for logs. */
+    name: string;
+    /** Streamable HTTP endpoint of the remote MCP server. */
+    url: string;
+    /** Prefix added to every remote tool name, e.g. "github_" turns get_me into github_get_me. */
+    prefix: string;
+    /** Bearer token sent to the remote server. A function is read at connect time. */
+    token?: string | (() => string | undefined);
+    headers?: Record<string, string>;
+    /**
+     * Which remote tools to expose. "read" (default) keeps tools whose first word is a read verb
+     * (get, list, search, ...) and blocks the rest. "all" exposes everything. A list exposes exactly
+     * those remote names (without the prefix).
+     */
+    expose?: 'read' | 'all' | string[];
+}
+/** A CLI subcommand: `knowledge-mcp <plugin id> <command> [args]`. */
+export interface PluginCommand {
+    description: string;
+    run: (args: string[]) => Promise<void> | void;
+}
+export interface PluginSpec {
+    /** Permission group and config key. Lowercase letters, digits and dashes. */
+    id: string;
+    /** One line shown by `knowledge-mcp doctor`. */
+    description?: string;
+    /** Env vars that must all be set (non-empty) for the plugin to turn on. */
+    env?: string[];
+    /** Extra condition, checked after `env`. Return true, or a short reason why the plugin is off. */
+    enabled?: () => boolean | string;
+    tools?: ToolSpec<any>[];
+    /** Remote MCP servers to proxy. Their tools join this plugin's permission group. */
+    upstreams?: UpstreamSpec[] | (() => UpstreamSpec[]);
+    /** Usage notes appended to the server instructions the client receives. */
+    instructions?: string;
+    /** zod schema for `plugins.<id>` in the config file. */
+    configSchema?: AnySchema;
+    /**
+     * Runs once after the HTTP server is listening (background jobs, warm-up). Errors are logged, not fatal.
+     * Not run in stdio mode, where each client session is its own process.
+     */
+    start?: (ctx: {
+        config: unknown;
+        state: PluginState;
+        log: (...args: unknown[]) => void;
+    }) => Promise<void> | void;
+    /** Extra CLI commands. */
+    commands?: Record<string, PluginCommand>;
+}
+export type Plugin = PluginSpec & {
+    readonly [PLUGIN_BRAND]: true;
+};
+export type Tool<S extends AnySchema = AnySchema> = ToolSpec<S> & {
+    readonly [TOOL_BRAND]: true;
+};
+/** Define a tool. Gives `run` a typed `input` from the zod schema. */
+export declare function defineTool<S extends AnySchema = AnySchema>(spec: ToolSpec<S>): Tool<S>;
+/** Define a plugin. Validates the shape early so mistakes fail at boot with a clear message. */
+export declare function definePlugin(spec: PluginSpec): Plugin;
+export declare function isPlugin(v: unknown): v is Plugin;
+/**
+ * Throw this from `run` for an expected failure (not found, bad state, missing permission).
+ * The model receives `[error] <message>` and the call is logged as failed.
+ */
+export declare class ToolError extends Error {
+    constructor(message: string);
+}
+export {};

package/dist/plugin/define.js

@@ -0,0 +1,44 @@
+export const PLUGIN_BRAND = Symbol.for('knowledge-mcp.plugin');
+const TOOL_BRAND = Symbol.for('knowledge-mcp.tool');
+const TOOL_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
+const PLUGIN_ID_RE = /^[a-z][a-z0-9-]{0,31}$/;
+/** Define a tool. Gives `run` a typed `input` from the zod schema. */
+export function defineTool(spec) {
+    if (!TOOL_NAME_RE.test(spec.name)) {
+        throw new Error(`[plugin] invalid tool name "${spec.name}": use lowercase letters, digits and underscores (max 64)`);
+    }
+    if (!spec.description?.trim())
+        throw new Error(`[plugin] tool "${spec.name}" needs a description`);
+    if (typeof spec.run !== 'function')
+        throw new Error(`[plugin] tool "${spec.name}" needs a run function`);
+    return Object.assign({}, spec, { [TOOL_BRAND]: true });
+}
+/** Define a plugin. Validates the shape early so mistakes fail at boot with a clear message. */
+export function definePlugin(spec) {
+    if (!PLUGIN_ID_RE.test(spec.id)) {
+        throw new Error(`[plugin] invalid plugin id "${spec.id}": use lowercase letters, digits and dashes (max 32)`);
+    }
+    const names = new Set();
+    for (const t of spec.tools ?? []) {
+        if (!t[TOOL_BRAND])
+            defineTool(t); // validates plain objects too
+        if (names.has(t.name))
+            throw new Error(`[plugin] ${spec.id}: duplicate tool name "${t.name}"`);
+        names.add(t.name);
+    }
+    return Object.assign({}, spec, { [PLUGIN_BRAND]: true });
+}
+export function isPlugin(v) {
+    return !!v && typeof v === 'object' && v[PLUGIN_BRAND] === true;
+}
+/**
+ * Throw this from `run` for an expected failure (not found, bad state, missing permission).
+ * The model receives `[error] <message>` and the call is logged as failed.
+ */
+export class ToolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ToolError';
+    }
+}
+//# sourceMappingURL=define.js.map

package/dist/plugin/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../src/plugin/define.ts"],"names":[],"mappings":"AA2BA,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;AAC/D,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;AAmGpD,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAC9C,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAE9C,sEAAsE;AACtE,MAAM,UAAU,UAAU,CAAkC,IAAiB;IAC3E,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,IAAI,2DAA2D,CAAC,CAAC;IACvH,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,IAAI,CAAC,IAAI,uBAAuB,CAAC,CAAC;IACnG,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,IAAI,CAAC,IAAI,wBAAwB,CAAC,CAAC;IACzG,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,IAAa,EAAE,CAAC,CAAC;AAClE,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,YAAY,CAAC,IAAgB;IAC3C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,EAAE,sDAAsD,CAAC,CAAC;IAChH,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;QACjC,IAAI,CAAE,CAAmB,CAAC,UAAU,CAAC;YAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,8BAA8B;QACpF,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC,EAAE,0BAA0B,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;QAC/F,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,IAAa,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,CAAU;IACjC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAK,CAA6B,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;AAC/F,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/dist/plugin/load.d.ts

@@ -0,0 +1,2 @@
+import { type Plugin } from './define.js';
+export declare function loadPlugins(dir: string | URL): Promise<Plugin[]>;

package/dist/plugin/load.js

@@ -0,0 +1,41 @@
+/**
+ * loadPlugins(dir) — imports every plugin file in a folder, so adding a tool is adding a file.
+ *
+ *   await run({ plugins: [...builtinPlugins, ...(await loadPlugins(new URL('./plugins/', import.meta.url)))] });
+ *
+ * Loads *.ts / *.js / *.mts / *.mjs in name order. Skips *.d.ts, *.test.*, *.spec.* and names starting
+ * with "_" or ".". Each file's default export must be a plugin made with definePlugin.
+ * Works under tsx (src/*.ts) and after tsc (dist/*.js) with the same import.meta.url-relative path.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isPlugin } from './define.js';
+const PLUGIN_FILE = /\.(m?[jt]s)$/;
+const SKIP = /(\.d\.[mc]?ts$)|(\.(test|spec)\.[mc]?[jt]s$)|(\.map$)/;
+export async function loadPlugins(dir) {
+    const path = dir instanceof URL ? fileURLToPath(dir) : dir;
+    if (!existsSync(path))
+        return [];
+    const files = readdirSync(path)
+        .filter((f) => PLUGIN_FILE.test(f) && !SKIP.test(f) && !f.startsWith('_') && !f.startsWith('.'))
+        .filter((f) => statSync(join(path, f)).isFile())
+        .sort();
+    const out = [];
+    for (const f of files) {
+        const full = join(path, f);
+        let mod;
+        try {
+            mod = (await import(pathToFileURL(full).href));
+        }
+        catch (e) {
+            throw new Error(`[plugin] failed to load ${full}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (!isPlugin(mod.default)) {
+            throw new Error(`[plugin] ${full}: the default export must be definePlugin({...})`);
+        }
+        out.push(mod.default);
+    }
+    return out;
+}
+//# sourceMappingURL=load.js.map

package/dist/plugin/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/plugin/load.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAe,MAAM,aAAa,CAAC;AAEpD,MAAM,WAAW,GAAG,cAAc,CAAC;AACnC,MAAM,IAAI,GAAG,uDAAuD,CAAC;AAErE,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAiB;IACjD,MAAM,IAAI,GAAG,GAAG,YAAY,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC3D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC;SAC5B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;SAC/F,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SAC/C,IAAI,EAAE,CAAC;IACV,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC3B,IAAI,GAA0B,CAAC;QAC/B,IAAI,CAAC;YACH,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAA0B,CAAC;QAC1E,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACpG,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,kDAAkD,CAAC,CAAC;QACtF,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/plugin/ping.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Health check tool — always listed, no permission group. Shows who you are and which plugins are on.
+ * Call it first when a tool you just added does not show up.
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { AuthContext } from '../core/auth.js';
+import type { Registry } from './registry.js';
+export declare const pingTool: Tool;
+export declare function handlePing(registry: Registry, auth: AuthContext, args: unknown): import("./define.js").ToolResult;

package/dist/plugin/ping.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { VERSION } from '../version.js';
+import { inputJsonSchema, textResult } from './result.js';
+const input = z.object({
+    echo: z.string().default('pong').describe('Returned as is. Default "pong".'),
+});
+export const pingTool = {
+    name: 'ping',
+    description: 'Health check. Verifies the server, your auth and which plugins are on. ' +
+        'Call it first when a tool you expect is missing.',
+    inputSchema: inputJsonSchema('ping', input),
+};
+export function handlePing(registry, auth, args) {
+    const { echo } = input.parse(args ?? {});
+    const admin = auth.role === 'admin';
+    return textResult(JSON.stringify({
+        ok: true,
+        echo,
+        server: 'knowledge-mcp',
+        version: VERSION,
+        timestamp: new Date().toISOString(),
+        authenticated_as: auth.email ?? auth.org_id ?? null,
+        role: auth.role ?? null,
+        // Plugin on/off is useful to everyone; the reason (env names) only to admins.
+        plugins: registry.status().map((p) => (admin ? { id: p.id, enabled: p.enabled, reason: p.reason } : { id: p.id, enabled: p.enabled })),
+        upstreams: admin ? registry.upstreams.statuses() : undefined,
+    }, null, 2));
+}
+//# sourceMappingURL=ping.js.map

package/dist/plugin/ping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ping.js","sourceRoot":"","sources":["../../src/plugin/ping.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,iCAAiC,CAAC;CAC7E,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAS;IAC5B,IAAI,EAAE,MAAM;IACZ,WAAW,EACT,yEAAyE;QACzE,kDAAkD;IACpD,WAAW,EAAE,eAAe,CAAC,MAAM,EAAE,KAAK,CAAwB;CACnE,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,QAAkB,EAAE,IAAiB,EAAE,IAAa;IAC7E,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC;IACpC,OAAO,UAAU,CACf,IAAI,CAAC,SAAS,CACZ;QACE,EAAE,EAAE,IAAI;QACR,IAAI;QACJ,MAAM,EAAE,eAAe;QACvB,OAAO,EAAE,OAAO;QAChB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,gBAAgB,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI;QACnD,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI;QACvB,8EAA8E;QAC9E,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACtI,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,SAAS;KAC7D,EACD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;AACJ,CAAC"}