atheneum-mcp 0.1.0

package/.npmrc.ci

@@ -0,0 +1 @@
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Multi-instance Wiki.js support with path scoping and access controls
+- Google Drive folder prioritization with recursive search
+- YAML configuration with environment variable interpolation
+- CLI entry point with `auth` subcommand for Google OAuth
+- Configurable read-only mode, strict path enforcement, and path hiding per wiki instance
+- Paginated Drive search that fills results across API pages
+
+### Changed
+
+- Generalized from single-instance to reusable, config-driven package
+- Refactored wiki client from module functions to WikiClient class
+- Refactored drive client from module functions to DriveClient class
+- Google OAuth tokens now stored in `~/.config/atheneum-mcp/`
+- Configuration via YAML file or environment variables
+
+[Unreleased]: https://gitlab.com/morgul/atheneum-mcp/-/compare/v0.1.0...main

package/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2026 Christopher S. Case <chris.case@g33xnexus.com>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

package/README.md

@@ -0,0 +1,191 @@
+# atheneum-mcp
+
+An MCP (Model Context Protocol) server that connects AI assistants to Wiki.js and Google Drive.
+Supports multiple Wiki.js instances with path scoping and access controls, plus Google Drive with
+folder prioritization. Runs as a standalone stdio server, designed to be invoked via `npx`.
+
+**Requires Node.js 24+** (native TypeScript, no build step)
+
+## Quick Start
+
+The fastest way to get running with a single Wiki.js instance:
+
+```bash
+# Set environment variables
+export WIKIJS_URL="https://wiki.example.com"
+export WIKIJS_TOKEN="your-api-token"
+
+# Run directly
+npx atheneum-mcp
+```
+
+Or add it to your MCP client config (see [MCP Client Configuration](#mcp-client-configuration)).
+
+## YAML Configuration
+
+For multiple wikis, Drive integration, or path scoping, use a YAML config file.
+The server checks `./atheneum.yaml` by default, or pass `--config <path>` explicitly.
+
+```yaml
+wikis:
+  - name: docs
+    url: https://wiki.example.com
+    token: ${WIKI_TOKEN}
+    basePath: /docs
+    readOnly: true
+
+  - name: internal
+    url: https://internal-wiki.example.com
+    token: ${INTERNAL_WIKI_TOKEN}
+
+drive:
+  folders:
+    - "1abc123def456"
+  recursive: true
+  strictFolders: false
+```
+
+YAML values support `$VAR` and `${VAR}` interpolation, so you can keep secrets in environment
+variables or `.env` files.
+
+See `atheneum.example.yaml` for a full example with all options.
+
+## Google Drive Setup
+
+### 1. Create OAuth Credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a project (or use existing)
+3. Enable the Google Drive API
+4. Create OAuth 2.0 credentials (Desktop app type)
+5. Download the JSON and save it (default location: `~/.config/atheneum-mcp/gcp-oauth.keys.json`)
+
+### 2. Authenticate
+
+```bash
+npx atheneum-mcp auth
+```
+
+This opens a browser for Google sign-in and saves credentials to
+`~/.config/atheneum-mcp/tokens.json`. Custom paths can be set via YAML config (`oauthPath` and
+`credentialsPath` under `drive:`).
+
+## MCP Client Configuration
+
+### Claude Code
+
+Add to your project `.mcp.json`:
+
+```json
+{
+    "mcpServers": {
+        "atheneum": {
+            "command": "npx",
+            "args": ["atheneum-mcp", "--config", "./atheneum.yaml"]
+        }
+    }
+}
+```
+
+Or add globally via the CLI:
+
+```bash
+claude mcp add atheneum -s user -- npx atheneum-mcp --config ~/atheneum.yaml
+```
+
+### Simple Setup (env vars only, no YAML)
+
+```json
+{
+    "mcpServers": {
+        "atheneum": {
+            "command": "npx",
+            "args": ["atheneum-mcp"],
+            "env": {
+                "WIKIJS_URL": "https://wiki.example.com",
+                "WIKIJS_TOKEN": "your-api-token"
+            }
+        }
+    }
+}
+```
+
+## Configuration Reference
+
+### Config Resolution Order
+
+1. `--config <path>` CLI argument (must exist)
+2. `./atheneum.yaml` in the current working directory (if present)
+3. Environment variable fallback
+4. `.env` file (loaded automatically via dotenv)
+
+### Environment Variables (simple mode)
+
+| Variable | Description |
+|---|---|
+| `WIKIJS_URL` | Wiki.js instance URL (creates a single "default" wiki) |
+| `WIKIJS_TOKEN` | Wiki.js API token |
+| `GDRIVE_OAUTH_PATH` | Path to Google OAuth keys JSON |
+| `GDRIVE_CREDENTIALS_PATH` | Path to Google credentials JSON |
+
+### YAML: `wikis[]`
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `name` | string | **required** | Instance name (used in multi-wiki `instance` parameter) |
+| `url` | string | **required** | Wiki.js base URL |
+| `token` | string | **required** | Wiki.js API token |
+| `basePath` | string | `/` | Restrict operations to a subtree |
+| `readOnly` | boolean | `false` | Disable all write operations |
+| `strictPath` | boolean | `true` | Hard reject paths outside basePath |
+| `hidePaths` | boolean | `false` | Return "not found" instead of "access denied" for out-of-scope paths |
+
+### YAML: `drive`
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `folders` | string[] | `[]` | Folder IDs to prioritize or restrict to |
+| `recursive` | boolean | `true` | Search subfolders of listed folders |
+| `strictFolders` | boolean | `false` | Treat folders as a hard restriction (not just priority hints) |
+| `oauthPath` | string | `~/.config/atheneum-mcp/gcp-oauth.keys.json` | Path to OAuth client keys |
+| `credentialsPath` | string | `~/.config/atheneum-mcp/tokens.json` | Path to saved auth tokens |
+
+## Wiki Tools
+
+All wiki tools accept an optional `instance` parameter when multiple wikis are configured.
+
+| Tool | Description | Write |
+|---|---|---|
+| `search_wiki` | Full-text search, results filtered to basePath | No |
+| `get_wiki_page` | Get page by path (relative to basePath) | No |
+| `get_wiki_page_by_id` | Get page by numeric ID (checked against basePath) | No |
+| `list_wiki_pages` | List recent pages under basePath | No |
+| `get_wiki_tree` | Folder structure under basePath | No |
+| `list_wiki_tags` | All tags (unscoped) | No |
+| `get_pages_by_tag` | Pages with tag, filtered to basePath | No |
+| `create_wiki_page` | Create page under basePath | Yes |
+| `update_wiki_page` | Update page (must be under basePath) | Yes |
+| `delete_wiki_page` | Delete page (must be under basePath) | Yes |
+| `move_wiki_page` | Move page (source and dest must be under basePath) | Yes |
+
+## Drive Tools
+
+| Tool | Description |
+|---|---|
+| `search_gdrive` | Search files with folder prioritization/restriction |
+| `read_gdrive_file` | Read file by ID (checked against folders if strict) |
+| `list_gdrive_folder` | List folder contents (checked against allowed folders if strict) |
+
+## Development
+
+```bash
+npm install              # Install dependencies
+npm start                # Run the server
+npm run lint             # Lint code
+npm run lint:types       # Type check
+npm run release          # Version bump + changelog + tag + push
+```
+
+## License
+
+[WTFPL](http://www.wtfpl.net/)

package/eslint.config.js

@@ -0,0 +1,52 @@
+//----------------------------------------------------------------------------------------------------------------------
+// ESLint Configuration
+//----------------------------------------------------------------------------------------------------------------------
+
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import globals from 'globals';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export default tseslint.config(
+    eslint.configs.recommended,
+    ...tseslint.configs.recommended,
+    {
+        languageOptions: {
+            globals: {
+                ...globals.node
+            }
+        },
+        rules: {
+            // Enforce Allman brace style
+            'brace-style': [ 'error', 'allman', { allowSingleLine: true } ],
+
+            // 4 space indentation
+            'indent': [ 'error', 4, { SwitchCase: 1 } ],
+
+            // 120 character line limit
+            'max-len': [ 'warn', { code: 120, ignoreUrls: true, ignoreStrings: true, ignoreTemplateLiterals: true } ],
+
+            // Spacing preferences
+            'array-bracket-spacing': [ 'error', 'always' ],
+            'object-curly-spacing': [ 'error', 'always' ],
+            'computed-property-spacing': [ 'error', 'never' ],
+            'space-in-parens': [ 'error', 'never' ],
+            'template-curly-spacing': [ 'error', 'always' ],
+
+            // TypeScript specific
+            '@typescript-eslint/no-unused-vars': [ 'error', { argsIgnorePattern: '^_' } ],
+            '@typescript-eslint/explicit-function-return-type': 'off',
+            '@typescript-eslint/no-explicit-any': 'warn'
+        }
+    },
+    {
+        ignores: [
+            '**/dist/**',
+            '**/node_modules/**',
+            '**/*.d.ts'
+        ]
+    }
+);
+
+//----------------------------------------------------------------------------------------------------------------------

package/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "atheneum-mcp",
+    "version": "0.1.0",
+    "description": "MCP server for Wiki.js and Google Drive",
+    "author": "Christopher S. Case <chris.case@g33xnexus.com>",
+    "license": "WTFPL",
+    "type": "module",
+    "main": "src/cli.ts",
+    "bin": {
+        "atheneum-mcp": "src/cli.ts"
+    },
+    "engines": {
+        "node": ">=24"
+    },
+    "scripts": {
+        "start": "node src/cli.ts",
+        "lint": "eslint src/",
+        "lint:types": "tsc --noEmit",
+        "release": "bash scripts/release.sh"
+    },
+    "dependencies": {
+        "@google-cloud/local-auth": "^3.0.1",
+        "@modelcontextprotocol/sdk": "^1.0.0",
+        "dotenv": "^16.3.1",
+        "googleapis": "^166.0.0",
+        "yaml": "^2.7.0",
+        "zod": "^3.25.76"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.0.0",
+        "@types/node": "^22.0.0",
+        "eslint": "^9.0.0",
+        "globals": "^15.0.0",
+        "typescript": "^5.3.0",
+        "typescript-eslint": "^8.0.0"
+    }
+}

package/src/auth.ts

@@ -0,0 +1,60 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Atheneum MCP - Google OAuth Authentication Flow
+//----------------------------------------------------------------------------------------------------------------------
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { authenticate } from '@google-cloud/local-auth';
+
+// Config
+import type { AtheneumConfig } from './config.ts';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Constants
+//----------------------------------------------------------------------------------------------------------------------
+
+const DEFAULT_OAUTH_PATH = path.join(os.homedir(), '.config', 'atheneum-mcp', 'gcp-oauth.keys.json');
+const DEFAULT_CREDENTIALS_PATH = path.join(os.homedir(), '.config', 'atheneum-mcp', 'tokens.json');
+
+//----------------------------------------------------------------------------------------------------------------------
+// Auth Flow
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Runs the interactive Google OAuth flow, opening a browser for the user to authorize, then saves the resulting
+ * credentials to disk. Intended to be invoked via `npx atheneum-mcp auth`.
+ */
+export async function runAuthFlow(config : AtheneumConfig) : Promise<void>
+{
+    const oauthPath = config.drive?.oauthPath ?? DEFAULT_OAUTH_PATH;
+    const credentialsPath = config.drive?.credentialsPath ?? DEFAULT_CREDENTIALS_PATH;
+
+    // Bail early if the OAuth keys file is missing
+    if(!fs.existsSync(oauthPath))
+    {
+        process.stderr.write(
+            `OAuth keys not found at ${ oauthPath }. Download from Google Cloud Console.\n`
+        );
+        process.exit(1);
+    }
+
+    // Run the interactive OAuth flow (opens a browser)
+    const auth = await authenticate({
+        keyfilePath: oauthPath,
+        scopes: [
+            'https://www.googleapis.com/auth/drive',
+            'https://www.googleapis.com/auth/drive.readonly',
+        ],
+    });
+
+    // Ensure the config directory exists
+    fs.mkdirSync(path.dirname(credentialsPath), { recursive: true });
+
+    // Write credentials with restrictive permissions
+    fs.writeFileSync(credentialsPath, JSON.stringify(auth.credentials, null, 2), { mode: 0o600 });
+
+    process.stderr.write(`Authentication successful. Credentials saved to ${ credentialsPath }\n`);
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/cli.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+//----------------------------------------------------------------------------------------------------------------------
+// CLI Entry Point
+//----------------------------------------------------------------------------------------------------------------------
+
+import { loadConfig } from './config.ts';
+import { runAuthFlow } from './auth.ts';
+import { startServer } from './server.ts';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+async function main() : Promise<void>
+{
+    const args = process.argv.slice(2);
+    const config = loadConfig(args);
+
+    if(args[0] === 'auth')
+    {
+        await runAuthFlow(config);
+        return;
+    }
+
+    await startServer(config);
+}
+
+main().catch((err) =>
+{
+    console.error(err);
+    process.exit(1);
+});
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/config.ts

@@ -0,0 +1,248 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Atheneum MCP - Configuration
+//----------------------------------------------------------------------------------------------------------------------
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import dotenv from 'dotenv';
+import { parse as parseYaml } from 'yaml';
+import { z } from 'zod';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Schemas
+//----------------------------------------------------------------------------------------------------------------------
+
+const WikiConfigSchema = z.object({
+    name: z.string(),
+    url: z.string().url(),
+    token: z.string(),
+    basePath: z.string().default('/'),
+    readOnly: z.boolean().default(false),
+    strictPath: z.boolean().default(true),
+    hidePaths: z.boolean().default(false),
+});
+
+const DriveConfigSchema = z.object({
+    folders: z.array(z.string()).default([]),
+    recursive: z.boolean().default(true),
+    strictFolders: z.boolean().default(false),
+    oauthPath: z.string().optional(),
+    credentialsPath: z.string().optional(),
+});
+
+const AtheneumConfigSchema = z.object({
+    wikis: z.array(WikiConfigSchema).default([]),
+    drive: DriveConfigSchema.optional(),
+});
+
+//----------------------------------------------------------------------------------------------------------------------
+// Types
+//----------------------------------------------------------------------------------------------------------------------
+
+export type WikiConfig = z.infer<typeof WikiConfigSchema>;
+export type DriveConfig = z.infer<typeof DriveConfigSchema>;
+export type AtheneumConfig = z.infer<typeof AtheneumConfigSchema>;
+
+//----------------------------------------------------------------------------------------------------------------------
+// Env Var Interpolation
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Replaces `$VAR` and `${VAR}` patterns in a string with the corresponding environment variable value.
+ * Throws if the referenced variable is not set.
+ */
+export function interpolateEnvVars(value : string) : string
+{
+    // Match both ${VAR} and $VAR patterns. The ${VAR} form is checked first to avoid partial matches.
+    const envVarPattern = /\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+    return value.replace(envVarPattern, (
+        _match,
+        braced : string | undefined,
+        bare : string | undefined
+    ) =>
+    {
+        const varName = braced ?? bare;
+        if(!varName)
+        {
+            return _match;
+        }
+
+        const envValue = process.env[varName];
+        if(envValue === undefined)
+        {
+            throw new Error(`Environment variable '${ varName }' is not set (referenced in config)`);
+        }
+
+        return envValue;
+    });
+}
+
+/**
+ * Recursively walks all string values in an object and applies env var interpolation.
+ */
+function interpolateObject(obj : unknown) : unknown
+{
+    if(typeof obj === 'string')
+    {
+        return interpolateEnvVars(obj);
+    }
+
+    if(Array.isArray(obj))
+    {
+        return obj.map((item) => interpolateObject(item));
+    }
+
+    if(obj !== null && typeof obj === 'object')
+    {
+        const result : Record<string, unknown> = {};
+        for(const [ key, val ] of Object.entries(obj as Record<string, unknown>))
+        {
+            result[key] = interpolateObject(val);
+        }
+        return result;
+    }
+
+    // Booleans, numbers, null, etc. pass through untouched
+    return obj;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+// CLI Arg Parsing
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Extracts the `--config <path>` argument from a CLI args array. Returns undefined if not present.
+ */
+function parseConfigPath(args : string[]) : string | undefined
+{
+    const idx = args.indexOf('--config');
+    if(idx === -1)
+    {
+        return undefined;
+    }
+
+    const next = args[idx + 1];
+    if(!next || next.startsWith('--'))
+    {
+        throw new Error('--config requires a path argument');
+    }
+
+    return next;
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+// Config Loading
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Builds a fallback config from environment variables when no YAML config is available.
+ * Returns undefined if the minimum required env vars aren't set.
+ */
+function buildEnvFallbackConfig() : Record<string, unknown> | undefined
+{
+    const wikiUrl = process.env.WIKIJS_URL;
+    const wikiToken = process.env.WIKIJS_TOKEN;
+
+    const hasWiki = wikiUrl && wikiToken;
+    const oauthPath = process.env.GDRIVE_OAUTH_PATH;
+    const credentialsPath = process.env.GDRIVE_CREDENTIALS_PATH;
+    const hasDrive = oauthPath || credentialsPath;
+
+    if(!hasWiki && !hasDrive)
+    {
+        return undefined;
+    }
+
+    const config : Record<string, unknown> = {};
+
+    if(hasWiki)
+    {
+        config.wikis = [
+            {
+                name: 'default',
+                url: wikiUrl,
+                token: wikiToken,
+                basePath: '/',
+            }
+        ];
+    }
+
+    if(hasDrive)
+    {
+        const drive : Record<string, unknown> = {};
+        if(oauthPath) { drive.oauthPath = oauthPath; }
+        if(credentialsPath) { drive.credentialsPath = credentialsPath; }
+        config.drive = drive;
+    }
+
+    return config;
+}
+
+function parseAndValidate(raw : unknown) : AtheneumConfig
+{
+    const result = AtheneumConfigSchema.safeParse(raw);
+    if(!result.success)
+    {
+        const issues = result.error.issues.map(i => `  - ${ i.path.join('.') }: ${ i.message }`).join('\n');
+        throw new Error(`Invalid configuration:\n${ issues }`);
+    }
+    return result.data;
+}
+
+/**
+ * Loads and validates the Atheneum configuration.
+ *
+ * Resolution order:
+ * 1. `--config <path>` CLI argument
+ * 2. `./atheneum.yaml` in the current working directory
+ * 3. Environment variable fallback (`WIKIJS_URL` + `WIKIJS_TOKEN`, `GDRIVE_*`)
+ */
+export function loadConfig(args : string[]) : AtheneumConfig
+{
+    // Load .env file into process.env (no-ops if .env doesn't exist)
+    dotenv.config();
+
+    const configPath = parseConfigPath(args);
+    let rawConfig : unknown;
+
+    if(configPath)
+    {
+        // Explicit --config path: must exist
+        const resolved = resolve(configPath);
+        if(!existsSync(resolved))
+        {
+            throw new Error(`Config file not found: ${ resolved }`);
+        }
+
+        const content = readFileSync(resolved, 'utf-8');
+        rawConfig = parseYaml(content);
+    }
+    else
+    {
+        // Try default location
+        const defaultPath = resolve('atheneum.yaml');
+        if(existsSync(defaultPath))
+        {
+            const content = readFileSync(defaultPath, 'utf-8');
+            rawConfig = parseYaml(content);
+        }
+    }
+
+    // yaml.parse returns null for empty/whitespace-only files
+    if(rawConfig !== undefined && rawConfig !== null)
+    {
+        return parseAndValidate(interpolateObject(rawConfig));
+    }
+
+    // No YAML found -- try env var fallback
+    const fallback = buildEnvFallbackConfig();
+    if(fallback)
+    {
+        return parseAndValidate(fallback);
+    }
+
+    // Nothing configured at all -- return empty (valid) config
+    return parseAndValidate({});
+}
+
+//----------------------------------------------------------------------------------------------------------------------