@alfe.ai/social-mcp 0.2.0

package/README.md

@@ -0,0 +1,22 @@
+# @alfe.ai/social-mcp
+
+Social MCP server — lets agents post, engage, and read on their connected social accounts (Bluesky today; X / Meta / Threads / LinkedIn / Pinterest / TikTok / Reddit / YouTube on the approval-gated roster) using Alfe Connect credentials. Pattern A multi-account; the platform is selected via `--provider`.
+
+Part of [**Alfe**](https://alfe.ai) — the operating system for AI agents: build, deploy, and run agents with persistent memory, identity, integrations, and channels. See the [documentation](https://docs.alfe.ai) to get started.
+
+## Install
+
+```bash
+npm install @alfe.ai/social-mcp
+```
+
+## Usage
+
+```bash
+npx @alfe.ai/social-mcp --provider bluesky
+```
+
+## Links
+
+- 🌐 Website: <https://alfe.ai>
+- 📚 Docs: <https://docs.alfe.ai>

package/dist/server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server.js

@@ -0,0 +1,738 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { resolveConfig } from "@alfe.ai/config";
+import { AgentApiClient } from "@alfe.ai/agent-api-client";
+import { assertPatternA } from "@alfe.ai/mcp-bundler";
+import { z } from "zod";
+//#region src/args.ts
+/**
+* Provider selection for the social MCP server.
+*
+* The provider (`bluesky`, and later `x`, `meta`, `threads`, …) is chosen via
+* a CLI **argument**, NOT an environment variable. This is load-bearing:
+*
+*   npx @alfe.ai/social-mcp --provider bluesky      (flag form)
+*   npx @alfe.ai/social-mcp bluesky                  (positional form)
+*
+* Why args and not env (from the plan + plugin-engineer audit):
+* `mcp-applier.resolveEnv` short-circuits MCP registration when a required env
+* var is unresolved (e.g. a zero-account 404). If the provider were passed via
+* `env`, that short-circuit would key off the provider var and skip registering
+* the server entirely — killing the zero-account graceful-degradation this
+* package relies on (start with `social_list_accounts` only, never crash the
+* daemon). Keeping the provider in `args` means the manifest env stays EMPTY,
+* exactly like `@alfe.ai/github-mcp`, and the server always registers.
+*
+* Pure + no I/O so it's unit-testable.
+*/
+/** Providers this shared package can drive. Bluesky is the only shipped one. */
+const SUPPORTED_PROVIDERS = ["bluesky"];
+function isSupportedProvider(value) {
+	return SUPPORTED_PROVIDERS.includes(value);
+}
+/**
+* Extract the provider from an argv slice (typically `process.argv.slice(2)`).
+* Accepts `--provider <id>`, `--provider=<id>`, or a bare positional `<id>`.
+* Returns `{ ok: false, error }` for a missing/unknown provider so the caller
+* can log a clear startup error and exit — this is an operator/manifest
+* misconfiguration, distinct from the zero-account (graceful) path.
+*/
+function parseProviderArg(argv) {
+	let raw;
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--provider") {
+			raw = argv[i + 1];
+			break;
+		}
+		if (arg.startsWith("--provider=")) {
+			raw = arg.slice(11);
+			break;
+		}
+		if (raw === void 0 && !arg.startsWith("-")) raw = arg;
+	}
+	if (!raw) return {
+		ok: false,
+		error: `No social provider selected. Pass one via --provider (e.g. "--provider bluesky"). Supported: ${SUPPORTED_PROVIDERS.join(", ")}.`
+	};
+	const provider = raw.trim().toLowerCase();
+	if (!isSupportedProvider(provider)) return {
+		ok: false,
+		error: `Unsupported social provider "${raw}". Supported: ${SUPPORTED_PROVIDERS.join(", ")}.`
+	};
+	return {
+		ok: true,
+		provider
+	};
+}
+//#endregion
+//#region src/drivers/facets.ts
+/**
+* URL detector. Matches http(s) URLs; trailing punctuation that is almost
+* always sentence punctuation rather than part of the URL is trimmed off the
+* match (Bluesky's own reference detector does the same) so "see https://a.co."
+* links `https://a.co` not `https://a.co.`.
+*/
+const URL_RE = /https?:\/\/[^\s]+/g;
+/** Trailing chars to strip from a matched URL (sentence punctuation, closers). */
+const TRAILING_TRIM = /[.,;:!?)\]}'"]+$/;
+const encoder = new TextEncoder();
+/** UTF-8 byte length of a string — the unit Bluesky facet offsets are in. */
+function utf8Len(text) {
+	return encoder.encode(text).length;
+}
+/**
+* Detect link facets in `text`, returning byte-offset ranges suitable for an
+* `app.bsky.feed.post.facets` array. Empty when there are no URLs.
+*
+* Implementation note: we walk matches in string space (RegExp works on the
+* JS string), but convert each match's [startCharIdx, endCharIdx) to
+* [byteStart, byteEnd) by measuring the UTF-8 length of the substrings. This
+* is O(n) in the number of matches and correct across multi-byte characters.
+*/
+function detectLinkFacets(text) {
+	const facets = [];
+	for (const match of text.matchAll(URL_RE)) {
+		const start = match.index;
+		let raw = match[0];
+		const trimmed = raw.replace(TRAILING_TRIM, "");
+		if (!trimmed) continue;
+		raw = trimmed;
+		const end = start + raw.length;
+		const byteStart = utf8Len(text.slice(0, start));
+		const byteEnd = byteStart + utf8Len(text.slice(start, end));
+		facets.push({
+			index: {
+				byteStart,
+				byteEnd
+			},
+			features: [{
+				$type: "app.bsky.richtext.facet#link",
+				uri: raw
+			}]
+		});
+	}
+	return facets;
+}
+//#endregion
+//#region src/drivers/bluesky.ts
+const DEFAULT_PDS_HOST = "https://bsky.social";
+/** Bluesky's hard post-text limit is 300 graphemes; we enforce on JS length as a floor. */
+const POST_TEXT_MAX = 300;
+/** Bound every XRPC call so a hung PDS can't stall the MCP server. */
+const XRPC_TIMEOUT_MS = 1e4;
+const CAPABILITIES = {
+	postText: true,
+	reply: true,
+	getPost: true,
+	getMetrics: true,
+	listNotifications: true,
+	search: true,
+	deletePost: true
+};
+/** Reject any non-https PDS host (defence-in-depth SSRF guard). */
+function assertHttpsPdsHost(pdsHost) {
+	let url;
+	try {
+		url = new URL(pdsHost);
+	} catch {
+		throw new Error(`Invalid pdsHost "${pdsHost}"`);
+	}
+	if (url.protocol !== "https:") throw new Error(`Refusing non-https pdsHost "${pdsHost}" (SSRF guard)`);
+}
+/**
+* Parse a `getSocialAccounts` entry into a usable {@link BlueskyAccount} or a
+* {@link DegradedAccount}. Exported for unit testing the bundle-parse contract.
+*/
+function parseAccountEntry(entry) {
+	const meta = entry.providerMetadata;
+	const handle = typeof meta.handle === "string" ? meta.handle : "";
+	const did = entry.accountIdentifier || (typeof meta.did === "string" ? meta.did : "");
+	const pdsHost = typeof meta.pdsHost === "string" && meta.pdsHost ? meta.pdsHost : DEFAULT_PDS_HOST;
+	const base = {
+		did,
+		handle,
+		displayName: entry.displayName,
+		connectedAt: entry.connectedAt
+	};
+	let bundle;
+	try {
+		bundle = JSON.parse(entry.accessToken);
+	} catch {
+		return {
+			...base,
+			reason: "unparseable_session_bundle"
+		};
+	}
+	if (!bundle.accessJwt) return {
+		...base,
+		reason: "missing_access_jwt"
+	};
+	try {
+		assertHttpsPdsHost(pdsHost);
+	} catch (err) {
+		return {
+			...base,
+			reason: err instanceof Error ? err.message : "bad_pds_host"
+		};
+	}
+	return {
+		...base,
+		pdsHost,
+		accessJwt: bundle.accessJwt
+	};
+}
+/** Thrown when the PDS says the session is expired/invalid (drives one refresh). */
+var ExpiredTokenError = class extends Error {};
+var BlueskyDriver = class BlueskyDriver {
+	provider = "bluesky";
+	toolPrefix = "bluesky";
+	capabilities = CAPABILITIES;
+	api;
+	accounts = /* @__PURE__ */ new Map();
+	byHandle = /* @__PURE__ */ new Map();
+	degraded = [];
+	constructor(api) {
+		this.api = api;
+	}
+	/**
+	* Build a driver from the agent's connected Bluesky accounts. Zero accounts
+	* is NOT an error — the server degrades gracefully (only `social_list_
+	* accounts` / `bluesky_check_connection` register). Per-account parse
+	* failures are recorded as degraded rather than failing the whole driver.
+	*/
+	static async create(api) {
+		const driver = new BlueskyDriver(api);
+		const { accounts } = await api.getSocialAccounts("bluesky");
+		for (const entry of accounts) driver.ingest(entry);
+		return driver;
+	}
+	ingest(entry) {
+		const parsed = parseAccountEntry(entry);
+		if ("reason" in parsed) {
+			this.degraded.push(parsed);
+			return;
+		}
+		this.accounts.set(parsed.did, parsed);
+		if (parsed.handle) this.byHandle.set(parsed.handle, parsed.did);
+	}
+	/** Resolve the `account` selector (DID or handle) to a usable account. */
+	resolve(account) {
+		if (!account) throw new Error("Missing required `account` argument. Call social_list_accounts to see connected Bluesky accounts and pass the handle or DID you want to target.");
+		const did = this.accounts.has(account) ? account : this.byHandle.get(account);
+		const acct = did ? this.accounts.get(did) : void 0;
+		if (!acct) {
+			const degraded = this.degraded.find((d) => d.did === account || d.handle === account);
+			if (degraded) throw new Error(`Account "${account}" is connected but not usable (reason: ${degraded.reason}). Ask the user to reconnect this Bluesky account from the dashboard.`);
+			throw new Error(`Unknown account "${account}". Call social_list_accounts to see connected Bluesky accounts on this agent.`);
+		}
+		return acct;
+	}
+	listAccounts() {
+		const usable = [...this.accounts.values()].map((a) => ({
+			accountIdentifier: a.did,
+			handle: a.handle,
+			displayName: a.displayName,
+			connectedAt: a.connectedAt,
+			connected: true
+		}));
+		const broken = this.degraded.map((d) => ({
+			accountIdentifier: d.did,
+			handle: d.handle,
+			displayName: d.displayName,
+			connectedAt: d.connectedAt,
+			connected: false,
+			reason: d.reason
+		}));
+		return [...usable, ...broken];
+	}
+	/**
+	* Authenticated XRPC call with the account's current accessJwt. On a 401 /
+	* ExpiredToken, refresh ONCE via connect + re-fetch accounts, then retry.
+	* Honors a single `Retry-After` on 429. Never logs tokens.
+	*/
+	async xrpc(acct, method, nsid, opts = {}) {
+		assertHttpsPdsHost(acct.pdsHost);
+		const url = new URL(`${acct.pdsHost}/xrpc/${nsid}`);
+		for (const [k, v] of Object.entries(opts.query ?? {})) if (Array.isArray(v)) for (const item of v) url.searchParams.append(k, item);
+		else url.searchParams.set(k, v);
+		const headers = {
+			Authorization: `Bearer ${acct.accessJwt}`,
+			Accept: "application/json"
+		};
+		if (method === "POST") headers["Content-Type"] = "application/json";
+		const res = await fetch(url, {
+			method,
+			headers,
+			body: method === "POST" ? JSON.stringify(opts.body ?? {}) : void 0,
+			signal: AbortSignal.timeout(XRPC_TIMEOUT_MS)
+		});
+		if (res.status === 429 && !opts.retried429) {
+			const retryAfter = Number(res.headers.get("retry-after"));
+			const delayMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1e3 : 1e3;
+			await new Promise((r) => setTimeout(r, Math.min(delayMs, 3e4)));
+			return this.xrpc(acct, method, nsid, {
+				...opts,
+				retried429: true
+			});
+		}
+		if (res.status === 401) {
+			if (opts.retriedAuth) throw new ExpiredTokenError(`Bluesky session invalid for ${acct.handle || acct.did} after refresh. Ask the user to reconnect.`);
+			const refreshed = await this.refreshAccount(acct.did);
+			return this.xrpc(refreshed, method, nsid, {
+				...opts,
+				retriedAuth: true,
+				retried429: false
+			});
+		}
+		if (!res.ok) {
+			let detail = "";
+			try {
+				const b = await res.json();
+				detail = b.error ?? b.message ?? "";
+			} catch {}
+			if (detail === "ExpiredToken" && !opts.retriedAuth) {
+				const refreshed = await this.refreshAccount(acct.did);
+				return this.xrpc(refreshed, method, nsid, {
+					...opts,
+					retriedAuth: true,
+					retried429: false
+				});
+			}
+			throw new Error(`Bluesky ${nsid} failed: HTTP ${String(res.status)}${detail ? ` (${detail})` : ""}`);
+		}
+		return res.json();
+	}
+	/** Delegate refresh to connect, then re-fetch accounts for the fresh jwt. */
+	async refreshAccount(did) {
+		await this.api.refreshSocialAccount("bluesky", did);
+		const { accounts } = await this.api.getSocialAccounts("bluesky");
+		const entry = accounts.find((a) => a.accountIdentifier === did);
+		if (entry) {
+			const parsed = parseAccountEntry(entry);
+			if (!("reason" in parsed)) {
+				this.accounts.set(parsed.did, parsed);
+				if (parsed.handle) this.byHandle.set(parsed.handle, parsed.did);
+				return parsed;
+			}
+		}
+		throw new ExpiredTokenError(`Could not resolve a usable Bluesky session for ${did} after refresh. Ask the user to reconnect.`);
+	}
+	async checkConnection(account) {
+		const acct = this.resolve(account);
+		const session = await this.xrpc(acct, "GET", "com.atproto.server.getSession");
+		return { data: {
+			account: acct.handle || acct.did,
+			connected: true,
+			did: session.did,
+			handle: session.handle
+		} };
+	}
+	async postText(args) {
+		const acct = this.resolve(args.account);
+		const len = graphemeLen(args.text);
+		if (len > POST_TEXT_MAX) throw new Error(`Post text is ${String(len)} characters; Bluesky's limit is ${String(POST_TEXT_MAX)}. Shorten it.`);
+		const record = {
+			$type: "app.bsky.feed.post",
+			text: args.text,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			facets: detectLinkFacets(args.text)
+		};
+		const out = await this.xrpc(acct, "POST", "com.atproto.repo.createRecord", { body: {
+			repo: acct.did,
+			collection: "app.bsky.feed.post",
+			record
+		} });
+		return { data: {
+			uri: out.uri,
+			cid: out.cid,
+			account: acct.handle || acct.did
+		} };
+	}
+	async reply(args) {
+		const acct = this.resolve(args.account);
+		const len = graphemeLen(args.text);
+		if (len > POST_TEXT_MAX) throw new Error(`Reply text is ${String(len)} characters; Bluesky's limit is ${String(POST_TEXT_MAX)}. Shorten it.`);
+		const parent = await this.xrpc(acct, "GET", "app.bsky.feed.getPostThread", { query: { uri: args.parent } });
+		const parentPost = parent.thread?.post;
+		if (!parentPost?.uri || !parentPost.cid) throw new Error(`Could not resolve parent post "${args.parent}" for reply.`);
+		const parentRef = {
+			uri: parentPost.uri,
+			cid: parentPost.cid
+		};
+		const rootRef = deriveRoot(parent.thread) ?? parentRef;
+		const record = {
+			$type: "app.bsky.feed.post",
+			text: args.text,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			facets: detectLinkFacets(args.text),
+			reply: {
+				root: rootRef,
+				parent: parentRef
+			}
+		};
+		const out = await this.xrpc(acct, "POST", "com.atproto.repo.createRecord", { body: {
+			repo: acct.did,
+			collection: "app.bsky.feed.post",
+			record
+		} });
+		return { data: {
+			uri: out.uri,
+			cid: out.cid,
+			account: acct.handle || acct.did
+		} };
+	}
+	async getPost(args) {
+		const acct = this.resolve(args.account);
+		return { data: { posts: (await this.xrpc(acct, "GET", "app.bsky.feed.getPosts", { query: { uris: [args.post] } })).posts ?? [] } };
+	}
+	async getMetrics(args) {
+		const acct = this.resolve(args.account);
+		const post = (await this.xrpc(acct, "GET", "app.bsky.feed.getPosts", { query: { uris: [args.post] } })).posts?.[0];
+		if (!post) throw new Error(`No post found for "${args.post}".`);
+		return { data: {
+			uri: post.uri,
+			likes: post.likeCount ?? 0,
+			reposts: post.repostCount ?? 0,
+			replies: post.replyCount ?? 0,
+			quotes: post.quoteCount ?? 0
+		} };
+	}
+	async listNotifications(args) {
+		const acct = this.resolve(args.account);
+		const query = {};
+		if (typeof args.limit === "number") query.limit = String(Math.min(Math.max(args.limit, 1), 100));
+		return { data: { notifications: (await this.xrpc(acct, "GET", "app.bsky.notification.listNotifications", { query })).notifications ?? [] } };
+	}
+	async search(args) {
+		const acct = this.resolve(args.account);
+		const query = { q: args.query };
+		if (typeof args.limit === "number") query.limit = String(Math.min(Math.max(args.limit, 1), 100));
+		return { data: { posts: (await this.xrpc(acct, "GET", "app.bsky.feed.searchPosts", { query })).posts ?? [] } };
+	}
+	async deletePost(args) {
+		const acct = this.resolve(args.account);
+		const rkey = rkeyFromUri(args.post);
+		if (!rkey) throw new Error(`Could not parse a record key from "${args.post}".`);
+		await this.xrpc(acct, "POST", "com.atproto.repo.deleteRecord", { body: {
+			repo: acct.did,
+			collection: "app.bsky.feed.post",
+			rkey
+		} });
+		return { data: {
+			deleted: true,
+			uri: args.post
+		} };
+	}
+};
+/**
+* Grapheme count. Bluesky's 300-character post limit is measured in graphemes
+* (user-perceived characters), so a family emoji or a combining-mark sequence
+* counts as one — using JS `.length` (UTF-16 code units) would over-count and
+* reject valid posts. `Intl.Segmenter` gives the correct grapheme count.
+*/
+const graphemeSegmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+function graphemeLen(text) {
+	return [...graphemeSegmenter.segment(text)].length;
+}
+/** Extract the record key (last path segment) from an at:// URI. */
+function rkeyFromUri(uri) {
+	const parts = uri.split("/");
+	const last = parts[parts.length - 1];
+	return last && parts.length >= 3 ? last : null;
+}
+/**
+* Best-effort thread-root ref extraction from a getPostThread response.
+*
+* Reads the parent post's OWN `record.reply.root` — for a nested reply that is
+* the true thread root. LIMITATION: when the parent record carries no
+* `reply.root` (e.g. the thread lookup was shallow, or the parent record shape
+* was unexpected), the caller falls back to using the parent itself as the
+* root. On a deep reply that fallback yields root === parent, which is only
+* correct when replying to a top-level post; it can mis-root a deep reply.
+*/
+function deriveRoot(thread) {
+	if (!thread) return void 0;
+	const root = thread.post?.record?.reply?.root;
+	if (root?.uri && root.cid) return {
+		uri: root.uri,
+		cid: root.cid
+	};
+}
+//#endregion
+//#region src/tools.ts
+/**
+* Tool registration for the social MCP server.
+*
+* Tools are built from a {@link SocialDriver}'s capability flags — the server
+* registers a credential-touching tool ONLY when the driver declares the
+* matching capability, so each platform gets exactly its own subset (per-
+* platform subsetting lives in the driver, never the manifest).
+*
+* Pattern A: every credential-touching tool requires an `account` selector
+* (the value from `social_list_accounts`). `social_list_accounts` is the sole
+* selector-exempt discovery tool. `buildPatternADescriptors()` returns the
+* JSON-Schema-shaped view of the registered tools so `server.ts` can run
+* `assertPatternA()` at startup — if a new tool ever forgets the `account`
+* field, the server refuses to start rather than shipping a credential-leak-
+* shaped contract regression.
+*
+* SINGLE SOURCE OF TRUTH: both `registerTools()` (what the LLM sees) and
+* `buildPatternADescriptors()` (what the Pattern A guard validates) are derived
+* from the one {@link ACTION_TOOL_SPECS} table below. A tool can't be added to
+* registration without also appearing in the descriptors the guard checks —
+* the two can never drift apart, so the guard can't be fooled by a hand-built
+* mirror going stale. `assertToolsMatchDescriptors()` additionally asserts the
+* two derived name sets are identical as a belt-and-braces regression fence.
+*
+* Tool naming mirrors the connect-credential MCP convention: the discovery /
+* health tools are `social_*` (platform-agnostic), while the action tools are
+* `<prefix>_*` (e.g. `bluesky_post_text`) — matching how `@alfe.ai/github-mcp`
+* names `github_list_accounts` alongside its GitHub-specific tools.
+*/
+function ok(data) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(data, null, 2)
+	}] };
+}
+function fail(err) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }, null, 2)
+		}],
+		isError: true
+	};
+}
+const accountField = z.string().describe("The connected account to act as — the handle or DID from social_list_accounts. Selects which OAuth identity makes the call (Pattern A).");
+/**
+* The one table both registration and descriptor-building derive from. The
+* `capability` field is BOTH the `SocialCapabilities` flag and the same-named
+* optional method on `SocialDriver`, so a spec is live IFF
+* `driver.capabilities[cap] && typeof driver[cap] === "function"`.
+*/
+const ACTION_TOOL_SPECS = [
+	{
+		capability: "postText",
+		suffix: "post_text",
+		description: "Publish a text post as the selected account. Links in the text are auto-detected and made clickable. Enforces the platform's character limit.",
+		inputSchema: {
+			account: accountField,
+			text: z.string().describe("The post body.")
+		}
+	},
+	{
+		capability: "reply",
+		suffix: "reply",
+		description: "Reply to a post as the selected account. Pass the parent post's URI/id; the thread root is resolved automatically.",
+		inputSchema: {
+			account: accountField,
+			parent: z.string().describe("URI/id of the post being replied to."),
+			text: z.string().describe("The reply body.")
+		}
+	},
+	{
+		capability: "getPost",
+		suffix: "get_post",
+		description: "Fetch a post by its URI/id as the selected account.",
+		inputSchema: {
+			account: accountField,
+			post: z.string().describe("URI/id of the post to fetch.")
+		}
+	},
+	{
+		capability: "getMetrics",
+		suffix: "get_metrics",
+		description: "Get like / repost / reply / quote counts for a post.",
+		inputSchema: {
+			account: accountField,
+			post: z.string().describe("URI/id of the post to measure.")
+		}
+	},
+	{
+		capability: "listNotifications",
+		suffix: "list_notifications",
+		description: "List recent notifications (mentions, replies, likes, follows) for the selected account.",
+		inputSchema: {
+			account: accountField,
+			limit: z.number().int().min(1).max(100).optional().describe("Max notifications (1-100).")
+		}
+	},
+	{
+		capability: "search",
+		suffix: "search",
+		description: "Search posts as the selected account.",
+		inputSchema: {
+			account: accountField,
+			query: z.string().describe("Search query."),
+			limit: z.number().int().min(1).max(100).optional().describe("Max results (1-100).")
+		}
+	},
+	{
+		capability: "deletePost",
+		suffix: "delete_post",
+		description: "Delete a post the selected account authored, by its URI/id.",
+		inputSchema: {
+			account: accountField,
+			post: z.string().describe("URI/id of the post to delete.")
+		}
+	}
+];
+/**
+* Resolve the live driver method for a spec, or `undefined` if the driver
+* hasn't enabled this capability. The `capability` key names the optional
+* method 1:1, so this is the single place both registration and descriptors
+* ask "is this tool live?".
+*/
+function resolveMethod(driver, spec) {
+	if (!driver.capabilities[spec.capability]) return void 0;
+	const method = driver[spec.capability];
+	if (typeof method !== "function") return void 0;
+	return (args) => method.call(driver, args);
+}
+/**
+* Register the discovery + health tools and every capability-enabled action
+* tool onto the MCP server. The discovery tool is always `social_list_accounts`;
+* action tools are prefixed with the driver's `toolPrefix` and driven off the
+* shared {@link ACTION_TOOL_SPECS} table.
+*/
+function registerTools(server, driver) {
+	const register = server.registerTool.bind(server);
+	const p = driver.toolPrefix;
+	register("social_list_accounts", {
+		description: "List the social accounts the agent has connected for this platform. Returns one entry per connection — use the returned handle or accountIdentifier as the `account` selector on every other tool. Entries with connected=false could not be initialised; ask the user to reconnect them.",
+		inputSchema: {}
+	}, () => ok({ accounts: driver.listAccounts() }));
+	register(`${p}_check_connection`, {
+		description: "Verify a connected account's session is still valid. Use this if calls are failing with authentication errors.",
+		inputSchema: { account: accountField }
+	}, async (args) => {
+		try {
+			return ok((await driver.checkConnection(args.account)).data);
+		} catch (err) {
+			return fail(err);
+		}
+	});
+	for (const spec of ACTION_TOOL_SPECS) {
+		const method = resolveMethod(driver, spec);
+		if (!method) continue;
+		register(`${p}_${spec.suffix}`, {
+			description: spec.description,
+			inputSchema: spec.inputSchema
+		}, (args) => method(args).then((r) => ok(r.data), (err) => fail(err)));
+	}
+}
+/**
+* Build the JSON-Schema-shaped descriptor list for `assertPatternA()`. Every
+* registered action tool carries a required `account` string; the discovery
+* tool (`social_list_accounts`) is exempt. Derived from the SAME
+* {@link ACTION_TOOL_SPECS} table as `registerTools()`, so the guard can never
+* validate a stale hand-built mirror.
+*/
+function buildPatternADescriptors(driver) {
+	const p = driver.toolPrefix;
+	const accountSchema = {
+		type: "object",
+		properties: { account: { type: "string" } },
+		required: ["account"]
+	};
+	const tools = [{
+		name: "social_list_accounts",
+		parameters: {
+			type: "object",
+			properties: {}
+		}
+	}, {
+		name: `${p}_check_connection`,
+		parameters: accountSchema
+	}];
+	for (const spec of ACTION_TOOL_SPECS) if (resolveMethod(driver, spec)) tools.push({
+		name: `${p}_${spec.suffix}`,
+		parameters: accountSchema
+	});
+	return tools;
+}
+/** The discovery tool name — the sole Pattern A exemption. */
+const DISCOVERY_TOOL_NAME = "social_list_accounts";
+//#endregion
+//#region src/server.ts
+/**
+* Social MCP Server (Pattern A multi-account, provider selected via --provider).
+*
+* A standalone stdio MCP server that lets an agent post, engage, and read on
+* its connected social accounts using Alfe Connect credentials. Runtime-
+* agnostic — spawned via `npx -y @alfe.ai/social-mcp --provider <id>` from an
+* integration manifest.
+*
+* Architecture:
+*   Agent runtime ←(stdio/MCP)→ this server ←(HTTPS/XRPC)→ platform PDS/API
+*
+* Provider selection is via a CLI ARGUMENT, never `env` — see `args.ts` for
+* why (env would break `mcp-applier.resolveEnv` short-circuiting and kill the
+* zero-account graceful-degradation path). Manifest env stays EMPTY, exactly
+* like `@alfe.ai/github-mcp`.
+*
+* Zero-account degradation: startup with no connected accounts is NOT fatal —
+* the server still registers `social_list_accounts` + `<prefix>_check_
+* connection` so the LLM can report the empty state and prompt the user to
+* connect, exactly like github-mcp. It never exits non-zero for zero accounts.
+*
+* Credentials: resolved at startup via `AgentApiClient.getSocialAccounts
+* (provider)`. Token refresh is delegated to connect (the driver calls
+* `refreshSocialAccount` on a 401) — never done in-plugin.
+*
+* Pattern A: every credential-touching tool requires an `account` selector;
+* `assertPatternA()` runs at startup so a forgotten selector fails closed.
+*/
+function log(msg) {
+	process.stderr.write(`[social-mcp] ${msg}\n`);
+}
+/**
+* Per-provider driver factories. Adding a platform = add a `SocialDriver`
+* implementation and register its factory here (plus `SUPPORTED_PROVIDERS` in
+* `args.ts`). Keyed by provider id so there's no tautological switch while
+* only one provider ships.
+*/
+const DRIVER_FACTORIES = { bluesky: (api) => BlueskyDriver.create(api) };
+/** Construct the driver for the selected provider from resolved credentials. */
+function createDriver(provider, api) {
+	return DRIVER_FACTORIES[provider](api);
+}
+async function main() {
+	const parsed = parseProviderArg(process.argv.slice(2));
+	if (!parsed.ok) {
+		log(`Fatal: ${parsed.error}`);
+		process.exit(1);
+	}
+	const provider = parsed.provider;
+	const { apiKey, apiUrl } = resolveConfig();
+	const driver = await createDriver(provider, new AgentApiClient({
+		apiKey,
+		apiUrl
+	}));
+	const usable = driver.listAccounts().filter((a) => a.connected).length;
+	if (usable === 0) log(`No ${provider} accounts connected — server will start with ${DISCOVERY_TOOL_NAME} and ${driver.toolPrefix}_check_connection only`);
+	const server = new McpServer({
+		name: "social-mcp-server",
+		version: "0.1.0"
+	});
+	registerTools(server, driver);
+	assertPatternA(buildPatternADescriptors(driver), {
+		selector: "account",
+		exempt: [DISCOVERY_TOOL_NAME]
+	});
+	for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, () => {
+		process.exit(0);
+	});
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	log(`${provider} MCP server running with ${String(usable)} connected account(s) and Pattern A selector enforcement`);
+}
+main().catch((err) => {
+	log(`Fatal: ${err instanceof Error ? err.message : String(err)}`);
+	process.exit(1);
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@alfe.ai/social-mcp",
+  "version": "0.2.0",
+  "description": "Social MCP server — post, engage, and read on connected social accounts (Bluesky today; X / Meta / Threads / LinkedIn / Pinterest / TikTok / Reddit / YouTube on the approval-gated roster) via Alfe Connect credentials (Pattern A multi-account, provider selected via --provider)",
+  "type": "module",
+  "main": "./dist/server.js",
+  "bin": {
+    "social-mcp-server": "./dist/server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.5",
+    "@alfe.ai/agent-api-client": "0.11.2",
+    "@alfe.ai/config": "0.3.0",
+    "@alfe.ai/mcp-bundler": "0.3.2"
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://alfe.ai",
+  "author": "Alfe (https://alfe.ai)",
+  "keywords": [
+    "alfe",
+    "ai-agents",
+    "agent",
+    "llm",
+    "mcp",
+    "model-context-protocol",
+    "social",
+    "bluesky",
+    "atproto"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint ."
+  }
+}