@abbit/abbit-mcp 0.1.0 → 0.3.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, personal-key or service-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,43 @@ 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 or service 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.
+
+## API-key login
+
+Use an existing Abbit personal (`abbit_pk_v1`) or service (`abbit_sk_v1`) 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/api-key
+```
+
+For the local adapter, supply the key only through hidden input or stdin; never as a command argument. Login validates the key with Abbit MCP before replacing your local login. Key issuance and permission management remain in IAM.
+
+`serve` sends the saved key as `Authorization: Bearer <key>`. 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 class and 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 stores exactly one optional `personalKey` or `serviceKey` field in the version-1 document. Existing OAuth and personal-key documents remain readable. Clients before 0.3.0 reject service-key documents safely; use this version to log out or return to browser login before downgrading.
+
+## Direct HTTP MCP in Codex
+
+Both key classes can also authenticate directly to the remote MCP endpoint. Codex supports an environment-sourced bearer in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.abbit]
+url = "https://api.abusybit.com/v1/mcp"
+bearer_token_env_var = "ABBIT_API_KEY"
+```
+
+Set `ABBIT_API_KEY` in the environment of the Codex process. Its value is the complete key without the `Bearer ` prefix. This connection does not use the local adapter or its credential store. Codex also accepts a literal header via `http_headers = { Authorization = "Bearer <key>" }`; that stores the secret in the configuration file. Use only one credential source. See the [official Codex configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference#configtoml).
 
 ## MCP client configuration
 
@@ -136,3 +176,21 @@ abbit-mcp logout
 This package provides the `abbit-mcp` command, not an importable JavaScript library. It contains compiled runtime modules and this README; npm installs its declared runtime dependencies. The preview channel starts at `0.1.0` and carries no stable API guarantee. Abbit code remains `UNLICENSED`; public registry access does not grant an open-source license. Dependencies retain their respective licenses.
 
 Maintainers: see the [publication policy](https://github.com/abbitco/abbit-platfrom/blob/main/wiki/mcp/npm-publication.md) and [runtime contract](https://github.com/abbitco/abbit-platfrom/blob/main/wiki/mcp/local-stdio-adapter.md).
+
+## Tracker attachment bytes
+
+Initiate an upload using `tracker_initiate_attachment_upload`, then stream its exact file locally:
+
+```sh
+abbit-mcp attachment-upload TRACKER_ID ITEM_ID UPLOAD_ID ./proof.png
+```
+
+Complete it with `tracker_complete_attachment_upload`, then call `tracker_add_comment_with_attachments` (optional caption) or `tracker_publish_attachments`. Reuse each metadata command's idempotency key after an uncertain response. A transfer failure should be followed by upload inspection before retrying. Files are capped at 25 MiB; tool arguments never contain bytes/base64, URLs, or server-side local paths.
+
+List associations with `tracker_list_attachments`, then retrieve an original to a new destination:
+
+```sh
+abbit-mcp attachment-download TRACKER_ID ITEM_ID ATTACHMENT_ID ./downloaded-proof.png
+```
+
+The helper verifies size/SHA-256 before publishing the local file and never overwrites an existing destination. Both byte helpers use the selected local credential, fixed gateway origin and exact Tracker routes. Credentials are absent from arguments, output and filenames. These commands require the attachment-capable gateway deployment.

package/dist/api-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 { parseApiKey } from './model.js';
+export const readApiKey = (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 (parseApiKey(key) === undefined)
+            reject(new Error('Enter a valid Abbit API key.'));
+        else
+            resolve(key);
+    };
+    const onError = () => finish(new Error('Could not read the API key.'));
+    const onEnd = () => finish();
+    const onClose = () => finish(new Error('API-key input closed.'));
+    const onTerminate = () => finish(new Error('API-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('API-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('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 fetchWithApiKey = async (key, input, init = {}, fetchImpl = fetch) => {
+    const url = input instanceof Request ? input.url : String(input);
+    if (url !== mcpAudience)
+        throw new Error('API 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 validateApiKey = async (key, fetchImpl = fetch) => {
+    if (parseApiKey(key) === undefined)
+        throw new Error('Enter a valid Abbit API key.');
+    const client = new Client({ name: 'abbit-mcp-r0', version: '0.3.0' }, { capabilities: {} });
+    const transport = new StreamableHTTPClientTransport(new URL(mcpAudience), {
+        fetch: async (input, init) => {
+            const response = await fetchWithApiKey(key, input, { ...init, signal: AbortSignal.timeout(iamRequestTimeoutMs) }, fetchImpl);
+            if (!response.ok && response.status !== 405) {
+                await response.body?.cancel();
+                throw new Error('API-key authentication failed.');
+            }
+            return response;
+        },
+    });
+    try {
+        await client.connect(transport, { timeout: iamRequestTimeoutMs });
+    }
+    catch {
+        throw new Error('Could not authenticate the API key with Abbit MCP. Check the key and connection.');
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+};

package/dist/attachment-transfer.js

@@ -0,0 +1,104 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { link, open, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { Readable } from 'node:stream';
+const encode = (value) => {
+    if (!value || [...value].length > 128 || value === '.' || value === '..' || value.includes('\0') || /[\uD800-\uDFFF]/u.test(value))
+        throw new Error('Invalid attachment identifier.');
+    return encodeURIComponent(value);
+};
+const target = (trackerId, itemId, suffix) => new URL(`https://api.abusybit.com/v2/trackers/${encode(trackerId)}/items/${encode(itemId)}/attachments/${suffix}`);
+export async function uploadAttachment(manager, trackerId, itemId, uploadId, path) {
+    const file = await open(path, 'r');
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > 26214400)
+            throw new Error('Choose a regular file no larger than 25 MiB.');
+        const key = `stream-${randomUUID()}`;
+        const response = await manager.attachmentFetch(target(trackerId, itemId, `uploads/${encode(uploadId)}/content`), () => ({
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/octet-stream', 'Idempotency-Key': key },
+            body: Readable.toWeb(file.createReadStream({ autoClose: false, start: 0 })),
+            duplex: 'half',
+            signal: AbortSignal.timeout(125000),
+        }));
+        if (response.status !== 200) {
+            await response.body?.cancel();
+            throw new Error(`Attachment upload was not confirmed (HTTP ${response.status}). Inspect the upload before retrying.`);
+        }
+        await response.body?.cancel();
+    }
+    catch (error) {
+        if (error instanceof Error && /^(Choose|Attachment upload was not confirmed)/.test(error.message))
+            throw error;
+        throw new Error('Attachment upload could not be confirmed. Inspect the upload before retrying.');
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function downloadAttachment(manager, trackerId, itemId, attachmentId, path) {
+    const temporary = join(dirname(path), `.abbit-attachment-${randomUUID()}`);
+    let created = false;
+    try {
+        const response = await manager.attachmentFetch(target(trackerId, itemId, `${encode(attachmentId)}/content`), () => ({
+            method: 'GET',
+            signal: AbortSignal.timeout(125000),
+        }));
+        if (response.status !== 200) {
+            await response.body?.cancel();
+            throw new Error(`Attachment download failed (HTTP ${response.status}).`);
+        }
+        const raw = response.headers.get('content-length'), sha = response.headers.get('x-attachment-sha256');
+        if (!raw ||
+            !/^\d{1,8}$/.test(raw) ||
+            Number(raw) > 26214400 ||
+            !sha ||
+            !/^[a-f0-9]{64}$/.test(sha) ||
+            response.headers.get('content-type') !== 'application/octet-stream') {
+            await response.body?.cancel();
+            throw new Error('Attachment response could not be verified.');
+        }
+        const file = await open(temporary, 'wx', 0o600);
+        created = true;
+        const hash = createHash('sha256');
+        let count = 0;
+        const reader = response.body?.getReader();
+        try {
+            if (reader)
+                while (true) {
+                    const part = await reader.read();
+                    if (part.done)
+                        break;
+                    count += part.value.length;
+                    if (count > Number(raw))
+                        throw new Error('Attachment response could not be verified.');
+                    hash.update(part.value);
+                    let offset = 0;
+                    while (offset < part.value.length) {
+                        const written = await file.write(part.value.subarray(offset));
+                        offset += written.bytesWritten;
+                    }
+                }
+            if (count !== Number(raw) || hash.digest('hex') !== sha)
+                throw new Error('Attachment response could not be verified.');
+            await file.sync();
+        }
+        finally {
+            await reader?.cancel().catch(() => undefined);
+            reader?.releaseLock();
+            await file.close();
+        }
+        // Atomic no-overwrite publication: an existing destination is never replaced.
+        await link(temporary, path);
+    }
+    catch (error) {
+        if (error instanceof Error && /^Attachment (download failed|response could not)/.test(error.message))
+            throw error;
+        throw new Error('Attachment download failed. Choose a new writable destination; existing files are never replaced.');
+    }
+    finally {
+        if (created)
+            await unlink(temporary).catch(() => undefined);
+    }
+}

package/dist/auth.js

@@ -1,8 +1,9 @@
 import { spawn } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import { createServer } from 'node:http';
+import { validateApiKey } from './api-key.js';
 import { authorizationTimeoutMs, iamOrigin, isMcpClientId, isMcpScopeSet, mcpAudience, mcpScope, parseMcpScope, refreshHardLifetimeMs, refreshIdleLifetimeMs, } from './constants.js';
-import { createAccessTokenEntry } from './model.js';
+import { createAccessTokenEntry, parseApiKey } from './model.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,8 @@ export class McpAuthService {
                 lastUsedAt: persistedAt.toISOString(),
             };
             const predecessors = await this.store.withLock(async (document) => {
+                delete document.personalKey;
+                delete document.serviceKey;
                 const pending = [];
                 for (const previous of Object.values(document.credentials)) {
                     if (!matchesAnyMcp(previous) || previous.credentialId === record.credentialId)
@@ -243,8 +246,36 @@ export class McpAuthService {
             await callback.close();
         }
     }
+    async loginWithKey(key, fetchImpl = fetch) {
+        const parsed = parseApiKey(key);
+        if (parsed === undefined)
+            throw new Error('Enter a valid Abbit API key.');
+        await validateApiKey(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 = [];
+            }
+            delete document.personalKey;
+            delete document.serviceKey;
+            if (parsed.kind === 'personal')
+                document.personalKey = key;
+            else
+                document.serviceKey = key;
+            return {
+                result: Object.values(document.credentials)
+                    .filter(matchesAnyMcp)
+                    .map(({ credentialId, refreshToken, clientId }) => ({ credentialId, refreshToken, clientId })),
+                document,
+            };
+        });
+        await this.revokePending(pending);
+        return parsed;
+    }
     async status(currentTime = new Date()) {
-        const records = Object.values((await this.store.read()).credentials).filter(matchesAnyMcp);
+        const document = await this.store.read();
+        const key = parseApiKey(document.personalKey ?? document.serviceKey);
+        const records = Object.values(document.credentials).filter(matchesAnyMcp);
         const stateFor = (record) => {
             if (record.state === 'pendingRevocation')
                 return 'pendingRevocation';
@@ -256,7 +287,10 @@ export class McpAuthService {
                 : 'active';
         };
         const namespaces = records.map((record) => ({ namespaceId: record.namespaceId, state: stateFor(record) }));
+        if (key !== undefined)
+            namespaces.unshift({ namespaceId: key.namespaceId, state: 'active' });
         return {
+            ...(key === undefined ? {} : { apiKey: key }),
             authenticated: namespaces.some(({ state }) => state === 'active'),
             pendingRevocation: namespaces.some(({ state }) => state === 'pendingRevocation'),
             reauthenticationRequired: namespaces.some(({ state }) => state === 'reauthenticationRequired'),
@@ -264,7 +298,11 @@ export class McpAuthService {
         };
     }
     async logout() {
+        let forgotten = 0;
         const pending = await this.store.withLock(async (document) => {
+            forgotten = document.personalKey === undefined && document.serviceKey === undefined ? 0 : 1;
+            delete document.personalKey;
+            delete document.serviceKey;
             const selected = Object.values(document.credentials).filter(matchesAnyMcp);
             for (const record of selected) {
                 record.state = 'pendingRevocation';
@@ -275,6 +313,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

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { readApiKey } from './api-key.js';
+import { downloadAttachment, uploadAttachment } from './attachment-transfer.js';
 import { McpAuthService } from './auth.js';
 import { CredentialStore } from './credentials.js';
 import { createMcpIamClient, refreshMcpToken } from './iam-client.js';
@@ -8,11 +10,21 @@ 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.3.0').showHelpAfterError();
+program.configureOutput({
+    outputError: (_message, write) => write('Invalid command. Use --help. Supply API 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 or service key')
+    .option('--key', 'Read an existing personal or service API key from hidden input or stdin')
+    .allowExcessArguments(false)
+    .action(async (options) => {
+    if (options.key) {
+        const record = await auth.loginWithKey(await readApiKey());
+        process.stdout.write(`Authenticated Abbit MCP with a ${record.kind} 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 +33,10 @@ program
     .description('Show local Abbit MCP authentication status')
     .action(async () => {
     const status = await auth.status();
-    if (status.authenticated) {
+    if (status.apiKey !== undefined) {
+        process.stdout.write(`${status.apiKey.kind === 'personal' ? 'Personal' : 'Service'} key saved for namespace ${JSON.stringify(status.apiKey.namespaceId)} (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 +51,20 @@ program
 });
 program
     .command('logout')
-    .description('Disable local access and revoke Abbit MCP credentials')
+    .description('Forget an API key locally and revoke browser OAuth credentials')
     .action(async () => {
     const result = await auth.logout();
+    if (result.forgotten > 0)
+        process.stdout.write('API 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')
@@ -58,6 +78,22 @@ program
         });
     }
 });
+program
+    .command('attachment-upload <trackerId> <itemId> <uploadId> <file>')
+    .description('Stream a local file to an initiated Tracker upload; complete and publish through MCP')
+    .allowExcessArguments(false)
+    .action(async (trackerId, itemId, uploadId, file) => {
+    await uploadAttachment(new McpTokenManager(store, refreshMcpToken()), trackerId, itemId, uploadId, file);
+    process.stdout.write('Bytes staged. Complete the upload and publish its attachment through MCP.\n');
+});
+program
+    .command('attachment-download <trackerId> <itemId> <attachmentId> <destination>')
+    .description('Download an original Tracker attachment to a new local file, verifying its SHA-256')
+    .allowExcessArguments(false)
+    .action(async (trackerId, itemId, attachmentId, destination) => {
+    await downloadAttachment(new McpTokenManager(store, refreshMcpToken()), trackerId, itemId, attachmentId, destination);
+    process.stdout.write('Original attachment downloaded and verified.\n');
+});
 program.parseAsync().catch((error) => {
     const message = error instanceof Error ? error.message : 'Abbit MCP failed.';
     process.stderr.write(`${message}\n`);

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,21 @@ export const isMcpRefreshToken = (value, expectedNamespaceId) => {
     const namespaceId = decodeNamespaceLocator(locator);
     return namespaceId !== undefined && (expectedNamespaceId === undefined || namespaceId === expectedNamespaceId);
 };
+export const parseApiKey = (value) => {
+    if (typeof value !== 'string' || value.length > 2_048)
+        return undefined;
+    const [prefix, locator, lookup, secret, extra] = value.split('.');
+    if ((prefix !== 'abbit_pk_v1' && prefix !== 'abbit_sk_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;
+    const namespaceId = decodeNamespaceLocator(locator);
+    return namespaceId === undefined ? undefined : { kind: prefix === 'abbit_pk_v1' ? 'personal' : 'service', namespaceId };
+};
 const isAccessToken = (value) => isRecord(value) &&
     hasExactKeys(value, ['accessToken', 'audience', 'scopes', 'issuedAt', 'expiresAt']) &&
     boundedString(value.accessToken, 1, 32_768) &&
@@ -113,7 +128,18 @@ 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, [
+            'version',
+            'credentials',
+            ...('personalKey' in value ? ['personalKey'] : []),
+            ...('serviceKey' in value ? ['serviceKey'] : []),
+        ]) ||
+        value.version !== 1 ||
+        !isRecord(value.credentials) ||
+        ('personalKey' in value && parseApiKey(value.personalKey)?.kind !== 'personal') ||
+        ('serviceKey' in value && parseApiKey(value.serviceKey)?.kind !== 'service') ||
+        ('personalKey' in value && 'serviceKey' in value)) {
         throw new TypeError('credential document validation failed');
     }
     for (const [key, credential] of Object.entries(value.credentials)) {

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.3.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.3.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,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { fetchWithApiKey } from './api-key.js';
 import { accessTokenSafetyWindowMs, iamOrigin, isMcpClientId, isMcpScopeSet, mcpAudience, parseMcpScope, refreshIdleLifetimeMs, } from './constants.js';
 import { createAccessTokenEntry } from './model.js';
 export class McpReauthenticationRequiredError extends Error {
@@ -35,6 +36,12 @@ export class McpTokenManager {
     async getAccessContext(options = {}) {
         const initialNow = this.now();
         const initialDocument = await this.store.read();
+        const key = initialDocument.personalKey ?? initialDocument.serviceKey;
+        if (key !== undefined) {
+            if (options.credentialId !== undefined || options.rejectedToken !== undefined)
+                throw new McpReauthenticationRequiredError();
+            return { accessToken: key, credentialId: 'api-key', apiKey: true };
+        }
         const initial = options.credentialId === undefined
             ? selectCredential(Object.values(initialDocument.credentials))
             : initialDocument.credentials[options.credentialId];
@@ -50,6 +57,8 @@ export class McpTokenManager {
             return { accessToken: cached.accessToken, credentialId };
         return this.store.withLock(async (document, commit) => {
             const completedAt = this.now();
+            if (document.personalKey !== undefined || document.serviceKey !== undefined)
+                throw new McpReauthenticationRequiredError();
             const credential = document.credentials[credentialId];
             if (credential === undefined || credential.state !== 'active' || !matchesMcpProfile(credential)) {
                 throw new McpReauthenticationRequiredError();
@@ -88,6 +97,8 @@ export class McpTokenManager {
     }
     async authenticatedFetch(input, init = {}, fetchImpl = fetch) {
         const initial = await this.getAccessContext();
+        if (initial.apiKey)
+            return fetchWithApiKey(initial.accessToken, input, init, fetchImpl);
         const first = await fetchImpl(input, this.withBearer(init, initial.accessToken));
         if (first.status !== 401)
             return first;
@@ -95,6 +106,32 @@ export class McpTokenManager {
         const successor = await this.getAccessContext({ credentialId: initial.credentialId, rejectedToken: initial.accessToken });
         return fetchImpl(input, this.withBearer(init, successor.accessToken));
     }
+    async attachmentFetch(url, init, fetchImpl = fetch) {
+        if (url.origin !== 'https://api.abusybit.com' ||
+            url.search ||
+            url.hash ||
+            url.username ||
+            url.password ||
+            !/^\/v2\/trackers\/[^/]+\/items\/[^/]+\/attachments\/(?:uploads\/[^/]+\/content|[^/]+\/content)$/.test(url.pathname))
+            throw new Error('Invalid Tracker attachment transfer route.');
+        const initial = await this.getAccessContext();
+        const send = (accessToken) => {
+            const options = init();
+            const upload = url.pathname.includes('/attachments/uploads/');
+            if (options.method !== (upload ? 'PUT' : 'GET'))
+                throw new Error('Invalid attachment transfer method.');
+            const headers = new Headers(options.headers);
+            headers.set('authorization', `Bearer ${accessToken}`);
+            headers.set('x-abbit-credential-profile', 'mcp');
+            return fetchImpl(url, { ...options, headers, redirect: 'error' });
+        };
+        const first = await send(initial.accessToken);
+        if (first.status !== 401 || initial.apiKey)
+            return first;
+        await first.body?.cancel();
+        const successor = await this.getAccessContext({ credentialId: initial.credentialId, rejectedToken: initial.accessToken });
+        return send(successor.accessToken);
+    }
     withBearer(init, token) {
         const headers = new Headers(init.headers);
         headers.set('authorization', `Bearer ${token}`);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@abbit/abbit-mcp",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"description": "Abbit-owned local stdio MCP adapter.",
 	"license": "UNLICENSED",
 	"repository": {
@@ -29,7 +29,7 @@
 		"build": "tsc -p tsconfig.build.json",
 		"verify:package": "node scripts/verify-package.ts",
 		"typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
-		"test": "npm run build && tsc -p tsconfig.test.json && node --test test-dist/test/*.test.js",
+		"test": "npm run build && tsc -p tsconfig.test.json && node --test test-dist/test/*.test.js test-dist/test/unit/*.unit.spec.js",
 		"test:e2e": "npm run build && tsc -p tsconfig.test.json && node --test test-dist/test/proxy.test.js test-dist/test/token-manager.test.js"
 	},
 	"dependencies": {