@chnxthr/knowledge-mcp 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chanthr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @chnxthr/knowledge-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build your team's own MCP server from plugins. API keys, Google sign-in (OAuth 2.1), per-person permissions,
+an audit log and a SQLite or Supabase store are built in, and so are Google Drive, Slack, GitHub and Railway.
+
+```bash
+npx create-knowledge-mcp my-mcp     # a ready project with an example plugin
+```
+
+```ts
+// src/plugins/weather.ts — every file in src/plugins is a plugin
+import { definePlugin, defineTool, z } from '@chnxthr/knowledge-mcp';
+
+export default definePlugin({
+  id: 'weather',
+  env: ['WEATHER_API_KEY'],
+  tools: [
+    defineTool({
+      name: 'weather_now',
+      description: 'Current weather for a city',
+      input: z.object({ city: z.string().describe('City name') }),
+      run: async ({ city }) => (await fetch(`https://api.example.com/weather?q=${city}`)).json(),
+    }),
+  ],
+});
+```
+
+Run it without a project too:
+
+```bash
+npx @chnxthr/knowledge-mcp doctor        # which built-in connectors are on
+npx @chnxthr/knowledge-mcp keys create --email you@example.com --role admin
+npx @chnxthr/knowledge-mcp serve         # http://localhost:8080/mcp
+```
+
+Requires Node 22.13 or later. Documentation: https://github.com/chanthr/internal-mcp
+
+MIT © chanthr

package/dist/bootstrap.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bootstrap.js

@@ -0,0 +1,18 @@
+/**
+ * Side effects that must run before any other module of the package is evaluated.
+ * index.ts imports this first: ESM evaluates imports in order, and several modules read process.env
+ * when they load, so .env has to be in place before them.
+ *
+ *   1. Load .env — MCP_ENV_FILE if set, else ./.env and <app root>/.env. Existing env vars win.
+ *   2. Mask secrets in every console.* line.
+ */
+import { existsSync } from 'node:fs';
+import { config as loadDotenv } from 'dotenv';
+import { candidates } from './core/paths.js';
+import { installLogMasking } from './core/log_mask.js';
+const explicit = process.env.MCP_ENV_FILE;
+const files = explicit ? [explicit] : candidates('.env').filter((f) => existsSync(f));
+for (const path of files)
+    loadDotenv({ path, quiet: true });
+installLogMasking();
+//# sourceMappingURL=bootstrap.js.map

package/dist/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;AAC1C,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACtF,KAAK,MAAM,IAAI,IAAI,KAAK;IAAE,UAAU,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAE5D,iBAAiB,EAAE,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/** `knowledge-mcp` binary — the server with the built-in plugins (Drive, Slack, GitHub, Railway). */
+import { run } from './index.js';
+await run();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,qGAAqG;AACrG,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEjC,MAAM,GAAG,EAAE,CAAC"}

package/dist/core/auth.d.ts

@@ -0,0 +1,38 @@
+/**
+ * admin  = every tool.
+ * member = a registered user (app_users row); limited by allowed_tools when set. Called "engineer" before 0.3.
+ * viewer = signed in but not registered; only `ping` and the groups in config access.viewerTools.
+ */
+export type Role = 'admin' | 'member' | 'viewer';
+/** 상수시간 문자열 비교 — sha256 으로 길이 정규화 후 timingSafeEqual (타이밍 누출 방지). oauth.ts 도 사용. */
+export declare function timingSafeEqualStr(a: string, b: string): boolean;
+/**
+ * 직원별 리소스 스코프 (app_users 의 allowed_* 컬럼에서 옴).
+ * 각 필드 null/undefined/빈배열 = 그 차원은 전체 허용(미설정). admin role 은 scope 무시 전체.
+ */
+export type ResourceScopes = {
+    slackChannels?: string[] | null;
+    driveFolders?: string[] | null;
+    tools?: string[] | null;
+};
+export type AuthContext = {
+    ok: boolean;
+    reason?: string;
+    org_id?: string;
+    role?: Role;
+    email?: string;
+    key_id?: string;
+    scopes?: ResourceScopes;
+    /** act-as(내부 프록시 위임) 경로로 들어온 요청인가. 프록시 키 유출에 대비해 고권한 도구를 막을 때 쓴다. */
+    actAs?: boolean;
+};
+export declare function authenticateApiKey(key: string | undefined): Promise<AuthContext>;
+/**
+ * 도구별 role 가드. 예: 쓰기 도구는 admin 만.
+ *
+ * 사용 예:
+ *   if (!requireRole(auth, 'admin', 'member')) {
+ *     return errorResponse('forbidden — role insufficient');
+ *   }
+ */
+export declare function requireRole(auth: AuthContext, ...allowed: Role[]): boolean;

package/dist/core/auth.js

@@ -0,0 +1,93 @@
+/**
+ * Knowledge MCP — API key auth.
+ *
+ * Keys are checked against the store (SQLite file or Supabase `validate_mcp_key`). Only a SHA-256 hash
+ * of each key is stored. Create keys with `knowledge-mcp keys create`.
+ */
+import { createHash, timingSafeEqual } from 'crypto';
+import { getStore } from '../store/index.js';
+import { getConfig } from './config.js';
+/** 상수시간 문자열 비교 — sha256 으로 길이 정규화 후 timingSafeEqual (타이밍 누출 방지). oauth.ts 도 사용. */
+export function timingSafeEqualStr(a, b) {
+    const ha = createHash('sha256').update(a).digest();
+    const hb = createHash('sha256').update(b).digest();
+    return timingSafeEqual(ha, hb);
+}
+// ── 인증 결과 TTL 캐시 ──
+// HTTP transport 는 도구 호출 1건 = 요청 1건 = validate_mcp_key RPC 1회.
+// 챗봇 ReAct 루프(여러 도구)·여러 사용자가 몰리면 같은 key 로 RPC 가 다발 →
+// 짧은 TTL 캐시로 DB 왕복을 줄인다. (key revoke 반영 지연은 최대 TTL 초)
+const AUTH_CACHE_TTL_MS = Number(process.env.AUTH_CACHE_TTL_MS ?? 60_000);
+const AUTH_CACHE_MAX = 500; // hard cap 백스톱 — key 회전이 많아도 무한 증가 방지(B-15)
+const _authCache = new Map();
+/** 만료 항목 제거 + cap 초과 시 가장 오래된 것부터 정리 (단일 인스턴스 in-memory 캐시 누수 방지). */
+function setAuthCache(key, auth) {
+    const now = Date.now();
+    for (const [k, v] of _authCache)
+        if (v.expiresAt <= now)
+            _authCache.delete(k);
+    while (_authCache.size >= AUTH_CACHE_MAX) {
+        const oldest = _authCache.keys().next().value; // Map 삽입 순서 = 오래된 것 먼저
+        if (oldest === undefined)
+            break;
+        _authCache.delete(oldest);
+    }
+    _authCache.set(key, { auth, expiresAt: now + AUTH_CACHE_TTL_MS });
+}
+export async function authenticateApiKey(key) {
+    if (!key) {
+        return { ok: false, reason: 'MCP_API_KEY not provided' };
+    }
+    // Day 1 호환: 단일 dev key — **stdio(로컬 dev) 전용**.
+    // HTTP(production)에선 비활성(P2): 정적 문자열 1개가 감사 식별자 없는 admin 백도어가 되므로,
+    // 프로덕션 인증은 mcp_keys(해시 저장·revoke·expiry) 경로만 허용한다.
+    const devKey = process.env.MCP_DEV_KEY;
+    const transport = (process.env.MCP_TRANSPORT || 'http').toLowerCase();
+    if (devKey && transport === 'stdio' && timingSafeEqualStr(key, devKey)) {
+        return {
+            ok: true,
+            org_id: getConfig().orgId,
+            role: 'admin',
+            email: 'dev@local',
+        };
+    }
+    // 캐시 hit (성공 결과만 캐시 — 실패는 매번 재검증해 빠른 키 활성화 반영)
+    const cached = _authCache.get(key);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.auth;
+    }
+    // 저장소(SQLite 파일 또는 Supabase validate_mcp_key RPC)에서 해시로 조회
+    try {
+        const store = await getStore();
+        const r = await store.validateKey(key);
+        if (!r.ok)
+            return { ok: false, reason: r.reason };
+        const auth = {
+            ok: true,
+            org_id: r.orgId ?? getConfig().orgId,
+            role: r.role,
+            email: r.email ?? undefined,
+            key_id: r.keyId,
+        };
+        setAuthCache(key, auth);
+        return auth;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { ok: false, reason: `auth error: ${msg}` };
+    }
+}
+/**
+ * 도구별 role 가드. 예: 쓰기 도구는 admin 만.
+ *
+ * 사용 예:
+ *   if (!requireRole(auth, 'admin', 'member')) {
+ *     return errorResponse('forbidden — role insufficient');
+ *   }
+ */
+export function requireRole(auth, ...allowed) {
+    if (!auth.ok || !auth.role)
+        return false;
+    return allowed.includes(auth.role);
+}
+//# sourceMappingURL=auth.js.map

package/dist/core/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/core/auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AASxC,mFAAmF;AACnF,MAAM,UAAU,kBAAkB,CAAC,CAAS,EAAE,CAAS;IACrD,MAAM,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACnD,MAAM,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACnD,OAAO,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAwBD,qBAAqB;AACrB,+DAA+D;AAC/D,qDAAqD;AACrD,sDAAsD;AACtD,MAAM,iBAAiB,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,MAAM,CAAC,CAAC;AAC1E,MAAM,cAAc,GAAG,GAAG,CAAC,CAAC,4CAA4C;AACxE,MAAM,UAAU,GAAG,IAAI,GAAG,EAAoD,CAAC;AAE/E,sEAAsE;AACtE,SAAS,YAAY,CAAC,GAAW,EAAE,IAAiB;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,UAAU;QAAE,IAAI,CAAC,CAAC,SAAS,IAAI,GAAG;YAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC9E,OAAO,UAAU,CAAC,IAAI,IAAI,cAAc,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,uBAAuB;QACtE,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM;QAChC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IACD,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,GAAG,iBAAiB,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,GAAuB;IAEvB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;IAC3D,CAAC;IAED,+CAA+C;IAC/C,mEAAmE;IACnE,mDAAmD;IACnD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IACvC,MAAM,SAAS,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;IACtE,IAAI,MAAM,IAAI,SAAS,KAAK,OAAO,IAAI,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC;QACvE,OAAO;YACL,EAAE,EAAE,IAAI;YACR,MAAM,EAAE,SAAS,EAAE,CAAC,KAAK;YACzB,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,WAAW;SACnB,CAAC;IACJ,CAAC;IAED,+CAA+C;IAC/C,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QAC5C,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAED,2DAA2D;IAC3D,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,QAAQ,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,CAAC,CAAC,EAAE;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;QAClD,MAAM,IAAI,GAAgB;YACxB,EAAE,EAAE,IAAI;YACR,MAAM,EAAE,CAAC,CAAC,KAAK,IAAI,SAAS,EAAE,CAAC,KAAK;YACpC,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,SAAS;YAC3B,MAAM,EAAE,CAAC,CAAC,KAAK;SAChB,CAAC;QACF,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QACpB,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,GAAG,EAAE,EAAE,CAAC;IACrD,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,IAAiB,EAAE,GAAG,OAAe;IAC/D,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACzC,OAAO,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC"}

package/dist/core/config.d.ts

@@ -0,0 +1,259 @@
+import { z } from 'zod';
+/** First line of the server instructions. Each enabled plugin appends its own notes (plugin `instructions`). */
+export declare const BASE_INSTRUCTIONS = "Knowledge MCP \u2014 tools over your team's data. Answer only from tool results; do not speculate.";
+/**
+ * A Drive folder to index. `source` is an indexing hint:
+ *   - "dev": structured knowledge docs (Markdown with frontmatter)
+ *   - "biz": general documents (PDF/DOCX/etc.)
+ * If you have one kind of content, just use "dev" for everything.
+ */
+declare const DriveRootSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    source: z.ZodEnum<["dev", "biz"]>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    source: "dev" | "biz";
+}, {
+    id: string;
+    name: string;
+    source: "dev" | "biz";
+}>;
+declare const UpstreamConfigSchema: z.ZodObject<{
+    /** Permission group and log name. Lowercase letters, digits and dashes. */
+    name: z.ZodString;
+    /** Streamable HTTP endpoint, e.g. https://mcp.example.com/mcp */
+    url: z.ZodString;
+    /** Tool name prefix. Default "<name>_" with dashes turned into underscores. */
+    prefix: z.ZodOptional<z.ZodString>;
+    /** Name of the env var holding the bearer token (the token itself never goes in this file). */
+    tokenEnv: z.ZodOptional<z.ZodString>;
+    /** Extra request headers (no secrets — use tokenEnv). */
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /** "read" (default): only read-verb tools. "all": everything. Or an explicit list of remote tool names. */
+    expose: z.ZodDefault<z.ZodUnion<[z.ZodEnum<["read", "all"]>, z.ZodArray<z.ZodString, "many">]>>;
+}, "strict", z.ZodTypeAny, {
+    url: string;
+    name: string;
+    expose: string[] | "read" | "all";
+    prefix?: string | undefined;
+    tokenEnv?: string | undefined;
+    headers?: Record<string, string> | undefined;
+}, {
+    url: string;
+    name: string;
+    prefix?: string | undefined;
+    tokenEnv?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    expose?: string[] | "read" | "all" | undefined;
+}>;
+declare const ConfigSchema: z.ZodObject<{
+    /** Organization identifier — flows into the auth context as org_id. */
+    orgId: z.ZodDefault<z.ZodString>;
+    branding: z.ZodDefault<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        /** Replaces the generated instructions (base line + each enabled plugin's notes) when set. */
+        instructions: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        instructions?: string | undefined;
+    }, {
+        name?: string | undefined;
+        instructions?: string | undefined;
+    }>>;
+    drive: z.ZodDefault<z.ZodObject<{
+        /** SSOT for index/search scope. Empty = Drive indexing disabled (tools still gated by credentials). */
+        roots: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            source: z.ZodEnum<["dev", "biz"]>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            name: string;
+            source: "dev" | "biz";
+        }, {
+            id: string;
+            name: string;
+            source: "dev" | "biz";
+        }>, "many">>;
+        /** Folder names to exclude from the search index (sensitive/backup). Merged with built-in dev-artifact names (node_modules etc.). */
+        excludeFolders: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        roots: {
+            id: string;
+            name: string;
+            source: "dev" | "biz";
+        }[];
+        excludeFolders: string[];
+    }, {
+        roots?: {
+            id: string;
+            name: string;
+            source: "dev" | "biz";
+        }[] | undefined;
+        excludeFolders?: string[] | undefined;
+    }>>;
+    qdrant: z.ZodDefault<z.ZodObject<{
+        /** Vector collection name. If env QDRANT_COLLECTION is set, it takes precedence (zero-downtime swap). */
+        collection: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        collection: string;
+    }, {
+        collection?: string | undefined;
+    }>>;
+    data: z.ZodDefault<z.ZodObject<{
+        /** Supabase schema holding the server's own tables (oauth clients, refresh tokens, sync_state, tool_calls, app_users). */
+        schema: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        schema: string;
+    }, {
+        schema?: string | undefined;
+    }>>;
+    /** Your own domains (used e.g. to distinguish first-party from external sources). */
+    selfDomains: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    oauth: z.ZodDefault<z.ZodObject<{
+        /**
+         * Google Workspace domains allowed to sign in (the account's `hd` claim must match).
+         * env OAUTH_ALLOWED_HD (comma-separated) takes precedence.
+         */
+        allowedDomains: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Individual emails allowed to sign in, in addition to the domains (any Google account type).
+         * env OAUTH_ALLOWED_EMAILS (comma-separated) takes precedence.
+         * If both lists are empty, OAuth stays off — otherwise any Google account could sign in.
+         */
+        allowedEmails: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        allowedDomains: string[];
+        allowedEmails: string[];
+    }, {
+        allowedDomains?: string[] | undefined;
+        allowedEmails?: string[] | undefined;
+    }>>;
+    access: z.ZodDefault<z.ZodObject<{
+        /**
+         * Tool groups a signed-in user WITHOUT an app_users row may use (role "viewer").
+         * A group is a plugin id (drive, slack, github, railway, or your own) or a config upstream name.
+         * Default: none, so unregistered users only get `ping`.
+         */
+        viewerTools: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        viewerTools: string[];
+    }, {
+        viewerTools?: string[] | undefined;
+    }>>;
+    /** Per-plugin settings: `plugins.<id>` is passed to that plugin as ctx.config. */
+    plugins: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Remote MCP servers to proxy. Their tools are listed as `<prefix><name>` in the group `name`. */
+    upstreams: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        /** Permission group and log name. Lowercase letters, digits and dashes. */
+        name: z.ZodString;
+        /** Streamable HTTP endpoint, e.g. https://mcp.example.com/mcp */
+        url: z.ZodString;
+        /** Tool name prefix. Default "<name>_" with dashes turned into underscores. */
+        prefix: z.ZodOptional<z.ZodString>;
+        /** Name of the env var holding the bearer token (the token itself never goes in this file). */
+        tokenEnv: z.ZodOptional<z.ZodString>;
+        /** Extra request headers (no secrets — use tokenEnv). */
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /** "read" (default): only read-verb tools. "all": everything. Or an explicit list of remote tool names. */
+        expose: z.ZodDefault<z.ZodUnion<[z.ZodEnum<["read", "all"]>, z.ZodArray<z.ZodString, "many">]>>;
+    }, "strict", z.ZodTypeAny, {
+        url: string;
+        name: string;
+        expose: string[] | "read" | "all";
+        prefix?: string | undefined;
+        tokenEnv?: string | undefined;
+        headers?: Record<string, string> | undefined;
+    }, {
+        url: string;
+        name: string;
+        prefix?: string | undefined;
+        tokenEnv?: string | undefined;
+        headers?: Record<string, string> | undefined;
+        expose?: string[] | "read" | "all" | undefined;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    data: {
+        schema: string;
+    };
+    orgId: string;
+    branding: {
+        name: string;
+        instructions?: string | undefined;
+    };
+    drive: {
+        roots: {
+            id: string;
+            name: string;
+            source: "dev" | "biz";
+        }[];
+        excludeFolders: string[];
+    };
+    qdrant: {
+        collection: string;
+    };
+    selfDomains: string[];
+    oauth: {
+        allowedDomains: string[];
+        allowedEmails: string[];
+    };
+    access: {
+        viewerTools: string[];
+    };
+    plugins: Record<string, unknown>;
+    upstreams: {
+        url: string;
+        name: string;
+        expose: string[] | "read" | "all";
+        prefix?: string | undefined;
+        tokenEnv?: string | undefined;
+        headers?: Record<string, string> | undefined;
+    }[];
+}, {
+    data?: {
+        schema?: string | undefined;
+    } | undefined;
+    orgId?: string | undefined;
+    branding?: {
+        name?: string | undefined;
+        instructions?: string | undefined;
+    } | undefined;
+    drive?: {
+        roots?: {
+            id: string;
+            name: string;
+            source: "dev" | "biz";
+        }[] | undefined;
+        excludeFolders?: string[] | undefined;
+    } | undefined;
+    qdrant?: {
+        collection?: string | undefined;
+    } | undefined;
+    selfDomains?: string[] | undefined;
+    oauth?: {
+        allowedDomains?: string[] | undefined;
+        allowedEmails?: string[] | undefined;
+    } | undefined;
+    access?: {
+        viewerTools?: string[] | undefined;
+    } | undefined;
+    plugins?: Record<string, unknown> | undefined;
+    upstreams?: {
+        url: string;
+        name: string;
+        prefix?: string | undefined;
+        tokenEnv?: string | undefined;
+        headers?: Record<string, string> | undefined;
+        expose?: string[] | "read" | "all" | undefined;
+    }[] | undefined;
+}>;
+export type AppConfig = z.infer<typeof ConfigSchema>;
+export type DriveRoot = z.infer<typeof DriveRootSchema>;
+export type UpstreamConfig = z.infer<typeof UpstreamConfigSchema>;
+/** Validated config (singleton). Loads and validates on first call; invalid config fails fast with a clear error. */
+export declare function getConfig(): AppConfig;
+/** Which config source was chosen (for boot logs / diagnostics). Valid after getConfig(). */
+export declare function configSource(): string;
+export {};

package/dist/core/config.js

@@ -0,0 +1,172 @@
+/**
+ * Deployment configuration — "what to look at" is kept out of the code.
+ *
+ * Credentials live in env (Supabase / Qdrant / Drive / Slack / GitHub keys). This module holds the
+ * rest: which Drive folders, which Qdrant collection, which Supabase schema, which domains. That
+ * lets anyone self-host by supplying their own config file — no code changes.
+ *
+ * Resolution order (first match wins):
+ *   1. MCP_CONFIG_JSON   — inline JSON (deploy-friendly: one env var, no file)
+ *   2. MCP_CONFIG_PATH   — explicit path to a JSON file
+ *   3. mcp.config.json   — in the working directory, then in the app root (see paths.ts)
+ *   4. (none)            — neutral built-in defaults (server boots; Drive indexing stays off until
+ *                          `drive.roots` is set)
+ *
+ * ⚠️ No secrets here. Never put keys/tokens in this file or the config JSON — those belong in env.
+ * This is only "what to look at".
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { candidates } from './paths.js';
+/** First line of the server instructions. Each enabled plugin appends its own notes (plugin `instructions`). */
+export const BASE_INSTRUCTIONS = 'Knowledge MCP — tools over your team\'s data. Answer only from tool results; do not speculate.';
+/**
+ * A Drive folder to index. `source` is an indexing hint:
+ *   - "dev": structured knowledge docs (Markdown with frontmatter)
+ *   - "biz": general documents (PDF/DOCX/etc.)
+ * If you have one kind of content, just use "dev" for everything.
+ */
+const DriveRootSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    source: z.enum(['dev', 'biz']),
+});
+const UpstreamConfigSchema = z
+    .object({
+    /** Permission group and log name. Lowercase letters, digits and dashes. */
+    name: z.string().regex(/^[a-z][a-z0-9-]{0,31}$/),
+    /** Streamable HTTP endpoint, e.g. https://mcp.example.com/mcp */
+    url: z.string().url(),
+    /** Tool name prefix. Default "<name>_" with dashes turned into underscores. */
+    prefix: z.string().regex(/^[a-z][a-z0-9_]*_$/).optional(),
+    /** Name of the env var holding the bearer token (the token itself never goes in this file). */
+    tokenEnv: z.string().optional(),
+    /** Extra request headers (no secrets — use tokenEnv). */
+    headers: z.record(z.string()).optional(),
+    /** "read" (default): only read-verb tools. "all": everything. Or an explicit list of remote tool names. */
+    expose: z.union([z.enum(['read', 'all']), z.array(z.string())]).default('read'),
+})
+    .strict();
+const ConfigSchema = z
+    .object({
+    /** Organization identifier — flows into the auth context as org_id. */
+    orgId: z.string().default('org'),
+    branding: z
+        .object({
+        name: z.string().default('Knowledge MCP'),
+        /** Replaces the generated instructions (base line + each enabled plugin's notes) when set. */
+        instructions: z.string().optional(),
+    })
+        .default({}),
+    drive: z
+        .object({
+        /** SSOT for index/search scope. Empty = Drive indexing disabled (tools still gated by credentials). */
+        roots: z.array(DriveRootSchema).default([]),
+        /** Folder names to exclude from the search index (sensitive/backup). Merged with built-in dev-artifact names (node_modules etc.). */
+        excludeFolders: z.array(z.string()).default([]),
+    })
+        .default({}),
+    qdrant: z
+        .object({
+        /** Vector collection name. If env QDRANT_COLLECTION is set, it takes precedence (zero-downtime swap). */
+        collection: z.string().default('knowledge_v1'),
+    })
+        .default({}),
+    data: z
+        .object({
+        /** Supabase schema holding the server's own tables (oauth clients, refresh tokens, sync_state, tool_calls, app_users). */
+        schema: z.string().default('public'),
+    })
+        .default({}),
+    /** Your own domains (used e.g. to distinguish first-party from external sources). */
+    selfDomains: z.array(z.string()).default([]),
+    oauth: z
+        .object({
+        /**
+         * Google Workspace domains allowed to sign in (the account's `hd` claim must match).
+         * env OAUTH_ALLOWED_HD (comma-separated) takes precedence.
+         */
+        allowedDomains: z.array(z.string()).default([]),
+        /**
+         * Individual emails allowed to sign in, in addition to the domains (any Google account type).
+         * env OAUTH_ALLOWED_EMAILS (comma-separated) takes precedence.
+         * If both lists are empty, OAuth stays off — otherwise any Google account could sign in.
+         */
+        allowedEmails: z.array(z.string()).default([]),
+    })
+        .default({}),
+    access: z
+        .object({
+        /**
+         * Tool groups a signed-in user WITHOUT an app_users row may use (role "viewer").
+         * A group is a plugin id (drive, slack, github, railway, or your own) or a config upstream name.
+         * Default: none, so unregistered users only get `ping`.
+         */
+        viewerTools: z.array(z.string()).default([]),
+    })
+        .default({}),
+    /** Per-plugin settings: `plugins.<id>` is passed to that plugin as ctx.config. */
+    plugins: z.record(z.unknown()).default({}),
+    /** Remote MCP servers to proxy. Their tools are listed as `<prefix><name>` in the group `name`. */
+    upstreams: z.array(UpstreamConfigSchema).default([]),
+})
+    .strict();
+let _source = 'defaults';
+/** Load the raw config object, or null if none is provided. Explicit/inline parse failures throw (fail fast). */
+function loadRawConfig() {
+    const inline = process.env.MCP_CONFIG_JSON;
+    if (inline && inline.trim()) {
+        try {
+            _source = 'env:MCP_CONFIG_JSON';
+            return JSON.parse(inline);
+        }
+        catch (e) {
+            throw new Error(`[config] failed to parse MCP_CONFIG_JSON: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    const explicitPath = process.env.MCP_CONFIG_PATH;
+    if (explicitPath) {
+        try {
+            const raw = readFileSync(explicitPath, 'utf8');
+            _source = `file:${explicitPath}`;
+            return JSON.parse(raw);
+        }
+        catch (e) {
+            throw new Error(`[config] failed to read MCP_CONFIG_PATH (${explicitPath}): ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    // Default locations may simply not exist → built-in defaults. A file that exists but is broken fails fast.
+    const path = candidates('mcp.config.json').find((p) => existsSync(p));
+    if (!path)
+        return null;
+    try {
+        _source = `file:${path}`;
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (e) {
+        throw new Error(`[config] failed to parse ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+let _config = null;
+/** Validated config (singleton). Loads and validates on first call; invalid config fails fast with a clear error. */
+export function getConfig() {
+    if (_config)
+        return _config;
+    const raw = loadRawConfig();
+    try {
+        _config = ConfigSchema.parse(raw === null ? {} : raw);
+    }
+    catch (e) {
+        if (e instanceof z.ZodError) {
+            const detail = e.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ');
+            throw new Error(`[config] validation failed — ${detail}`);
+        }
+        throw e;
+    }
+    return _config;
+}
+/** Which config source was chosen (for boot logs / diagnostics). Valid after getConfig(). */
+export function configSource() {
+    return _source;
+}
+//# sourceMappingURL=config.js.map