@wezzard/mcp-x-articles 0.2.4 → 0.3.0
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.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/.cursor-plugin/plugin.json +10 -15
- package/README.md +12 -10
- package/dist/server.mjs +928 -601
- package/mcp_config.json +12 -18
- package/package.json +1 -1
- package/pi-mcp.json +1 -1
- package/plugin.json +1 -1
- package/skills/x-articles/SKILL.md +3 -3
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mcp-x-articles",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
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,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://cursor.com/schemas/plugin.schema.json",
|
|
3
3
|
"name": "mcp-x-articles",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.3.0",
|
|
5
5
|
"description": "Publish Markdown files as X Articles via official X API v2.",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "WeZZard",
|
|
@@ -14,21 +14,17 @@
|
|
|
14
14
|
"variables": {
|
|
15
15
|
"type": "object",
|
|
16
16
|
"properties": {
|
|
17
|
-
"
|
|
17
|
+
"X_OAUTH2_CLIENT_ID": {
|
|
18
18
|
"type": "string",
|
|
19
|
-
"description": "X
|
|
19
|
+
"description": "X OAuth 2.0 Client ID under 'OAuth 2.0 Keys' in https://console.x.com -> Apps -> Keys and tokens."
|
|
20
20
|
},
|
|
21
|
-
"
|
|
21
|
+
"X_OAUTH2_CLIENT_SECRET": {
|
|
22
22
|
"type": "string",
|
|
23
|
-
"description": "X
|
|
23
|
+
"description": "Optional X OAuth 2.0 Client Secret under 'OAuth 2.0 Keys' in https://console.x.com -> Apps -> Keys and tokens (for confidential clients)."
|
|
24
24
|
},
|
|
25
|
-
"
|
|
25
|
+
"X_OAUTH2_REFRESH_TOKEN": {
|
|
26
26
|
"type": "string",
|
|
27
|
-
"description": "Optional
|
|
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)."
|
|
27
|
+
"description": "Optional long-term OAuth 2.0 Refresh Token from 'OAuth 2.0 Keys -> Access Token -> Generate' in https://console.x.com (leave blank to authorize via browser PKCE)."
|
|
32
28
|
}
|
|
33
29
|
}
|
|
34
30
|
},
|
|
@@ -39,10 +35,9 @@
|
|
|
39
35
|
"${CURSOR_PLUGIN_ROOT}/dist/server.mjs"
|
|
40
36
|
],
|
|
41
37
|
"env": {
|
|
42
|
-
"
|
|
43
|
-
"
|
|
44
|
-
"
|
|
45
|
-
"X_OAUTH_ACCESS_TOKEN_SECRET": "${X_OAUTH_ACCESS_TOKEN_SECRET}"
|
|
38
|
+
"X_OAUTH2_CLIENT_ID": "${X_OAUTH2_CLIENT_ID}",
|
|
39
|
+
"X_OAUTH2_CLIENT_SECRET": "${X_OAUTH2_CLIENT_SECRET}",
|
|
40
|
+
"X_OAUTH2_REFRESH_TOKEN": "${X_OAUTH2_REFRESH_TOKEN}"
|
|
46
41
|
}
|
|
47
42
|
}
|
|
48
43
|
}
|
package/README.md
CHANGED
|
@@ -4,6 +4,7 @@ Publish a local Markdown file as an [X Article](https://help.x.com/en/using-x/ar
|
|
|
4
4
|
|
|
5
5
|
- A deterministic compiler (`marked`) converts Markdown into X's Draft.js `content_state` in memory with UTF-16 code unit offsets, eliminating model-generated JSON and offset errors.
|
|
6
6
|
- Local and remote images stream directly from the Node.js MCP server to X's chunked media endpoints so base64 bytes never enter the LLM context window.
|
|
7
|
+
- OAuth 2.0 User Context (`Authorization: Bearer`) with PKCE (`S256`) and automatic long-term rotating `offline.access` refresh tokens backed by a cross-process lock and macOS Keychain persistence.
|
|
7
8
|
- Two human checkpoints guard every run: a pre-flight secret and degradation check before uploading bytes to X, and an explicit approval step after draft creation before irreversible publishing.
|
|
8
9
|
- One self-contained, pre-bundled Node.js executable (`dist/server.mjs`) powers five native agent plugin bundles (**Antigravity**, **Claude Code**, **Codex**, **Cursor**, and **pi**) as well as `npx` for **Claude Desktop**.
|
|
9
10
|
|
|
@@ -21,33 +22,34 @@ flowchart LR
|
|
|
21
22
|
end
|
|
22
23
|
|
|
23
24
|
subgraph Server["Committed Headless Executable (dist/server.mjs)"]
|
|
24
|
-
T1["x_article_auth_status (
|
|
25
|
+
T1["x_article_auth_status (OAuth 2.0 PKCE & Refresh)"]
|
|
25
26
|
T2["x_article_preflight (SHA-256 Token + Scanner)"]
|
|
26
27
|
T3["x_article_create_draft (marked AST + Chunked Upload)"]
|
|
27
28
|
T4["x_article_publish (destructiveHint: true)"]
|
|
28
29
|
end
|
|
29
30
|
|
|
30
31
|
KC["macOS Keychain / 0600 XDG Fallback"]
|
|
31
|
-
XAPI["Official X API v2 (/2/media/upload/* & /2/articles/*)"]
|
|
32
|
+
XAPI["Official X API v2 (/2/oauth2/token, /2/media/upload/* & /2/articles/*)"]
|
|
32
33
|
|
|
33
34
|
Hosts -->|"stdio JSON-RPC"| Server
|
|
34
35
|
Server <--> KC
|
|
35
|
-
Server -->|"OAuth
|
|
36
|
+
Server -->|"OAuth 2.0 Bearer + Auto-Refresh"| XAPI
|
|
36
37
|
```
|
|
37
38
|
|
|
38
39
|
## Prerequisites
|
|
39
40
|
|
|
40
41
|
- You need Node.js `>= 20` on your machine.
|
|
41
|
-
- You need an [X Developer](https://console.x.com) application with pay-per-use API credits and
|
|
42
|
-
-
|
|
42
|
+
- You need an [X Developer](https://console.x.com) application with pay-per-use API credits and **User authentication settings** configured (**Read and write** permissions; type **Web App, Automated App or Bot** for confidential clients with `Client Secret`, or **Native App** for public PKCE clients).
|
|
43
|
+
- Required OAuth 2.0 scopes (requested automatically in PKCE login): `tweet.read tweet.write users.read media.write offline.access`.
|
|
44
|
+
- For 1-click browser PKCE redirect, register `http://127.0.0.1:8976/oauth/callback` in your X Developer App's Callback URIs (or skip callback registration entirely by clicking **Generate** under `OAuth 2.0 Keys -> Access Token` in `console.x.com` and pasting the Refresh Token).
|
|
43
45
|
|
|
44
46
|
## Authentication (Zero Terminal Required)
|
|
45
47
|
|
|
46
|
-
You can configure authentication in any of three ways, and all six agents share
|
|
48
|
+
You can configure authentication in any of three ways, and all six agents share rotating OAuth 2.0 refresh tokens via **macOS Keychain** (`@wezzard/mcp-x-articles`, with `0600` XDG fallback):
|
|
47
49
|
|
|
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 `
|
|
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 **
|
|
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
|
|
50
|
+
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_OAUTH2_CLIENT_ID`, optional `X_OAUTH2_CLIENT_SECRET`, and optionally `X_OAUTH2_REFRESH_TOKEN` (from `console.x.com` → `OAuth 2.0 Keys` → `Access Token` → `Generate`) directly in the plugin settings UI. Once bootstrapped, rotated single-use refresh tokens are persisted safely in macOS Keychain so your original seed token is never reused. The localhost `/setup` web form is never shown when a native host configuration UI is available.
|
|
51
|
+
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 **Client ID** and optional **Client Secret** (or optional **Refresh Token**) straight to macOS Keychain without sending them to the LLM, and completes X OAuth 2.0 PKCE (`S256`) consent with `offline.access`.
|
|
52
|
+
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 via Refresh Token or browser PKCE.
|
|
51
53
|
|
|
52
54
|
## Install
|
|
53
55
|
|
|
@@ -110,7 +112,7 @@ Add `@wezzard/mcp-x-articles` to `claude_desktop_config.json`:
|
|
|
110
112
|
|
|
111
113
|
| Name | Kind | Purpose |
|
|
112
114
|
|---|---|---|
|
|
113
|
-
| `x_article_auth_status` | Tool (`readOnlyHint`) | Checks credential resolution (`env` -> `macos-keychain` -> `xdg-config`), verifies `/2/users/me`, and launches
|
|
115
|
+
| `x_article_auth_status` | Tool (`readOnlyHint`) | Checks OAuth 2.0 credential resolution (`env` -> `macos-keychain` -> `xdg-config`), proactively refreshes rotating `offline.access` tokens under a cross-process lock, verifies `/2/users/me`, and launches OAuth 2.0 PKCE browser consent when `login: true`. |
|
|
114
116
|
| `x_article_preflight` | Tool (`readOnlyHint`) | Scans Markdown text for secrets and PII, dry-runs `marked` conversion to list lossy warnings, attaches local images for visual review, and issues a SHA-256 `preflight_token`. |
|
|
115
117
|
| `x_article_create_draft` | Tool (`openWorldHint`) | Verifies `preflight_token` against live disk hashes, uploads inline and cover images in 2.5 MB chunks, compiles UTF-16 `content_state` in memory, and creates a reversible X draft. |
|
|
116
118
|
| `x_article_publish` | Tool (`destructiveHint`) | Publishes a draft permanently (`POST /2/articles/{article_id}/publish`) and returns the live post URL. |
|