create-knowledge-mcp 0.0.0-stage → 0.3.0

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,22 @@
-# Temporary Holding Version
+# create-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.
+Scaffolds your own [Knowledge MCP](https://github.com/chanthr/internal-mcp) server.
+
+```bash
+npx create-knowledge-mcp my-mcp
+# or: npm create knowledge-mcp@latest my-mcp
+cd my-mcp
+npm run dev
+```
+
+You get `src/server.ts`, an example plugin in `src/plugins/notes.ts`, `.env`, a `Dockerfile` and a README.
+Add a tool by adding a file to `src/plugins/`.
+
+| Option | Meaning |
+| --- | --- |
+| `--no-install` | Skip installing packages |
+| `--no-git` | Skip `git init` |
+
+Installs with the package manager that ran it (npm, pnpm, yarn or bun). Requires Node 22.13 or later.
+
+MIT © chanthr

package/index.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * create-knowledge-mcp — scaffolds your own Knowledge MCP server.
+ *
+ *   npx create-knowledge-mcp my-mcp            # or: npm create knowledge-mcp@latest my-mcp
+ *   npx create-knowledge-mcp my-mcp --no-install --no-git
+ *
+ * No dependencies: copies ./template, fills in the project name and the framework version, installs
+ * packages with the package manager that ran it (npm, pnpm, yarn or bun), and prints the next steps.
+ * KMCP_CORE_SPEC overrides the @chnxthr/knowledge-mcp dependency (tests use a local tarball).
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+
+const HERE = fileURLToPath(new URL('.', import.meta.url));
+const TEMPLATE = join(HERE, 'template');
+const VERSION = JSON.parse(readFileSync(join(HERE, 'package.json'), 'utf8')).version;
+const CORE = '@chnxthr/knowledge-mcp';
+// npm drops .gitignore from published packages, so the template keeps it as _gitignore.
+const RENAMES = { _gitignore: '.gitignore', _dockerignore: '.dockerignore' };
+
+const tty = process.stdout.isTTY && !process.env.NO_COLOR;
+const bold = (s) => (tty ? `\x1b[1m${s}\x1b[22m` : s);
+const dim = (s) => (tty ? `\x1b[2m${s}\x1b[22m` : s);
+const green = (s) => (tty ? `\x1b[32m${s}\x1b[39m` : s);
+
+function parseArgs(argv) {
+  const opts = { dir: undefined, install: true, git: true, help: false };
+  for (const a of argv) {
+    if (a === '--no-install') opts.install = false;
+    else if (a === '--no-git') opts.git = false;
+    else if (a === '-h' || a === '--help') opts.help = true;
+    else if (a.startsWith('-')) throw new Error(`unknown option ${a}`);
+    else if (!opts.dir) opts.dir = a;
+    else throw new Error(`unexpected argument ${a}`);
+  }
+  return opts;
+}
+
+/** npm package name rules, simplified: lowercase, url-safe, no leading dot or underscore. */
+export function toPackageName(dir) {
+  return (
+    basename(resolve(dir))
+      .toLowerCase()
+      .replace(/[^a-z0-9._~-]+/g, '-')
+      .replace(/^[._-]+|[-]+$/g, '') || 'my-knowledge-mcp'
+  );
+}
+
+/** Which package manager started us (npm_config_user_agent = "pnpm/9.0.0 npm/? node/v22 ..."). */
+export function detectPackageManager(userAgent = process.env.npm_config_user_agent ?? '') {
+  const name = userAgent.split(' ')[0]?.split('/')[0];
+  return ['pnpm', 'yarn', 'bun'].includes(name) ? name : 'npm';
+}
+
+function isEmptyDir(path) {
+  return !existsSync(path) || readdirSync(path).filter((f) => f !== '.git' && f !== '.DS_Store').length === 0;
+}
+
+function fill(path, vars) {
+  let s = readFileSync(path, 'utf8');
+  for (const [k, v] of Object.entries(vars)) s = s.split(`__${k}__`).join(v);
+  writeFileSync(path, s);
+}
+
+/** Copy the template into `target` and fill placeholders. Exported for tests. */
+export function scaffold(target, { name, coreSpec }) {
+  mkdirSync(target, { recursive: true });
+  cpSync(TEMPLATE, target, { recursive: true });
+  for (const [from, to] of Object.entries(RENAMES)) {
+    if (existsSync(join(target, from))) renameSync(join(target, from), join(target, to));
+  }
+  const vars = { NAME: name, CORE_SPEC: coreSpec, VERSION };
+  for (const f of ['package.json', 'README.md']) fill(join(target, f), vars);
+  if (!existsSync(join(target, '.env'))) cpSync(join(target, '.env.example'), join(target, '.env'));
+}
+
+async function ask(question, fallback) {
+  if (!process.stdin.isTTY) return fallback;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const a = (await rl.question(`${question} ${dim(`(${fallback})`)} `)).trim();
+    return a || fallback;
+  } finally {
+    rl.close();
+  }
+}
+
+function run(cmd, args, cwd) {
+  const r = spawnSync(cmd, args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' });
+  return r.status === 0;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    console.log(`Usage: npx create-knowledge-mcp [dir] [--no-install] [--no-git]`);
+    return;
+  }
+  const dir = opts.dir ?? (await ask('Project folder?', 'my-knowledge-mcp'));
+  const target = resolve(dir);
+  if (!isEmptyDir(target)) throw new Error(`${target} is not empty — pick a new folder`);
+
+  const name = toPackageName(dir);
+  const coreSpec = process.env.KMCP_CORE_SPEC || `^${VERSION}`;
+  scaffold(target, { name, coreSpec });
+  console.log(`\n${green('✓')} Created ${bold(name)} in ${target}`);
+
+  const pm = detectPackageManager();
+  if (opts.install) {
+    console.log(dim(`\n${pm} install …`));
+    if (!run(pm, ['install'], target)) console.log(`\n${pm} install failed — run it yourself inside ${dir}.`);
+  }
+  if (opts.git && !existsSync(join(target, '.git'))) {
+    spawnSync('git', ['init', '-q'], { cwd: target, stdio: 'ignore' });
+  }
+
+  const runScript = pm === 'npm' ? 'npm run' : pm;
+  const tsx = join(target, 'node_modules', '.bin', 'tsx');
+  console.log(`
+${bold('Next')}
+  cd ${dir}
+  ${runScript} dev                                  ${dim('# http://localhost:8080/mcp, reloads on save')}
+  ${runScript} keys -- create --email you@example.com --role admin   ${dim('# prints an API key once')}
+
+${bold('Add a tool')}
+  Copy src/plugins/notes.ts to src/plugins/<name>.ts and edit it. Every file there is loaded.
+
+${bold('Use it from Claude Code (local, no key needed)')}
+  claude mcp add ${name} -- ${tsx} ${join(target, 'src', 'server.ts')} serve --stdio
+
+${bold('Check what is on')}
+  ${runScript} doctor
+`);
+}
+
+// Run only as a command (npx goes through a bin symlink, hence realpath), not when imported by tests.
+const isMain = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  main().catch((e) => {
+    console.error(`create-knowledge-mcp: ${e instanceof Error ? e.message : e}`);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "create-knowledge-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Create your own Knowledge MCP server: npx create-knowledge-mcp my-mcp",
+  "type": "module",
+  "license": "MIT",
+  "author": "chanthr",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chanthr/internal-mcp.git",
+    "directory": "packages/create-knowledge-mcp"
+  },
+  "homepage": "https://github.com/chanthr/internal-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/chanthr/internal-mcp/issues"
+  },
+  "keywords": ["mcp", "model-context-protocol", "create", "scaffold", "mcp-server"],
+  "bin": {
+    "create-knowledge-mcp": "index.js"
+  },
+  "files": ["index.js", "template", "README.md", "LICENSE"],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/.env.example

@@ -0,0 +1,35 @@
+# ── Server ─────────────────────────────────────────────────────────────────
+PORT=8080
+# MCP_TRANSPORT=stdio                 # or pass `serve --stdio`
+# MCP_DATA_DIR=./data                 # SQLite store and checkpoints (default ./data)
+# MCP_STORE=supabase                  # use Supabase instead of the SQLite file
+# SUPABASE_URL=
+# SUPABASE_SERVICE_ROLE_KEY=
+
+# ── Your plugins ───────────────────────────────────────────────────────────
+# Put the env vars your plugins read here (declare them in `env: [...]` so the tools stay hidden until set).
+
+# ── Built-in connectors (each turns on when its vars are set) ───────────────
+# Google Drive: one of these, plus drive.roots in mcp.config.json
+# GOOGLE_SERVICE_ACCOUNT_KEY=
+# GOOGLE_OAUTH_CLIENT_ID=
+# GOOGLE_OAUTH_CLIENT_SECRET=
+# GOOGLE_OAUTH_REFRESH_TOKEN=
+# Semantic search over Drive
+# QDRANT_URL=
+# QDRANT_API_KEY=
+# OPENAI_API_KEY=
+# Slack (bot token for reading, user token adds search)
+# SLACK_BOT_TOKEN=
+# SLACK_USER_TOKEN=
+# GitHub (Contents: read)
+# GITHUB_TOKEN=
+# Railway
+# RAILWAY_TOKEN=
+
+# ── Sign-in for Claude web/desktop connectors (optional, see OAUTH_SETUP.md) ──
+# MCP_OAUTH_ISSUER=https://mcp.example.com
+# OAUTH_GOOGLE_CLIENT_ID=
+# OAUTH_GOOGLE_CLIENT_SECRET=
+# OAUTH_JWT_SECRET=
+# OAUTH_ALLOWED_HD=example.com

package/template/Dockerfile

@@ -0,0 +1,26 @@
+# Your Knowledge MCP server as a container.
+#   docker build -t my-mcp .
+#   docker run -d -p 8080:8080 -v my-mcp-data:/data --env-file .env my-mcp
+#   docker exec <container> node dist/server.js keys create --email you@example.com --role admin
+FROM node:22-alpine AS build
+WORKDIR /app
+COPY package*.json ./
+RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi
+COPY tsconfig.json ./
+COPY src ./src
+RUN npm run build && npm prune --omit=dev
+
+FROM node:22-alpine
+WORKDIR /app
+RUN addgroup -S app && adduser -S -G app -h /app app && mkdir -p /data && chown app:app /data
+COPY --from=build --chown=app:app /app/node_modules ./node_modules
+COPY --from=build --chown=app:app /app/dist ./dist
+COPY --chown=app:app package.json ./
+USER app
+ENV NODE_ENV=production MCP_TRANSPORT=http PORT=8080 MCP_DATA_DIR=/data
+VOLUME /data
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD wget -qO- "http://127.0.0.1:${PORT}/health" >/dev/null || exit 1
+ENTRYPOINT ["node", "dist/server.js"]
+CMD ["serve"]

package/template/README.md

@@ -0,0 +1,75 @@
+# __NAME__
+
+Your own MCP server, built on [Knowledge MCP](https://github.com/chanthr/internal-mcp) __VERSION__.
+Each file in `src/plugins/` is a plugin that adds tools. The built-in Google Drive, Slack, GitHub and Railway
+plugins turn on when you set their env vars in `.env`.
+
+## Run
+
+```bash
+npm run dev                                               # http://localhost:8080/mcp, reloads on save
+npm run keys -- create --email you@example.com --role admin   # prints an API key once
+npm run doctor                                            # which plugins are on, and what each one is missing
+```
+
+Clients send the key as `Authorization: Bearer <key>`. State (keys, users, plugin data) lives in `./data`.
+
+## Add a tool
+
+Copy `src/plugins/notes.ts` to `src/plugins/<name>.ts` and edit it:
+
+```ts
+import { definePlugin, defineTool, z } from '@chnxthr/knowledge-mcp';
+
+export default definePlugin({
+  id: 'weather',                 // also the permission group
+  env: ['WEATHER_API_KEY'],      // tools stay hidden until this is set
+  tools: [
+    defineTool({
+      name: 'weather_now',
+      description: 'Current weather for a city',
+      input: z.object({ city: z.string().describe('City name') }),
+      annotations: { readOnlyHint: true },
+      run: async ({ city }) => {
+        const r = await fetch(`https://api.example.com/weather?q=${encodeURIComponent(city)}`, {
+          headers: { Authorization: `Bearer ${process.env.WEATHER_API_KEY}` },
+        });
+        return r.json();         // string, any JSON value, or a full MCP result
+      },
+    }),
+  ],
+});
+```
+
+`run` gets the validated input and a context: `ctx.user` (email, role), `ctx.state` (persistent key-value
+storage for this plugin), `ctx.config` (`plugins.<id>` from `mcp.config.json`) and `ctx.log`.
+Throw `ToolError` for an expected failure. Files starting with `_` are skipped.
+
+## Connect a client
+
+| Client | How |
+| --- | --- |
+| Claude Code (local) | `claude mcp add __NAME__ -- node /absolute/path/__NAME__/dist/server.js serve --stdio` after `npm run build` |
+| Any HTTP client | URL `http://localhost:8080/mcp`, header `Authorization: Bearer <key>` |
+| Claude web and desktop connectors | Deploy behind HTTPS and turn on OAuth ([guide](https://github.com/chanthr/internal-mcp/blob/main/OAUTH_SETUP.md)) |
+
+stdio runs as the local admin unless you set `MCP_API_KEY`.
+
+## Permissions
+
+```bash
+npm run users -- add teammate@example.com --role member --tools notes,drive
+```
+
+Admins see every plugin. Members see every plugin unless `--tools` limits them. Signed-in people without
+a users entry are viewers: they get `ping` and the plugins listed in `access.viewerTools` of `mcp.config.json`.
+
+## Deploy
+
+```bash
+docker build -t __NAME__ .
+docker run -d -p 8080:8080 -v __NAME__-data:/data --env-file .env __NAME__
+docker exec <container> node dist/server.js keys create --email you@example.com --role admin
+```
+
+Keep `/data` on a volume, or set `MCP_STORE=supabase` to keep state in Supabase.

package/template/_dockerignore

@@ -0,0 +1,9 @@
+node_modules
+dist
+data
+.env
+.env.*
+.git
+*.log
+mcp.config.json
+*-service-account.json

package/template/_gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+data/
+.env
+.env.local
+*.log
+.DS_Store
+mcp.config.json
+*-service-account.json

package/template/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "__NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts serve",
+    "build": "tsc",
+    "start": "node dist/server.js serve",
+    "keys": "tsx src/server.ts keys",
+    "users": "tsx src/server.ts users",
+    "doctor": "tsx src/server.ts doctor",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@chnxthr/knowledge-mcp": "__CORE_SPEC__"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  }
+}

package/template/src/plugins/notes.ts

@@ -0,0 +1,44 @@
+/**
+ * Example plugin — copy this file to add your own tools. Each file in src/plugins is one plugin.
+ *
+ * The plugin id ("notes") is also its permission group: admins see it, members see it unless their
+ * allowed tools exclude it, and viewers see it only if config access.viewerTools lists it.
+ */
+import { definePlugin, defineTool, ToolError, z } from '@chnxthr/knowledge-mcp';
+
+type Note = { text: string; by: string; at: string };
+
+export default definePlugin({
+  id: 'notes',
+  description: 'Shared team notes (example plugin)',
+  // env: ['MY_API_KEY'],       // tools stay hidden until these env vars are set
+  instructions: 'Notes: save short facts with notes_add, read them back with notes_list.',
+  tools: [
+    defineTool({
+      name: 'notes_add',
+      description: 'Save a short note for the team.',
+      input: z.object({
+        text: z.string().min(1).max(500).describe('The note'),
+      }),
+      run: async ({ text }, ctx) => {
+        const notes = (await ctx.state.get<Note[]>('all')) ?? [];
+        notes.push({ text, by: ctx.user.email ?? 'unknown', at: new Date().toISOString() });
+        await ctx.state.set('all', notes.slice(-200));
+        return `Saved. ${notes.length} notes in total.`;
+      },
+    }),
+    defineTool({
+      name: 'notes_list',
+      description: 'List the saved team notes, newest first.',
+      input: z.object({
+        limit: z.number().int().min(1).max(50).default(10).describe('How many notes'),
+      }),
+      annotations: { readOnlyHint: true },
+      run: async ({ limit }, ctx) => {
+        const notes = (await ctx.state.get<Note[]>('all')) ?? [];
+        if (!notes.length) throw new ToolError('No notes yet. Add one with notes_add.');
+        return notes.slice(-limit).reverse(); // any JSON value is returned as pretty JSON
+      },
+    }),
+  ],
+});

package/template/src/server.ts

@@ -0,0 +1,11 @@
+/**
+ * Your MCP server. Every file in ./plugins is loaded as a plugin; the built-in Drive, Slack, GitHub and
+ * Railway plugins turn on when their env vars are set (.env). `npm run doctor` shows what is on.
+ *
+ * The same file is the command line: serve, serve --stdio, keys, users, doctor, <plugin> <command>.
+ */
+import { run, builtinPlugins, loadPlugins } from '@chnxthr/knowledge-mcp';
+
+const mine = await loadPlugins(new URL('./plugins/', import.meta.url));
+
+await run({ plugins: [...builtinPlugins, ...mine] });

package/template/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"]
+}