@wezzard/mcp-x-articles 0.0.0-stage → 0.2.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.
@@ -0,0 +1,14 @@
1
+ {
2
+ "name": "mcp-x-articles",
3
+ "description": "The mcp-x-articles Claude Code plugin",
4
+ "owner": {
5
+ "name": "WeZZard"
6
+ },
7
+ "plugins": [
8
+ {
9
+ "name": "mcp-x-articles",
10
+ "source": "./",
11
+ "description": "Publish Markdown files as X Articles with deterministic AST compilation, zero-token media uploads, and macOS Keychain secret storage."
12
+ }
13
+ ]
14
+ }
@@ -0,0 +1,18 @@
1
+ {
2
+ "name": "mcp-x-articles",
3
+ "version": "0.2.0",
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
+ "author": {
6
+ "name": "WeZZard",
7
+ "url": "https://github.com/WeZZard"
8
+ },
9
+ "repository": "https://github.com/WeZZard/mcp-x-articles",
10
+ "license": "MIT",
11
+ "keywords": [
12
+ "x",
13
+ "twitter",
14
+ "articles",
15
+ "markdown",
16
+ "mcp"
17
+ ]
18
+ }
@@ -0,0 +1,11 @@
1
+ {
2
+ "mcpServers": {
3
+ "x_articles": {
4
+ "type": "stdio",
5
+ "command": "node",
6
+ "args": [
7
+ "./dist/server.mjs"
8
+ ]
9
+ }
10
+ }
11
+ }
@@ -0,0 +1,31 @@
1
+ {
2
+ "name": "mcp-x-articles",
3
+ "version": "0.2.0",
4
+ "description": "Publish Markdown files as X Articles via official X API v2.",
5
+ "author": {
6
+ "name": "WeZZard",
7
+ "url": "https://github.com/WeZZard"
8
+ },
9
+ "repository": "https://github.com/WeZZard/mcp-x-articles",
10
+ "license": "MIT",
11
+ "keywords": [
12
+ "x",
13
+ "twitter",
14
+ "articles",
15
+ "markdown",
16
+ "mcp"
17
+ ],
18
+ "skills": "./skills/",
19
+ "mcpServers": "./.codex-plugin/mcp.json",
20
+ "interface": {
21
+ "displayName": "X Articles",
22
+ "shortDescription": "Publish Markdown as X Articles",
23
+ "longDescription": "Deterministic Markdown conversion, zero-token image upload, macOS Keychain secret storage, and two-step human review for X Articles.",
24
+ "developerName": "WeZZard",
25
+ "category": "Productivity",
26
+ "defaultPrompt": [
27
+ "Publish post.md as an X Article draft",
28
+ "Run X Article preflight on index.md"
29
+ ]
30
+ }
31
+ }
@@ -0,0 +1,39 @@
1
+ {
2
+ "$schema": "https://cursor.com/schemas/plugin.schema.json",
3
+ "name": "mcp-x-articles",
4
+ "version": "0.2.0",
5
+ "description": "Publish Markdown files as X Articles via official X API v2.",
6
+ "author": {
7
+ "name": "WeZZard",
8
+ "url": "https://github.com/WeZZard"
9
+ },
10
+ "license": "MIT",
11
+ "logo": "assets/logo.svg",
12
+ "category": "Productivity",
13
+ "skills": "./skills",
14
+ "variables": {
15
+ "type": "object",
16
+ "properties": {
17
+ "X_OAUTH_CONSUMER_KEY": {
18
+ "type": "string",
19
+ "description": "Optional X API Key (leave blank to configure via the local browser Keychain setup card)."
20
+ },
21
+ "X_OAUTH_CONSUMER_SECRET": {
22
+ "type": "string",
23
+ "description": "Optional X API Key Secret (leave blank to configure via the local browser Keychain setup card)."
24
+ }
25
+ }
26
+ },
27
+ "mcpServers": {
28
+ "x-articles": {
29
+ "command": "node",
30
+ "args": [
31
+ "${CURSOR_PLUGIN_ROOT}/dist/server.mjs"
32
+ ],
33
+ "env": {
34
+ "X_OAUTH_CONSUMER_KEY": "${X_OAUTH_CONSUMER_KEY}",
35
+ "X_OAUTH_CONSUMER_SECRET": "${X_OAUTH_CONSUMER_SECRET}"
36
+ }
37
+ }
38
+ }
39
+ }
package/.mcp.json ADDED
@@ -0,0 +1,11 @@
1
+ {
2
+ "mcpServers": {
3
+ "x-articles": {
4
+ "type": "stdio",
5
+ "command": "node",
6
+ "args": [
7
+ "${CLAUDE_PLUGIN_ROOT}/dist/server.mjs"
8
+ ]
9
+ }
10
+ }
11
+ }
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 WeZZard
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,135 @@
1
- # Temporary Holding Version
1
+ # @wezzard/mcp-x-articles
2
2
 
3
- 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.
3
+ Publish a local Markdown file as an [X Article](https://help.x.com/en/using-x/articles) through the official X API v2 Articles endpoints from any Model Context Protocol (MCP) agent.
4
+
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
+ - 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
+ - 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
+ - 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
+ ## Architecture
11
+
12
+ ```mermaid
13
+ flowchart LR
14
+ subgraph Hosts["Agent Runtimes & Plugin Manifests"]
15
+ AGY["Antigravity (plugin.json + mcp_config.json)"]
16
+ CC["Claude Code (.claude-plugin/ + .mcp.json)"]
17
+ CDX["Codex (.codex-plugin/plugin.json + mcp.json)"]
18
+ CUR["Cursor (.cursor-plugin/plugin.json)"]
19
+ PI["pi (package.json + pi-mcp.json)"]
20
+ CD["Claude Desktop / npx (bin: mcp-x-articles)"]
21
+ end
22
+
23
+ subgraph Server["Committed Headless Executable (dist/server.mjs)"]
24
+ T1["x_article_auth_status (Browser Keychain Setup)"]
25
+ T2["x_article_preflight (SHA-256 Token + Scanner)"]
26
+ T3["x_article_create_draft (marked AST + Chunked Upload)"]
27
+ T4["x_article_publish (destructiveHint: true)"]
28
+ end
29
+
30
+ KC["macOS Keychain / 0600 XDG Fallback"]
31
+ XAPI["Official X API v2 (/2/media/upload/* & /2/articles/*)"]
32
+
33
+ Hosts -->|"stdio JSON-RPC"| Server
34
+ Server <--> KC
35
+ Server -->|"OAuth 1.0a HTTPS"| XAPI
36
+ ```
37
+
38
+ ## Prerequisites
39
+
40
+ - 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 OAuth 1.0a (**Read and write** permissions) enabled.
42
+ - For 1-click browser redirect, register `http://127.0.0.1:8976/oauth/callback` in your X Developer App's Callback URLs; if port `8976` is occupied by another local process or not whitelisted in `console.x.com`, the server automatically binds an OS-assigned random port and falls back to X's 7-digit OAuth 1.0a PIN flow.
43
+
44
+ ## Authentication (Zero Terminal Required)
45
+
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
+
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`.
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
+
52
+ ## Install
53
+
54
+ ### Claude Code
55
+
56
+ Add this repository as a marketplace and install the plugin:
57
+
58
+ ```text
59
+ /plugin marketplace add WeZZard/mcp-x-articles
60
+ /plugin install mcp-x-articles@mcp-x-articles
61
+ ```
62
+
63
+ ### Antigravity
64
+
65
+ Clone this repository and symlink it into `~/.gemini/config/plugins/` (no `npm install` is required because `dist/server.mjs` is pre-bundled):
66
+
67
+ ```sh
68
+ git clone https://github.com/WeZZard/mcp-x-articles
69
+ ln -s "$PWD/mcp-x-articles" ~/.gemini/config/plugins/mcp-x-articles
70
+ ```
71
+
72
+ Open `customization://mcp-x-articles` in Antigravity and toggle the plugin on.
73
+
74
+ ### Codex
75
+
76
+ Install this repository through Codex Plugins (`.codex-plugin/plugin.json` loads `./skills/` and `.codex-plugin/mcp.json`), or register via CLI:
77
+
78
+ ```sh
79
+ codex mcp add x-articles -- npx -y @wezzard/mcp-x-articles
80
+ ```
81
+
82
+ ### Cursor
83
+
84
+ Load this repository as a Cursor Plugin (`.cursor-plugin/plugin.json`), or add `npx -y @wezzard/mcp-x-articles` to `~/.cursor/mcp.json`.
85
+
86
+ ### pi
87
+
88
+ Install the npm package (requires `pi-mcp-adapter` or built-in MCP support):
89
+
90
+ ```sh
91
+ pi install npm:@wezzard/mcp-x-articles
92
+ ```
93
+
94
+ ### Claude Desktop (and Other `stdio` MCP Clients)
95
+
96
+ Add `@wezzard/mcp-x-articles` to `claude_desktop_config.json`:
97
+
98
+ ```json
99
+ {
100
+ "mcpServers": {
101
+ "x-articles": {
102
+ "command": "npx",
103
+ "args": ["-y", "@wezzard/mcp-x-articles"]
104
+ }
105
+ }
106
+ }
107
+ ```
108
+
109
+ ## MCP Tools and Prompt
110
+
111
+ | Name | Kind | Purpose |
112
+ |---|---|---|
113
+ | `x_article_auth_status` | Tool (`readOnlyHint`) | Checks credential resolution (`env` -> `macos-keychain` -> `xdg-config`), verifies `/2/users/me`, and launches the local browser Keychain setup + OAuth 1.0a login when `login: true`. |
114
+ | `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
+ | `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
+ | `x_article_publish` | Tool (`destructiveHint`) | Publishes a draft permanently (`POST /2/articles/{article_id}/publish`) and returns the live post URL. |
117
+ | `publish-x-article` | Prompt | Provides a structured user prompt template for clients that surface MCP Prompts. |
118
+
119
+ ## Conversion Rules and API Limits
120
+
121
+ - The converter resolves the article title in order: explicit `title` argument, YAML frontmatter `title`, first `# H1`, or the Markdown file name.
122
+ - Markdown `##` maps to `header-one` and `###+` clamps to `header-two` (X Articles only support two heading levels), fenced code and GFM tables map to native X `markdown` entities, standalone `x.com`/`twitter.com` status URLs map to `post` entities, and only the optional Markdown image `"title"` string in `![alt](src "caption")` maps to a visible image caption.
123
+ - Nested lists flatten to one level and raw HTML blocks drop with explicit entries in `warnings`.
124
+ - The X Articles API exposes only two endpoints—create draft and publish—with no update endpoint and no delete endpoint, so post-draft edits either happen in the X web composer or create a new draft.
125
+
126
+ ## Develop
127
+
128
+ ```sh
129
+ npm install
130
+ npm run check # build dist/server.mjs + tsc typecheck + test suite + tarball & isolation check
131
+ ```
132
+
133
+ ## License
134
+
135
+ MIT
@@ -0,0 +1,11 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" fill="none">
2
+ <rect x="24" y="24" width="208" height="208" rx="44" fill="#161614" stroke="#D86A43" stroke-width="6"/>
3
+ <rect x="58" y="56" width="96" height="128" rx="12" fill="#F4EFE6"/>
4
+ <rect x="74" y="80" width="64" height="8" rx="4" fill="#161614"/>
5
+ <rect x="74" y="100" width="48" height="7" rx="3.5" fill="#D86A43"/>
6
+ <rect x="74" y="118" width="58" height="6" rx="3" fill="#5C5A54"/>
7
+ <rect x="74" y="134" width="52" height="6" rx="3" fill="#5C5A54"/>
8
+ <rect x="74" y="150" width="38" height="6" rx="3" fill="#E5A94C"/>
9
+ <circle cx="168" cy="164" r="40" fill="#D86A43" stroke="#161614" stroke-width="6"/>
10
+ <path d="M151 146H161L169.5 158.2L179.5 146H186L173 162L187 182H177L167.8 168.8L157 182H150.5L164.5 165L151 146Z" fill="#F4EFE6"/>
11
+ </svg>