@wezzard/mcp-x-articles 0.2.3 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcp-x-articles",
3
- "version": "0.2.3",
3
+ "version": "0.2.4",
4
4
  "description": "Publish Markdown files as X Articles via official X API v2: deterministic conversion, zero-token media upload, and macOS Keychain secret storage.",
5
5
  "author": {
6
6
  "name": "WeZZard",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcp-x-articles",
3
- "version": "0.2.3",
3
+ "version": "0.2.4",
4
4
  "description": "Publish Markdown files as X Articles via official X API v2.",
5
5
  "author": {
6
6
  "name": "WeZZard",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://cursor.com/schemas/plugin.schema.json",
3
3
  "name": "mcp-x-articles",
4
- "version": "0.2.3",
4
+ "version": "0.2.4",
5
5
  "description": "Publish Markdown files as X Articles via official X API v2.",
6
6
  "author": {
7
7
  "name": "WeZZard",
@@ -16,11 +16,19 @@
16
16
  "properties": {
17
17
  "X_OAUTH_CONSUMER_KEY": {
18
18
  "type": "string",
19
- "description": "Optional X API Key (leave blank to configure via the local browser Keychain setup card)."
19
+ "description": "X API Key (Consumer Key) under 'Consumer Keys' in https://console.x.com -> Apps -> Keys and tokens."
20
20
  },
21
21
  "X_OAUTH_CONSUMER_SECRET": {
22
22
  "type": "string",
23
- "description": "Optional X API Key Secret (leave blank to configure via the local browser Keychain setup card)."
23
+ "description": "X API Key Secret (Consumer Secret) under 'Consumer Keys' in https://console.x.com -> Apps -> Keys and tokens."
24
+ },
25
+ "X_OAUTH_ACCESS_TOKEN": {
26
+ "type": "string",
27
+ "description": "Optional X Access Token under 'Authentication Tokens' in https://console.x.com (leave blank to authorize in browser)."
28
+ },
29
+ "X_OAUTH_ACCESS_TOKEN_SECRET": {
30
+ "type": "string",
31
+ "description": "Optional X Access Token Secret under 'Authentication Tokens' in https://console.x.com (leave blank to authorize in browser)."
24
32
  }
25
33
  }
26
34
  },
@@ -32,7 +40,9 @@
32
40
  ],
33
41
  "env": {
34
42
  "X_OAUTH_CONSUMER_KEY": "${X_OAUTH_CONSUMER_KEY}",
35
- "X_OAUTH_CONSUMER_SECRET": "${X_OAUTH_CONSUMER_SECRET}"
43
+ "X_OAUTH_CONSUMER_SECRET": "${X_OAUTH_CONSUMER_SECRET}",
44
+ "X_OAUTH_ACCESS_TOKEN": "${X_OAUTH_ACCESS_TOKEN}",
45
+ "X_OAUTH_ACCESS_TOKEN_SECRET": "${X_OAUTH_ACCESS_TOKEN_SECRET}"
36
46
  }
37
47
  }
38
48
  }
package/README.md CHANGED
@@ -45,8 +45,8 @@ flowchart LR
45
45
 
46
46
  You can configure authentication in any of three ways, and all six agents share the resulting **macOS Keychain** entry (`@wezzard/mcp-x-articles`):
47
47
 
48
- 1. **In-Browser GUI Setup (Works Inside Every GUI & CLI Agent):** Ask your agent to check auth or create a draft (`x_article_auth_status({ login: true })`). When keys are not yet in macOS Keychain, the server opens a local-only setup card in your browser (`127.0.0.1`), saves your **API Key** and **API Key Secret** straight to macOS Keychain without sending them to the LLM, and continues directly to X OAuth 1.0a consent.
49
- 2. **IDE Plugin Settings Forms:** Antigravity (`customization://mcp-x-articles`) and Cursor (`.cursor-plugin/plugin.json` `variables`) also expose optional GUI fields for `X_OAUTH_CONSUMER_KEY` and `X_OAUTH_CONSUMER_SECRET`.
48
+ 1. **Native IDE Plugin Settings UI (Antigravity & Cursor):** In agents with a native MCP plugin configuration UI — such as Antigravity (`[X Articles](customization://x-articles)`) and Cursor (`.cursor-plugin/plugin.json` `variables`) — configure `X_OAUTH_CONSUMER_KEY`, `X_OAUTH_CONSUMER_SECRET`, and optionally `X_OAUTH_ACCESS_TOKEN` and `X_OAUTH_ACCESS_TOKEN_SECRET` directly in the plugin settings UI. The localhost `/setup` web form is never shown when a native host configuration UI is available.
49
+ 2. **In-Browser GUI Setup Fallback (For Agents Without a Native Plugin Settings UI):** In agents that do not provide a GUI for MCP plugin variables (Claude Code, Codex, pi, Claude Desktop), calling `x_article_auth_status({ login: true })` when keys are not yet in macOS Keychain opens a local-only setup card in your browser (`127.0.0.1`), saves your **API Key** and **API Key Secret** straight to macOS Keychain without sending them to the LLM, and continues directly to X OAuth 1.0a consent.
50
50
  3. **Terminal CLI Setup:** Run `npx -y @wezzard/mcp-x-articles auth` once in a terminal to store your keys in macOS Keychain and authorize in your browser.
51
51
 
52
52
  ## Install
package/dist/server.mjs CHANGED
@@ -7269,6 +7269,37 @@ var CONSUMER_ACCOUNT = "consumer_credentials";
7269
7269
  function keychainServiceName() {
7270
7270
  return (process.env.MCP_X_ARTICLES_KEYCHAIN_SERVICE ?? "").trim() || DEFAULT_KEYCHAIN_SERVICE;
7271
7271
  }
7272
+ function detectHostConfigUi() {
7273
+ const pluginRoot = (process.env.PLUGIN_ROOT ?? "").trim();
7274
+ const pluginData = (process.env.PLUGIN_DATA ?? "").trim();
7275
+ const isAntigravity = process.env.ANTIGRAVITY_VSCODE_HOST === "1" || Boolean((process.env.ANTIGRAVITY_AUTH_SUCCESS_APP ?? "").trim()) || Boolean(pluginRoot) || Boolean(pluginData);
7276
+ if (isAntigravity) {
7277
+ const baseSource = pluginRoot || pluginData;
7278
+ const segments = baseSource.replace(/\/+$/, "").split("/").filter(Boolean);
7279
+ const dir = segments[segments.length - 1] || "x-articles";
7280
+ const configUiUrl = `customization://${dir}`;
7281
+ return {
7282
+ hasNativeConfigUi: true,
7283
+ hostName: "antigravity",
7284
+ configUiUrl,
7285
+ setupInstruction: `Open Antigravity's MCP plugin configuration UI at [X Articles](${configUiUrl}) and configure X_OAUTH_CONSUMER_KEY and X_OAUTH_CONSUMER_SECRET (and optionally X_OAUTH_ACCESS_TOKEN and X_OAUTH_ACCESS_TOKEN_SECRET).`
7286
+ };
7287
+ }
7288
+ if ((process.env.CURSOR_PLUGIN_ROOT ?? "").trim()) {
7289
+ return {
7290
+ hasNativeConfigUi: true,
7291
+ hostName: "cursor",
7292
+ configUiUrl: null,
7293
+ setupInstruction: "Open Cursor's MCP plugin settings UI and configure X_OAUTH_CONSUMER_KEY and X_OAUTH_CONSUMER_SECRET (and optionally X_OAUTH_ACCESS_TOKEN and X_OAUTH_ACCESS_TOKEN_SECRET)."
7294
+ };
7295
+ }
7296
+ return {
7297
+ hasNativeConfigUi: false,
7298
+ hostName: "none",
7299
+ configUiUrl: null,
7300
+ setupInstruction: "Call `x_article_auth_status({ login: true })` to open the local browser setup form (saves API Key and Secret directly to macOS Keychain and completes X OAuth), or run `npx @wezzard/mcp-x-articles auth` in a terminal."
7301
+ };
7302
+ }
7272
7303
  function cleanEnvValue(raw) {
7273
7304
  const val = (raw ?? "").trim();
7274
7305
  if (!val || val.startsWith("${")) return "";
@@ -7370,6 +7401,9 @@ function loadConsumerCredentials() {
7370
7401
  source: "env"
7371
7402
  };
7372
7403
  }
7404
+ if (detectHostConfigUi().hasNativeConfigUi && process.env.MCP_X_ARTICLES_ALLOW_KEYCHAIN_IN_NATIVE_UI !== "1") {
7405
+ return { credentials: null, source: "none" };
7406
+ }
7373
7407
  const kcRaw = keychainRead(CONSUMER_ACCOUNT);
7374
7408
  if (kcRaw) {
7375
7409
  try {
@@ -7714,6 +7748,12 @@ async function runInteractiveSetupAndOAuth1Flow(options) {
7714
7748
  const csrfSecret = randomBytes(16).toString("hex");
7715
7749
  let creds = options.existingCredentials;
7716
7750
  let credSource = options.existingCredentialSource;
7751
+ const hostUi = detectHostConfigUi();
7752
+ if (!creds && hostUi.hasNativeConfigUi) {
7753
+ throw new Error(
7754
+ `Missing X OAuth Consumer Key and Secret. The localhost web setup form is only used when the host agent has no native configuration UI. ${hostUi.setupInstruction}`
7755
+ );
7756
+ }
7717
7757
  let activeReqToken = "";
7718
7758
  let activeReqSecret = "";
7719
7759
  let useOobMode = false;
@@ -19511,14 +19551,16 @@ async function ensureAuthenticatedSession(options) {
19511
19551
  }
19512
19552
  }
19513
19553
  if (!credentials || !tokens) {
19554
+ const hostUi = detectHostConfigUi();
19555
+ if (!credentials && hostUi.hasNativeConfigUi) {
19556
+ throw new Error(`Missing X OAuth Consumer Key and Secret. ${hostUi.setupInstruction}`);
19557
+ }
19514
19558
  if (!options.allowInteractiveLogin) {
19515
19559
  if (!credentials) {
19516
- throw new Error(
19517
- "Missing X OAuth Consumer Key and Secret. Call `x_article_auth_status({ login: true })` to open the local browser Keychain setup page, or run `npx @wezzard/mcp-x-articles auth`."
19518
- );
19560
+ throw new Error(`Missing X OAuth Consumer Key and Secret. ${hostUi.setupInstruction}`);
19519
19561
  }
19520
19562
  throw new Error(
19521
- "No cached OAuth 1.0a user token found. Call `x_article_auth_status({ login: true })` or run `npx @wezzard/mcp-x-articles auth` to authorize in your browser."
19563
+ hostUi.hasNativeConfigUi ? `No user OAuth 1.0a token is configured yet. Either configure X_OAUTH_ACCESS_TOKEN and X_OAUTH_ACCESS_TOKEN_SECRET in ${hostUi.configUiUrl ? `[X Articles](${hostUi.configUiUrl})` : "your host's MCP plugin configuration UI"}, or call \`x_article_auth_status({ login: true })\` to authorize in your browser.` : "No cached OAuth 1.0a user token found. Call `x_article_auth_status({ login: true })` or run `npx @wezzard/mcp-x-articles auth` to authorize in your browser."
19522
19564
  );
19523
19565
  }
19524
19566
  const interactive = await runInteractiveSetupAndOAuth1Flow({
@@ -19715,7 +19757,7 @@ async function publishXArticle(options) {
19715
19757
 
19716
19758
  // src/server.ts
19717
19759
  var PACKAGE_NAME = "@wezzard/mcp-x-articles";
19718
- var PACKAGE_VERSION = "0.2.3";
19760
+ var PACKAGE_VERSION = "0.2.4";
19719
19761
  var MAX_INLINE_PREVIEW_BYTES = 5 * 1024 * 1024;
19720
19762
  var PREVIEWABLE_MIMES = /* @__PURE__ */ new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
19721
19763
  var SERVER_INSTRUCTIONS = [
@@ -19936,14 +19978,19 @@ function createMcpServer() {
19936
19978
  if (name === "x_article_auth_status") {
19937
19979
  const login = Boolean(args.login);
19938
19980
  const verify = args.verify !== false;
19981
+ const hostUi = detectHostConfigUi();
19939
19982
  const { credentials, source: credentialSource } = loadConsumerCredentials();
19940
- if (!credentials && !login) {
19941
- return jsonToolResult({
19942
- configured: false,
19943
- credential_source: "none",
19944
- token_cached: false,
19945
- setup_hint: "Call `x_article_auth_status({ login: true })` to open the local browser setup form (saves API Key and Secret directly to macOS Keychain and completes X OAuth), or run `npx @wezzard/mcp-x-articles auth` in a terminal."
19946
- });
19983
+ if (!credentials) {
19984
+ if (hostUi.hasNativeConfigUi || !login) {
19985
+ return jsonToolResult({
19986
+ configured: false,
19987
+ credential_source: "none",
19988
+ token_cached: false,
19989
+ has_native_config_ui: hostUi.hasNativeConfigUi,
19990
+ native_config_ui_url: hostUi.configUiUrl,
19991
+ setup_hint: hostUi.setupInstruction
19992
+ });
19993
+ }
19947
19994
  }
19948
19995
  if (credentials) {
19949
19996
  const cached2 = loadUserOAuthTokens(credentials.consumerKey);
@@ -19953,7 +20000,9 @@ function createMcpServer() {
19953
20000
  credential_source: credentialSource,
19954
20001
  token_cached: false,
19955
20002
  token_source: "none",
19956
- setup_hint: "Consumer credentials found, but no user OAuth 1.0a token is cached yet. Call `x_article_auth_status({ login: true })` to authorize in your browser."
20003
+ has_native_config_ui: hostUi.hasNativeConfigUi,
20004
+ native_config_ui_url: hostUi.configUiUrl,
20005
+ setup_hint: hostUi.hasNativeConfigUi ? `Consumer credentials found (${credentialSource}), but no user OAuth 1.0a Access Token is configured yet. Either configure X_OAUTH_ACCESS_TOKEN and X_OAUTH_ACCESS_TOKEN_SECRET in ${hostUi.configUiUrl ? `[X Articles](${hostUi.configUiUrl})` : "your host's MCP plugin configuration UI"}, or call \`x_article_auth_status({ login: true })\` to authorize your account on x.com in your browser.` : "Consumer credentials found, but no user OAuth 1.0a token is cached yet. Call `x_article_auth_status({ login: true })` to authorize in your browser."
19957
20006
  });
19958
20007
  }
19959
20008
  }
@@ -19966,6 +20015,8 @@ function createMcpServer() {
19966
20015
  credential_source: session.credentialSource,
19967
20016
  token_cached: true,
19968
20017
  token_source: session.tokenSource,
20018
+ has_native_config_ui: hostUi.hasNativeConfigUi,
20019
+ native_config_ui_url: hostUi.configUiUrl,
19969
20020
  verified: verify,
19970
20021
  authenticated_user: session.user ?? null
19971
20022
  });
@@ -20318,6 +20369,7 @@ export {
20318
20369
  consumerKeyId,
20319
20370
  convertMarkdownFile,
20320
20371
  createMcpServer,
20372
+ detectHostConfigUi,
20321
20373
  extractMarkdownImageSrcs,
20322
20374
  keychainServiceName,
20323
20375
  loadConsumerCredentials,
package/mcp_config.json CHANGED
@@ -8,18 +8,30 @@
8
8
  "cwd": ".",
9
9
  "env": {
10
10
  "X_OAUTH_CONSUMER_KEY": "${X_OAUTH_CONSUMER_KEY}",
11
- "X_OAUTH_CONSUMER_SECRET": "${X_OAUTH_CONSUMER_SECRET}"
11
+ "X_OAUTH_CONSUMER_SECRET": "${X_OAUTH_CONSUMER_SECRET}",
12
+ "X_OAUTH_ACCESS_TOKEN": "${X_OAUTH_ACCESS_TOKEN}",
13
+ "X_OAUTH_ACCESS_TOKEN_SECRET": "${X_OAUTH_ACCESS_TOKEN_SECRET}"
12
14
  },
13
15
  "variables": [
14
16
  {
15
17
  "name": "X_OAUTH_CONSUMER_KEY",
16
- "title": "X OAuth Consumer Key (Optional — leave blank to use Browser Setup / macOS Keychain)",
17
- "description": "API Key (Consumer Key) from https://console.x.com -> Apps -> Keys and tokens."
18
+ "title": "X API Key (Consumer Key)",
19
+ "description": "API Key under 'Consumer Keys' in https://console.x.com -> Apps -> Keys and tokens."
18
20
  },
19
21
  {
20
22
  "name": "X_OAUTH_CONSUMER_SECRET",
21
- "title": "X OAuth Consumer Secret (Optional — leave blank to use Browser Setup / macOS Keychain)",
22
- "description": "API Key Secret (Consumer Secret) from https://console.x.com -> Apps -> Keys and tokens."
23
+ "title": "X API Key Secret (Consumer Secret)",
24
+ "description": "API Key Secret under 'Consumer Keys' in https://console.x.com -> Apps -> Keys and tokens."
25
+ },
26
+ {
27
+ "name": "X_OAUTH_ACCESS_TOKEN",
28
+ "title": "X Access Token (Optional — leave blank to authorize in browser)",
29
+ "description": "Access Token with Read and Write permissions under 'Authentication Tokens' in https://console.x.com -> Apps -> Keys and tokens."
30
+ },
31
+ {
32
+ "name": "X_OAUTH_ACCESS_TOKEN_SECRET",
33
+ "title": "X Access Token Secret (Optional — leave blank to authorize in browser)",
34
+ "description": "Access Token Secret with Read and Write permissions under 'Authentication Tokens' in https://console.x.com -> Apps -> Keys and tokens."
23
35
  }
24
36
  ]
25
37
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wezzard/mcp-x-articles",
3
- "version": "0.2.3",
3
+ "version": "0.2.4",
4
4
  "type": "module",
5
5
  "description": "MCP server and multi-agent plugin for publishing Markdown files as X Articles via the official X API v2 Articles endpoints: deterministic Markdown conversion, zero-token media upload, macOS Keychain secret storage, and two-step human review.",
6
6
  "license": "MIT",
package/pi-mcp.json CHANGED
@@ -1 +1 @@
1
- {"mcpServers":{"x-articles":{"command":"npx","args":["-y","@wezzard/mcp-x-articles@0.2.3"],"lifecycle":"lazy","directTools":true,"toolPrefix":"none"}}}
1
+ {"mcpServers":{"x-articles":{"command":"npx","args":["-y","@wezzard/mcp-x-articles@0.2.4"],"lifecycle":"lazy","directTools":true,"toolPrefix":"none"}}}
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "mcp-x-articles",
3
3
  "displayName": "X Articles",
4
- "version": "0.2.3",
4
+ "version": "0.2.4",
5
5
  "description": "Publish Markdown files as X Articles via official X API v2: deterministic conversion, zero-token image upload, macOS Keychain secret storage, and two-step human review.",
6
6
  "logo": "assets/logo.svg",
7
7
  "author": {
@@ -7,7 +7,9 @@ description: Publish a local Markdown file as an X Article via @wezzard/mcp-x-ar
7
7
 
8
8
  Publish a Markdown file as an X Article through the `@wezzard/mcp-x-articles` MCP tools.
9
9
 
10
- 1. Call `x_article_auth_status` if authentication is unverified; if credentials or user tokens are missing, call `x_article_auth_status({ login: true })` to open the local browser setup card (which saves X API keys directly to macOS Keychain and completes X OAuth 1.0a consent without exposing secrets to chat).
10
+ 1. Call `x_article_auth_status` if authentication is unverified:
11
+ - If the host agent has a native MCP plugin configuration UI (`has_native_config_ui: true`, e.g. Antigravity `[X Articles](customization://x-articles)` or Cursor) and credentials are not yet configured, **do not** open the localhost `/setup` web UI; instead, give the user the `native_config_ui_url` link (`[X Articles](customization://x-articles)`) so they can configure their API Key, API Key Secret, and optional Access Token / Access Token Secret in the host's plugin settings UI.
12
+ - Only call `x_article_auth_status({ login: true })` when `has_native_config_ui` is `false` (to open the fallback local browser `/setup` card for agents without a native plugin config UI), or when `configured: true` and `token_cached: false` and the user wants to authorize their user token on `x.com` instead of entering `X_OAUTH_ACCESS_TOKEN` and `X_OAUTH_ACCESS_TOKEN_SECRET` in the plugin UI.
11
13
  2. Call `x_article_preflight({ markdown_path, cover_image_path })` first, and visually inspect every image in `images_for_visual_review` for live credentials, financial balances, account IDs, email addresses, real names, or private file paths.
12
14
  3. **Checkpoint 1:** Whenever preflight reports text `findings`, visual sensitivities, or conversion `warnings`, ask the user with your dedicated ask-user-question tool (or directly in conversation) to rule on each item before uploading anything to X.
13
15
  4. Call `x_article_create_draft({ markdown_path, preflight_token, cover_image_path })` and share the returned `editor_url` (`https://x.com/compose/articles/edit/<article_id>`).