@abbit/abbit-mcp 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @abbit/abbit-mcp
 
-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.
+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
 
@@ -16,13 +16,13 @@ abbit-mcp login
 abbit-mcp status
 ```
 
-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 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.
 
-## Personal-key login
+## API-key login
 
-Use an existing Abbit personal API key with the permissions needed by your tools:
+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
@@ -31,16 +31,28 @@ 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
+abbit-mcp login --key < /secure/path/api-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.
+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` 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.
+`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 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.
+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
 
@@ -164,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/{personal-key.js → api-key.js}

@@ -1,8 +1,8 @@
 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) => {
+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 = '';
@@ -26,15 +26,15 @@ export const readPersonalKey = (input = process.stdin, output = process.stderr)
         value = '';
         if (error !== undefined)
             reject(error);
-        else if (personalKeyNamespace(key) === undefined)
-            reject(new Error('Enter a valid Abbit personal API key.'));
+        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 personal API key.'));
+    const onError = () => finish(new Error('Could not read the API key.'));
     const onEnd = () => finish();
-    const onClose = () => finish(new Error('Personal-key input closed.'));
-    const onTerminate = () => finish(new Error('Personal-key login canceled.'));
+    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'))
@@ -46,24 +46,24 @@ export const readPersonalKey = (input = process.stdin, output = process.stderr)
             else
                 value += char;
             if (value.length > 2_048)
-                return finish(new Error('Personal-key input is too long.'));
+                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('Personal API key (hidden): ');
+        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 fetchWithPersonalKey = async (key, input, init = {}, fetchImpl = fetch) => {
+export const fetchWithApiKey = 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.');
+        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 {
@@ -77,16 +77,16 @@ export const fetchWithPersonalKey = async (key, input, init = {}, fetchImpl = fe
         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: {} });
+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 fetchWithPersonalKey(key, input, { ...init, signal: AbortSignal.timeout(iamRequestTimeoutMs) }, fetchImpl);
+            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('Personal-key authentication failed.');
+                throw new Error('API-key authentication failed.');
             }
             return response;
         },
@@ -95,7 +95,7 @@ export const validatePersonalKey = async (key, fetchImpl = fetch) => {
         await client.connect(transport, { timeout: iamRequestTimeoutMs });
     }
     catch {
-        throw new Error('Could not authenticate the personal key with Abbit MCP. Check the key and connection.');
+        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,9 +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, personalKeyNamespace } from './model.js';
-import { validatePersonalKey } from './personal-key.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';
@@ -215,6 +215,7 @@ export class McpAuthService {
             };
             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)
@@ -246,16 +247,21 @@ export class McpAuthService {
         }
     }
     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 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 = [];
             }
-            document.personalKey = key;
+            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)
@@ -264,11 +270,11 @@ export class McpAuthService {
             };
         });
         await this.revokePending(pending);
-        return { namespaceId };
+        return parsed;
     }
     async status(currentTime = new Date()) {
         const document = await this.store.read();
-        const keyNamespace = personalKeyNamespace(document.personalKey);
+        const key = parseApiKey(document.personalKey ?? document.serviceKey);
         const records = Object.values(document.credentials).filter(matchesAnyMcp);
         const stateFor = (record) => {
             if (record.state === 'pendingRevocation')
@@ -281,10 +287,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' });
+        if (key !== undefined)
+            namespaces.unshift({ namespaceId: key.namespaceId, state: 'active' });
         return {
-            ...(keyNamespace === undefined ? {} : { personalKeyNamespace: keyNamespace }),
+            ...(key === undefined ? {} : { apiKey: key }),
             authenticated: namespaces.some(({ state }) => state === 'active'),
             pendingRevocation: namespaces.some(({ state }) => state === 'pendingRevocation'),
             reauthenticationRequired: namespaces.some(({ state }) => state === 'reauthenticationRequired'),
@@ -294,8 +300,9 @@ export class McpAuthService {
     async logout() {
         let forgotten = 0;
         const pending = await this.store.withLock(async (document) => {
-            forgotten = document.personalKey === undefined ? 0 : 1;
+            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';

package/dist/cli.js

@@ -1,27 +1,28 @@
 #!/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';
-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.2.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 personal keys through hidden input or stdin, never arguments.\n'),
+    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 or with a personal key')
-    .option('--key', 'Read an existing personal API key from hidden input or stdin')
+    .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 readPersonalKey());
-        process.stdout.write(`Authenticated Abbit MCP with a personal key for namespace ${JSON.stringify(record.namespaceId)}.\n`);
+        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`) });
@@ -32,8 +33,8 @@ program
     .description('Show local Abbit MCP authentication status')
     .action(async () => {
     const status = await auth.status();
-    if (status.personalKeyNamespace !== undefined) {
-        process.stdout.write(`Personal key saved for namespace ${JSON.stringify(status.personalKeyNamespace)} (server checks validity on use).\n`);
+    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')) {
@@ -50,11 +51,11 @@ program
 });
 program
     .command('logout')
-    .description('Forget a personal key locally and revoke browser OAuth 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('Personal key removed locally. The key remains valid until revoked in IAM.\n');
+        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;
@@ -77,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/model.js

@@ -56,11 +56,11 @@ export const isMcpRefreshToken = (value, expectedNamespaceId) => {
     const namespaceId = decodeNamespaceLocator(locator);
     return namespaceId !== undefined && (expectedNamespaceId === undefined || namespaceId === expectedNamespaceId);
 };
-export const personalKeyNamespace = (value) => {
+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' ||
+    if ((prefix !== 'abbit_pk_v1' && prefix !== 'abbit_sk_v1') ||
         locator === undefined ||
         lookup === undefined ||
         secret === undefined ||
@@ -68,7 +68,8 @@ export const personalKeyNamespace = (value) => {
         !/^[A-Za-z0-9_-]{21}[AQgw]$/u.test(lookup) ||
         !/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/u.test(secret))
         return undefined;
-    return decodeNamespaceLocator(locator);
+    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']) &&
@@ -128,10 +129,17 @@ const isCredential = (value) => {
 export const emptyCredentialDocument = () => ({ version: 1, credentials: {} });
 export const parseCredentialDocument = (value) => {
     if (!isRecord(value) ||
-        !hasExactKeys(value, 'personalKey' in value ? ['version', 'credentials', 'personalKey'] : ['version', 'credentials']) ||
+        !hasExactKeys(value, [
+            'version',
+            'credentials',
+            ...('personalKey' in value ? ['personalKey'] : []),
+            ...('serviceKey' in value ? ['serviceKey'] : []),
+        ]) ||
         value.version !== 1 ||
         !isRecord(value.credentials) ||
-        ('personalKey' in value && personalKeyNamespace(value.personalKey) === undefined)) {
+        ('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.2.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.2.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,7 +1,7 @@
 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';
-import { fetchWithPersonalKey } from './personal-key.js';
 export class McpReauthenticationRequiredError extends Error {
     constructor() {
         super('Abbit MCP authentication is required. Run `abbit-mcp login`.');
@@ -36,10 +36,11 @@ export class McpTokenManager {
     async getAccessContext(options = {}) {
         const initialNow = this.now();
         const initialDocument = await this.store.read();
-        if (initialDocument.personalKey !== undefined) {
+        const key = initialDocument.personalKey ?? initialDocument.serviceKey;
+        if (key !== undefined) {
             if (options.credentialId !== undefined || options.rejectedToken !== undefined)
                 throw new McpReauthenticationRequiredError();
-            return { accessToken: initialDocument.personalKey, credentialId: 'personal-key', personalKey: true };
+            return { accessToken: key, credentialId: 'api-key', apiKey: true };
         }
         const initial = options.credentialId === undefined
             ? selectCredential(Object.values(initialDocument.credentials))
@@ -56,7 +57,7 @@ export class McpTokenManager {
             return { accessToken: cached.accessToken, credentialId };
         return this.store.withLock(async (document, commit) => {
             const completedAt = this.now();
-            if (document.personalKey !== undefined)
+            if (document.personalKey !== undefined || document.serviceKey !== undefined)
                 throw new McpReauthenticationRequiredError();
             const credential = document.credentials[credentialId];
             if (credential === undefined || credential.state !== 'active' || !matchesMcpProfile(credential)) {
@@ -96,8 +97,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);
+        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;
@@ -105,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.2.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": {