appforshare-mcp 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# appforshare-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for [AppForShare](https://appforshare.io). Lets Claude Code, Cursor, Codex, VS Code, Gemini CLI and other
+MCP clients upload iOS and Android builds, find install links, read the store readiness check and follow App Store
+and Google Play releases and reviews.
+
+Needs an AppForShare API token (Pro and Team), from https://appforshare.io/dashboard/settings, and Node 18 or newer.
+
+```json
+{
+  "mcpServers": {
+    "appforshare": {
+      "command": "npx",
+      "args": ["-y", "appforshare-mcp"],
+      "env": { "APPFORSHARE_TOKEN": "afs_your_token" }
+    }
+  }
+}
+```
+
+Claude Code:
+
+```sh
+claude mcp add appforshare --env APPFORSHARE_TOKEN=afs_your_token -- npx -y appforshare-mcp
+```
+
+No local uploads needed? Use the hosted server instead: `https://appforshare.io/api/mcp` with the header
+`Authorization: Bearer afs_your_token`. Setup for each client: https://appforshare.io/docs/mcp
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `upload_build` | Upload a local .ipa, .apk or .aab (release notes, channel). Returns the install link and readiness result. |
+| `list_builds`, `latest_build` | Builds with install links, filtered by platform, app, project or channel. |
+| `build_info` | One build with every store readiness finding and its fix. |
+| `list_projects`, `whoami` | Projects in the account; account, plan and role of the token. |
+| `release_status`, `list_reviews` | App Store and Google Play release status and reviews. Read only. |
+| `promote_build`, `delete_build` | Change a channel or delete a build. Developer role and `confirm: true` required. |
+
+Environment: `APPFORSHARE_TOKEN` (required), `APPFORSHARE_API` (default `https://appforshare.io`).
+
+MIT licence.

package/dist/server.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// AppForShare MCP server over stdio. Every tool of the hosted server (https://appforshare.io/api/mcp) is passed
+// through with the same API token, plus `upload_build`, which reads a file from this computer and uploads it
+// with the same resumable API as the CLI. Only JSON-RPC goes to stdout; anything else goes to stderr.
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_readline_1 = require("node:readline");
+const VERSION = '1.0.1';
+const TOKEN = process.env.APPFORSHARE_TOKEN ?? '';
+const API = (process.env.APPFORSHARE_API ?? 'https://appforshare.io').replace(/\/$/, '');
+const UA = `appforshare-mcp/${VERSION}`;
+class ToolError extends Error {
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const send = (m) => void process.stdout.write(`${JSON.stringify(m)}\n`);
+const log = (s) => process.stderr.write(`appforshare-mcp: ${s}\n`);
+const UPLOAD_TOOL = {
+    name: 'upload_build',
+    title: 'Upload a build',
+    description: 'Upload an .ipa, .apk or .aab from this computer to AppForShare and return its install link and store readiness result. An .aab is turned into one APK for testers. Optional release notes and a channel (such as beta) whose stable link then opens this build.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Path to the .ipa, .apk or .aab file' },
+            notes: { type: 'string', description: 'Release notes shown to testers (Pro and Team)' },
+            channel: { type: 'string', description: 'Put the build into this channel when it is ready (Pro and Team)' },
+        },
+        required: ['path'],
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+};
+/** One call to the hosted MCP endpoint. */
+async function remote(msg) {
+    if (!TOKEN)
+        throw new ToolError('APPFORSHARE_TOKEN is not set. Create an API token at https://appforshare.io/dashboard/settings and add it to this MCP server\'s env.');
+    const res = await fetch(`${API}/api/mcp`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream', 'User-Agent': UA },
+        body: JSON.stringify(msg),
+    });
+    const data = (await res.json().catch(() => null));
+    if (data && 'jsonrpc' in data)
+        return data;
+    throw new ToolError(data?.message ?? `AppForShare answered ${res.status}`);
+}
+async function rest(method, path, opts = {}) {
+    for (let attempt = 1;; attempt++) {
+        let res;
+        try {
+            res = await fetch(`${API}/api${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${TOKEN}`,
+                    'User-Agent': UA,
+                    ...(opts.json !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                    ...(opts.body ? { 'Content-Type': 'application/octet-stream' } : {}),
+                    ...opts.headers,
+                },
+                body: opts.json !== undefined ? JSON.stringify(opts.json) : opts.body ? new Uint8Array(opts.body) : undefined,
+            });
+        }
+        catch (err) {
+            if (attempt >= 6)
+                throw new ToolError(`Network error: ${err.message}`);
+            await sleep(Math.min(30_000, 1000 * 2 ** attempt));
+            continue;
+        }
+        const data = (await res.json().catch(() => ({})));
+        if (res.status >= 500 && attempt < 6) {
+            await sleep(Math.min(30_000, 1000 * 2 ** attempt));
+            continue;
+        }
+        if (!res.ok && res.status !== 409 && !(res.status === 400 && typeof data.offset === 'number')) {
+            const msg = Array.isArray(data.message) ? data.message[0] : data.message;
+            throw new ToolError(msg || `Request failed with ${res.status}`);
+        }
+        return data;
+    }
+}
+function readChunk(fd, offset, length) {
+    const buf = Buffer.alloc(length);
+    let read = 0;
+    while (read < length) {
+        const n = (0, node_fs_1.readSync)(fd, buf, read, length - read, offset + read);
+        if (!n)
+            break;
+        read += n;
+    }
+    return buf.subarray(0, read);
+}
+async function upload(args) {
+    if (!TOKEN)
+        throw new ToolError('APPFORSHARE_TOKEN is not set. Create an API token at https://appforshare.io/dashboard/settings.');
+    if (typeof args.path !== 'string' || !args.path.trim())
+        throw new ToolError('path is required');
+    const file = (0, node_path_1.resolve)(args.path);
+    if (!/\.(ipa|apk|aab)$/i.test(file))
+        throw new ToolError('Only .ipa, .apk and .aab files can be shared. An .aab is turned into an APK for testers.');
+    let size;
+    try {
+        size = (0, node_fs_1.statSync)(file).size;
+    }
+    catch {
+        throw new ToolError(`File not found: ${file}`);
+    }
+    const notes = typeof args.notes === 'string' && args.notes.trim() ? args.notes.slice(0, 5000) : undefined;
+    const channel = typeof args.channel === 'string' && args.channel.trim() ? args.channel.trim() : undefined;
+    const created = await rest('POST', '/uploads', {
+        json: { fileName: (0, node_path_1.basename)(file), size, ...(notes ? { releaseNotes: notes } : {}), ...(channel ? { channel } : {}) },
+    });
+    const fd = (0, node_fs_1.openSync)(file, 'r');
+    let offset = created.offset;
+    try {
+        while (offset < size) {
+            const chunk = readChunk(fd, offset, Math.min(created.chunkBytes, size - offset));
+            const d = await rest('PUT', `/uploads/${created.id}?offset=${offset}`, { body: chunk, headers: { 'X-Upload-Token': created.token } });
+            offset = typeof d.offset === 'number' ? d.offset : offset + chunk.length;
+        }
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+    const h = { headers: { 'X-Upload-Token': created.token } };
+    await rest('POST', `/uploads/${created.id}/complete`, h);
+    const deadline = Date.now() + 20 * 60 * 1000;
+    let s;
+    for (;;) {
+        s = await rest('GET', `/uploads/${created.id}`, h);
+        if (s.status === 'READY' || s.status === 'FAILED')
+            break;
+        if (Date.now() > deadline)
+            throw new ToolError('Processing is taking too long. Check the AppForShare dashboard.');
+        await sleep(2000);
+    }
+    if (s.status === 'FAILED')
+        throw new ToolError(s.error ?? 'The build could not be processed.');
+    for (let i = 0; channel && !s.channel && i < 5; i++) {
+        await sleep(1000);
+        s = await rest('GET', `/uploads/${created.id}`, h);
+    }
+    let readiness = null;
+    try {
+        readiness = (await rest('GET', `/ci/builds/${encodeURIComponent(s.slug ?? '')}`)).readinessReport;
+    }
+    catch {
+        // Readiness is extra; the upload worked.
+    }
+    return { url: s.url, slug: s.slug, name: s.build?.name, version: s.build?.version, expiresAt: s.expiresAt, channel: s.channel, readiness };
+}
+async function handle(m) {
+    const reply = (result) => send({ jsonrpc: '2.0', id: m.id, result });
+    const fail = (code, message) => send({ jsonrpc: '2.0', id: m.id ?? null, error: { code, message } });
+    if (m.id === undefined)
+        return; // notifications need no answer
+    try {
+        switch (m.method) {
+            case 'initialize': {
+                const asked = typeof m.params?.protocolVersion === 'string' ? m.params.protocolVersion : '2025-06-18';
+                if (!TOKEN)
+                    log('APPFORSHARE_TOKEN is not set; tools will answer with an error until it is.');
+                return reply({
+                    protocolVersion: asked,
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo: { name: 'appforshare', title: 'AppForShare', version: VERSION, websiteUrl: 'https://appforshare.io/docs/mcp' },
+                    instructions: 'AppForShare shares iOS and Android test builds by install link and tracks App Store and Google Play releases. upload_build uploads a local .ipa or .apk. ' +
+                        'promote_build and delete_build change things: ask the person first and pass confirm: true.',
+                });
+            }
+            case 'ping':
+                return reply({});
+            case 'tools/list': {
+                let tools = [];
+                try {
+                    const r = await remote({ jsonrpc: '2.0', id: 1, method: 'tools/list' });
+                    tools = (r.result?.tools ?? []);
+                }
+                catch (err) {
+                    log(err.message);
+                }
+                return reply({ tools: [UPLOAD_TOOL, ...tools] });
+            }
+            case 'tools/call': {
+                if (m.params?.name === UPLOAD_TOOL.name) {
+                    try {
+                        const data = await upload((m.params.arguments ?? {}));
+                        return reply({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], structuredContent: data, isError: false });
+                    }
+                    catch (err) {
+                        return reply({ content: [{ type: 'text', text: err instanceof ToolError ? err.message : String(err) }], isError: true });
+                    }
+                }
+                try {
+                    const r = await remote({ jsonrpc: '2.0', id: m.id ?? 1, method: 'tools/call', params: m.params });
+                    return r.error ? send({ ...r, id: m.id }) : reply(r.result);
+                }
+                catch (err) {
+                    return reply({ content: [{ type: 'text', text: err.message }], isError: true });
+                }
+            }
+            default:
+                return fail(-32601, `Method not found: ${m.method}`);
+        }
+    }
+    catch (err) {
+        fail(-32603, err.message);
+    }
+}
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    process.stdout.write(`${VERSION}\n`);
+    process.exit(0);
+}
+const rl = (0, node_readline_1.createInterface)({ input: process.stdin, crlfDelay: Infinity });
+rl.on('line', (line) => {
+    if (!line.trim())
+        return;
+    let m;
+    try {
+        m = JSON.parse(line);
+    }
+    catch {
+        return send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+    }
+    void handle(m);
+});

package/package.json

@@ -1,6 +1,20 @@
 {
   "name": "appforshare-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "AppForShare MCP server for Claude Code, Cursor, Codex and other AI tools: upload iOS and Android builds, get install links, check store readiness and follow App Store and Google Play releases.",
+  "license": "MIT",
+  "author": "AppForShare",
+  "homepage": "https://appforshare.io/docs/mcp",
+  "keywords": ["mcp", "model-context-protocol", "ios", "android", "ipa", "apk", "testflight", "app-distribution", "beta-testing"],
+  "bin": { "appforshare-mcp": "dist/server.js" },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/server.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "~5.9.3"
+  }
+}