@abbit/abbit-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,10 +1,14 @@
 # @abbit/abbit-mcp
 
-Preview CLI that connects an MCP client to Abbit's remote MCP over local stdio. It manages browser login, private local credentials, and serialized token refresh. Requires Node.js `>=24.15.0 <25` and an Abbit account with access to a workspace.
+Preview CLI that connects an MCP client to Abbit's remote MCP over local stdio. It supports browser or personal-key login, private local credentials, and serialized OAuth token refresh. Requires Node.js `>=24.15.0 <25` and an Abbit account with access to a workspace.
+
+## Supported platforms
+
+The current preview is supported and tested only on macOS. Linux and Windows support is planned; neither platform is currently supported or tested.
 
 ## Install and log in
 
-After the first npm publication:
+Install the current preview release:
 
 ```sh
 npm install --global @abbit/abbit-mcp@preview
@@ -12,7 +16,31 @@ abbit-mcp login
 abbit-mcp status
 ```
 
-Login opens or prints a browser authorization URL. Select your workspace and approve access. The browser must reach the same machine's loopback callback; SSH/headless login is not supported.
+Login opens or prints a browser authorization URL. Select your workspace and approve access. Browser login requires reaching the same machine's loopback callback. Use an existing personal key for SSH/headless login.
+
+Login requests Tracker access and Wiki listing, creation, reading, search rebuilding, and editing. IAM grants only your approved, permitted scope. Existing sessions keep their original permissions during refresh. After updating from a version without Wiki listing or creation scopes, run `abbit-mcp login` again and approve the needed Wiki access.
+
+## Personal-key login
+
+Use an existing Abbit personal API key with the permissions needed by your tools:
+
+```sh
+abbit-mcp login --key
+```
+
+Paste the key into the hidden prompt and press Enter. For headless use, redirect a protected file or pipe a secret manager's output into the same command:
+
+```sh
+abbit-mcp login --key < /secure/path/personal-key
+```
+
+Never put the key in command arguments, shell history, environment variables, or MCP client configuration. Login validates the key with Abbit MCP before replacing your local login. Service keys are not accepted. Key issuance and permission management remain in IAM.
+
+`serve` uses the saved key directly. IAM checks its current permissions, expiry and revocation on every request. Keys do not refresh; replace a rejected key by running `login --key` again. Failed authentication never falls back to another login. `status` reports the locally saved key's namespace without displaying the key; it does not check current server validity.
+
+A successful login selects its authentication method: key login disables previous browser sessions locally and attempts to revoke them; browser login removes the local key. Failed OAuth revocation stays pending for a later `logout` retry. `logout` removes the saved key **only from this machine**; revoke it separately in IAM to invalidate other copies.
+
+Both methods use the locked, atomic `~/.abbit/credentials.json` store (directory mode 0700, file mode 0600). Key login adds an optional `personalKey` field to the version-1 document. Existing OAuth documents remain readable. Older clients reject a key-bearing document safely; use this version to log out or return to browser login before downgrading.
 
 ## MCP client configuration
 

package/dist/auth.js

@@ -2,7 +2,8 @@ import { spawn } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import { createServer } from 'node:http';
 import { authorizationTimeoutMs, iamOrigin, isMcpClientId, isMcpScopeSet, mcpAudience, mcpScope, parseMcpScope, refreshHardLifetimeMs, refreshIdleLifetimeMs, } from './constants.js';
-import { createAccessTokenEntry } from './model.js';
+import { createAccessTokenEntry, personalKeyNamespace } from './model.js';
+import { validatePersonalKey } from './personal-key.js';
 const matchesMcpIdentity = (record) => record.origin === iamOrigin && isMcpClientId(record.clientId) && record.audience === mcpAudience;
 const matchesMcp = (record) => matchesMcpIdentity(record) && isMcpScopeSet(record.approvedScopes);
 const matchesLegacyMcp = (record) => matchesMcpIdentity(record) && record.approvedScopes.length === 1 && record.approvedScopes[0] === 'mcp:access';
@@ -213,6 +214,7 @@ export class McpAuthService {
                 lastUsedAt: persistedAt.toISOString(),
             };
             const predecessors = await this.store.withLock(async (document) => {
+                delete document.personalKey;
                 const pending = [];
                 for (const previous of Object.values(document.credentials)) {
                     if (!matchesAnyMcp(previous) || previous.credentialId === record.credentialId)
@@ -243,8 +245,31 @@ export class McpAuthService {
             await callback.close();
         }
     }
+    async loginWithKey(key, fetchImpl = fetch) {
+        const namespaceId = personalKeyNamespace(key);
+        if (namespaceId === undefined)
+            throw new Error('Enter a valid Abbit personal API key.');
+        await validatePersonalKey(key, fetchImpl);
+        const pending = await this.store.withLock(async (document) => {
+            for (const record of Object.values(document.credentials).filter(matchesAnyMcp)) {
+                record.state = 'pendingRevocation';
+                record.accessTokens = [];
+            }
+            document.personalKey = key;
+            return {
+                result: Object.values(document.credentials)
+                    .filter(matchesAnyMcp)
+                    .map(({ credentialId, refreshToken, clientId }) => ({ credentialId, refreshToken, clientId })),
+                document,
+            };
+        });
+        await this.revokePending(pending);
+        return { namespaceId };
+    }
     async status(currentTime = new Date()) {
-        const records = Object.values((await this.store.read()).credentials).filter(matchesAnyMcp);
+        const document = await this.store.read();
+        const keyNamespace = personalKeyNamespace(document.personalKey);
+        const records = Object.values(document.credentials).filter(matchesAnyMcp);
         const stateFor = (record) => {
             if (record.state === 'pendingRevocation')
                 return 'pendingRevocation';
@@ -256,7 +281,10 @@ export class McpAuthService {
                 : 'active';
         };
         const namespaces = records.map((record) => ({ namespaceId: record.namespaceId, state: stateFor(record) }));
+        if (keyNamespace !== undefined)
+            namespaces.unshift({ namespaceId: keyNamespace, state: 'active' });
         return {
+            ...(keyNamespace === undefined ? {} : { personalKeyNamespace: keyNamespace }),
             authenticated: namespaces.some(({ state }) => state === 'active'),
             pendingRevocation: namespaces.some(({ state }) => state === 'pendingRevocation'),
             reauthenticationRequired: namespaces.some(({ state }) => state === 'reauthenticationRequired'),
@@ -264,7 +292,10 @@ export class McpAuthService {
         };
     }
     async logout() {
+        let forgotten = 0;
         const pending = await this.store.withLock(async (document) => {
+            forgotten = document.personalKey === undefined ? 0 : 1;
+            delete document.personalKey;
             const selected = Object.values(document.credentials).filter(matchesAnyMcp);
             for (const record of selected) {
                 record.state = 'pendingRevocation';
@@ -275,6 +306,9 @@ export class McpAuthService {
                 document,
             };
         });
+        return { ...(await this.revokePending(pending)), forgotten };
+    }
+    async revokePending(pending) {
         let revoked = 0;
         for (const candidate of pending) {
             if (!(await this.iam.revoke(candidate.refreshToken, candidate.clientId)))

package/dist/cli.js

@@ -3,16 +3,27 @@ import { Command } from 'commander';
 import { McpAuthService } from './auth.js';
 import { CredentialStore } from './credentials.js';
 import { createMcpIamClient, refreshMcpToken } from './iam-client.js';
+import { readPersonalKey } from './personal-key.js';
 import { serveLocalMcp } from './proxy.js';
 import { McpTokenManager } from './token-manager.js';
 const store = new CredentialStore();
 const iam = createMcpIamClient();
 const auth = new McpAuthService(store, iam);
-const program = new Command().name('abbit-mcp').description('Abbit local stdio MCP adapter').version('0.1.0').showHelpAfterError();
+const program = new Command().name('abbit-mcp').description('Abbit local stdio MCP adapter').version('0.2.0').showHelpAfterError();
+program.configureOutput({
+    outputError: (_message, write) => write('Invalid command. Use --help. Supply personal keys through hidden input or stdin, never arguments.\n'),
+});
 program
     .command('login')
-    .description('Authorize Abbit MCP in your browser')
-    .action(async () => {
+    .description('Authorize Abbit MCP in your browser or with a personal key')
+    .option('--key', 'Read an existing personal API key from hidden input or stdin')
+    .allowExcessArguments(false)
+    .action(async (options) => {
+    if (options.key) {
+        const record = await auth.loginWithKey(await readPersonalKey());
+        process.stdout.write(`Authenticated Abbit MCP with a personal key for namespace ${JSON.stringify(record.namespaceId)}.\n`);
+        return;
+    }
     const record = await auth.login({ output: (line) => process.stdout.write(`${line}\n`) });
     process.stdout.write(`Authenticated Abbit MCP for namespace ${record.namespaceId}.\n`);
 });
@@ -21,7 +32,10 @@ program
     .description('Show local Abbit MCP authentication status')
     .action(async () => {
     const status = await auth.status();
-    if (status.authenticated) {
+    if (status.personalKeyNamespace !== undefined) {
+        process.stdout.write(`Personal key saved for namespace ${JSON.stringify(status.personalKeyNamespace)} (server checks validity on use).\n`);
+    }
+    else if (status.authenticated) {
         for (const record of status.namespaces.filter(({ state }) => state === 'active')) {
             process.stdout.write(`Authenticated: ${record.namespaceId}\n`);
         }
@@ -36,15 +50,20 @@ program
 });
 program
     .command('logout')
-    .description('Disable local access and revoke Abbit MCP credentials')
+    .description('Forget a personal key locally and revoke browser OAuth credentials')
     .action(async () => {
     const result = await auth.logout();
+    if (result.forgotten > 0)
+        process.stdout.write('Personal key removed locally. The key remains valid until revoked in IAM.\n');
     if (result.pending > 0) {
         process.stdout.write('Local access disabled; remote revocation is pending.\n');
         process.exitCode = 1;
         return;
     }
-    process.stdout.write(result.revoked > 0 ? 'Abbit MCP credentials revoked.\n' : 'No Abbit MCP credentials were configured.\n');
+    if (result.revoked > 0)
+        process.stdout.write('Abbit MCP credentials revoked.\n');
+    else if (result.forgotten === 0)
+        process.stdout.write('No Abbit MCP credentials were configured.\n');
 });
 program
     .command('serve')

package/dist/constants.js

@@ -1,7 +1,16 @@
 export const iamOrigin = 'https://auth.abusybit.com';
 export const mcpAudience = 'https://api.abusybit.com/v1/mcp';
-export const mcpScopes = ['tracker:claim', 'tracker:read', 'tracker:write', 'wiki:read', 'wiki:write'];
-export const mcpScope = 'tracker:claim tracker:read tracker:write wiki:read wiki:write';
+export const mcpScopes = [
+    'tracker:claim',
+    'tracker:read',
+    'tracker:write',
+    'wiki:list',
+    'wiki:provision',
+    'wiki:read',
+    'wiki:rebuild',
+    'wiki:write',
+];
+export const mcpScope = 'tracker:claim tracker:read tracker:write wiki:list wiki:provision wiki:read wiki:rebuild wiki:write';
 export const parseMcpScope = (value) => {
     if (typeof value !== 'string')
         return undefined;

package/dist/model.js

@@ -56,6 +56,20 @@ export const isMcpRefreshToken = (value, expectedNamespaceId) => {
     const namespaceId = decodeNamespaceLocator(locator);
     return namespaceId !== undefined && (expectedNamespaceId === undefined || namespaceId === expectedNamespaceId);
 };
+export const personalKeyNamespace = (value) => {
+    if (typeof value !== 'string' || value.length > 2_048)
+        return undefined;
+    const [prefix, locator, lookup, secret, extra] = value.split('.');
+    if (prefix !== 'abbit_pk_v1' ||
+        locator === undefined ||
+        lookup === undefined ||
+        secret === undefined ||
+        extra !== undefined ||
+        !/^[A-Za-z0-9_-]{21}[AQgw]$/u.test(lookup) ||
+        !/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/u.test(secret))
+        return undefined;
+    return decodeNamespaceLocator(locator);
+};
 const isAccessToken = (value) => isRecord(value) &&
     hasExactKeys(value, ['accessToken', 'audience', 'scopes', 'issuedAt', 'expiresAt']) &&
     boundedString(value.accessToken, 1, 32_768) &&
@@ -113,7 +127,11 @@ const isCredential = (value) => {
 };
 export const emptyCredentialDocument = () => ({ version: 1, credentials: {} });
 export const parseCredentialDocument = (value) => {
-    if (!isRecord(value) || !hasExactKeys(value, ['version', 'credentials']) || value.version !== 1 || !isRecord(value.credentials)) {
+    if (!isRecord(value) ||
+        !hasExactKeys(value, 'personalKey' in value ? ['version', 'credentials', 'personalKey'] : ['version', 'credentials']) ||
+        value.version !== 1 ||
+        !isRecord(value.credentials) ||
+        ('personalKey' in value && personalKeyNamespace(value.personalKey) === undefined)) {
         throw new TypeError('credential document validation failed');
     }
     for (const [key, credential] of Object.entries(value.credentials)) {

package/dist/personal-key.js

@@ -0,0 +1,103 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { iamRequestTimeoutMs, mcpAudience } from './constants.js';
+import { personalKeyNamespace } from './model.js';
+export const readPersonalKey = (input = process.stdin, output = process.stderr) => new Promise((resolve, reject) => {
+    const interactive = input.isTTY === true;
+    const wasRaw = input.isRaw === true;
+    let value = '';
+    let finished = false;
+    const finish = (error) => {
+        if (finished)
+            return;
+        finished = true;
+        input.removeListener('data', onData);
+        input.removeListener('end', onEnd);
+        input.removeListener('error', onError);
+        input.removeListener('close', onClose);
+        process.removeListener('SIGTERM', onTerminate);
+        process.removeListener('SIGINT', onTerminate);
+        input.pause();
+        if (interactive) {
+            input.setRawMode?.(wasRaw);
+            output.write('\n');
+        }
+        const key = value.replace(/\r?\n$/u, '');
+        value = '';
+        if (error !== undefined)
+            reject(error);
+        else if (personalKeyNamespace(key) === undefined)
+            reject(new Error('Enter a valid Abbit personal API key.'));
+        else
+            resolve(key);
+    };
+    const onError = () => finish(new Error('Could not read the personal API key.'));
+    const onEnd = () => finish();
+    const onClose = () => finish(new Error('Personal-key input closed.'));
+    const onTerminate = () => finish(new Error('Personal-key login canceled.'));
+    const onData = (chunk) => {
+        for (const char of chunk.toString()) {
+            if (interactive && (char === '\u0003' || char === '\u0004'))
+                return onTerminate();
+            if (interactive && (char === '\r' || char === '\n'))
+                return finish();
+            if (interactive && (char === '\u007f' || char === '\b'))
+                value = value.slice(0, -1);
+            else
+                value += char;
+            if (value.length > 2_048)
+                return finish(new Error('Personal-key input is too long.'));
+        }
+    };
+    if (interactive) {
+        if (input.setRawMode === undefined)
+            return reject(new Error('Hidden input is unavailable. Redirect the key through stdin.'));
+        input.setRawMode(true);
+        output.write('Personal API key (hidden): ');
+    }
+    input.on('data', onData).once('end', onEnd).once('error', onError).once('close', onClose);
+    process.once('SIGTERM', onTerminate);
+    process.once('SIGINT', onTerminate);
+    input.resume();
+});
+export const fetchWithPersonalKey = async (key, input, init = {}, fetchImpl = fetch) => {
+    const url = input instanceof Request ? input.url : String(input);
+    if (url !== mcpAudience)
+        throw new Error('Personal keys may only be sent to the Abbit MCP endpoint.');
+    const headers = new Headers(init.headers);
+    headers.set('authorization', `Bearer ${key}`);
+    try {
+        const response = await fetchImpl(input, { ...init, headers, redirect: 'error' });
+        if (response.ok)
+            return response;
+        await response.body?.cancel();
+        return new Response('Abbit MCP request rejected.', { status: response.status });
+    }
+    catch {
+        throw new Error('Abbit MCP request failed.');
+    }
+};
+export const validatePersonalKey = async (key, fetchImpl = fetch) => {
+    if (personalKeyNamespace(key) === undefined)
+        throw new Error('Enter a valid Abbit personal API key.');
+    const client = new Client({ name: 'abbit-mcp-r0', version: '0.2.0' }, { capabilities: {} });
+    const transport = new StreamableHTTPClientTransport(new URL(mcpAudience), {
+        fetch: async (input, init) => {
+            const response = await fetchWithPersonalKey(key, input, { ...init, signal: AbortSignal.timeout(iamRequestTimeoutMs) }, fetchImpl);
+            if (!response.ok && response.status !== 405) {
+                await response.body?.cancel();
+                throw new Error('Personal-key authentication failed.');
+            }
+            return response;
+        },
+    });
+    try {
+        await client.connect(transport, { timeout: iamRequestTimeoutMs });
+    }
+    catch {
+        throw new Error('Could not authenticate the personal key with Abbit MCP. Check the key and connection.');
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+};

package/dist/proxy.js

@@ -5,13 +5,13 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { mcpAudience } from './constants.js';
 export const createLocalMcpProxyServer = (upstream) => {
-    const server = new Server({ name: 'abbit-mcp-r0', version: '0.1.0' }, { capabilities: { tools: {} } });
+    const server = new Server({ name: 'abbit-mcp-r0', version: '0.2.0' }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, (request) => upstream.listTools(request.params));
     server.setRequestHandler(CallToolRequestSchema, (request) => upstream.callTool(request.params));
     return server;
 };
 export const serveLocalMcp = async (options) => {
-    const upstream = new Client({ name: 'abbit-mcp-r0', version: '0.1.0' }, { capabilities: {} });
+    const upstream = new Client({ name: 'abbit-mcp-r0', version: '0.2.0' }, { capabilities: {} });
     const fetchImpl = options.fetch ?? fetch;
     const upstreamTransport = new StreamableHTTPClientTransport(new URL(mcpAudience), {
         fetch: (input, init) => options.tokenManager.authenticatedFetch(input, init, fetchImpl),

package/dist/token-manager.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { accessTokenSafetyWindowMs, iamOrigin, isMcpClientId, isMcpScopeSet, mcpAudience, parseMcpScope, refreshIdleLifetimeMs, } from './constants.js';
 import { createAccessTokenEntry } from './model.js';
+import { fetchWithPersonalKey } from './personal-key.js';
 export class McpReauthenticationRequiredError extends Error {
     constructor() {
         super('Abbit MCP authentication is required. Run `abbit-mcp login`.');
@@ -35,6 +36,11 @@ export class McpTokenManager {
     async getAccessContext(options = {}) {
         const initialNow = this.now();
         const initialDocument = await this.store.read();
+        if (initialDocument.personalKey !== undefined) {
+            if (options.credentialId !== undefined || options.rejectedToken !== undefined)
+                throw new McpReauthenticationRequiredError();
+            return { accessToken: initialDocument.personalKey, credentialId: 'personal-key', personalKey: true };
+        }
         const initial = options.credentialId === undefined
             ? selectCredential(Object.values(initialDocument.credentials))
             : initialDocument.credentials[options.credentialId];
@@ -50,6 +56,8 @@ export class McpTokenManager {
             return { accessToken: cached.accessToken, credentialId };
         return this.store.withLock(async (document, commit) => {
             const completedAt = this.now();
+            if (document.personalKey !== undefined)
+                throw new McpReauthenticationRequiredError();
             const credential = document.credentials[credentialId];
             if (credential === undefined || credential.state !== 'active' || !matchesMcpProfile(credential)) {
                 throw new McpReauthenticationRequiredError();
@@ -88,6 +96,8 @@ export class McpTokenManager {
     }
     async authenticatedFetch(input, init = {}, fetchImpl = fetch) {
         const initial = await this.getAccessContext();
+        if (initial.personalKey)
+            return fetchWithPersonalKey(initial.accessToken, input, init, fetchImpl);
         const first = await fetchImpl(input, this.withBearer(init, initial.accessToken));
         if (first.status !== 401)
             return first;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@abbit/abbit-mcp",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Abbit-owned local stdio MCP adapter.",
 	"license": "UNLICENSED",
 	"repository": {