codex-xai-oauth 0.1.0 → 0.2.2

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-xai-oauth",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "Use xAI/Grok OAuth or API-key credentials from Codex through local MCP tools.",
   "author": {
     "name": "ilseoblee"
@@ -13,15 +13,16 @@
   "mcpServers": "./.mcp.json",
   "interface": {
     "displayName": "xAI Grok OAuth",
-    "shortDescription": "Generate with Grok, including images, from Codex.",
-    "longDescription": "Adds local Codex MCP tools for xAI/Grok text, web search, X search, image generation, TTS, video generation, and credential status using OAuth or XAI_API_KEY.",
+    "shortDescription": "Generate with Grok, including artifact-backed images, from Codex.",
+    "longDescription": "Adds local Codex MCP tools for xAI/Grok text, web search, X search, artifact-backed image generation, TTS, video generation, and credential status using OAuth or XAI_API_KEY.",
     "developerName": "ilseoblee",
     "category": "Productivity",
     "capabilities": ["MCP", "Local tools", "Image generation"],
     "defaultPrompt": [
-      "Generate an image with xAI.",
+      "Use xai_image_generate with artifact_dir to generate an image and save local artifacts.",
       "Check my xAI credential status.",
-      "Search the web with Grok."
+      "Search the web with Grok.",
+      "Call the OpenAI-compatible /v1/images/generations proxy with n, resolution, size, and response_format."
     ],
     "brandColor": "#111111"
   }

package/README.md

@@ -13,7 +13,7 @@ Codex plugin that exposes xAI/Grok tools through a local stdio MCP server. It is
 - `xai_tts`
 - `xai_video_generate`
 
-`xai_image_generate` calls xAI `/images/generations`. Default model is `grok-imagine-image`, default response format is `url`, and `resolution` supports `1k` or `2k`.
+`xai_image_generate` calls xAI `/images/generations`. Default model is `grok-imagine-image`, default response format is `url`, and `resolution` supports `1k` or `2k`. Pass `artifact_dir` to save returned URL or `b64_json` images locally and include artifact metadata in the tool result.
 
 ## Unofficial / Use At Your Own Risk
 
@@ -29,6 +29,8 @@ npm run build
 python3 /Users/ilseoblee/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
 ```
 
+Release notes are tracked in [RELEASE_NOTES.md](RELEASE_NOTES.md).
+
 ## Install / Doctor
 
 From a checkout:
@@ -57,6 +59,8 @@ codex-xai-oauth doctor
 
 ## Authentication
 
+The default OAuth store is the shared xAI OIDC file at `~/.grok/auth.json`. This project reads and writes that shared store by default; it does not require a specific Grok CLI build. `CODEX_XAI_OAUTH_AUTH_FILE` is available only when you intentionally want a separate package-specific auth file.
+
 Browser OAuth login:
 
 ```bash
@@ -81,22 +85,42 @@ Status:
 npx codex-xai-oauth status
 ```
 
-OAuth credentials are stored at:
+Generate an image directly from the NPX CLI:
 
-```text
-~/.config/codex-xai-oauth/auth.json
+```bash
+npx codex-xai-oauth image --prompt "minimal blue dot icon" --resolution 2k
+```
+
+Save generated image payloads to local artifacts:
+
+```bash
+npx codex-xai-oauth image --prompt "minimal blue dot icon" --response-format b64_json --artifact-dir .codex-xai-artifacts
 ```
 
-If that file is absent and no custom auth file is configured, the tools also read the Grok CLI OIDC session from:
+OAuth credentials are stored by default as an xAI OIDC entry in:
 
 ```text
 ~/.grok/auth.json
 ```
 
+Legacy package-specific OAuth credentials are still read as a fallback from:
+
+```text
+~/.config/codex-xai-oauth/auth.json
+```
+
+Credential precedence:
+
+- `CODEX_XAI_OAUTH_AUTH_FILE`, when explicitly set.
+- `~/.grok/auth.json`.
+- `~/.config/codex-xai-oauth/auth.json` legacy fallback.
+- `XAI_API_KEY`.
+- Codex model provider `experimental_bearer_token`.
+
 Overrides:
 
-- `CODEX_XAI_OAUTH_AUTH_FILE`: custom OAuth auth JSON path.
-- `CODEX_XAI_OAUTH_GROK_AUTH_FILE`: custom Grok CLI auth JSON path, mainly for tests or nonstandard installs.
+- `CODEX_XAI_OAUTH_AUTH_FILE`: custom package-format OAuth auth JSON path.
+- `CODEX_XAI_OAUTH_GROK_AUTH_FILE`: custom shared xAI OIDC auth JSON path, mainly for tests or nonstandard installs.
 - `XAI_API_KEY`: API-key fallback.
 - `XAI_BASE_URL`: custom xAI-compatible base URL.
 
@@ -121,12 +145,58 @@ The proxy exposes:
 - `/v1/responses`
 - `/v1/images/generations`
 
+`/v1/images/generations` and `/images/generations` forward `prompt`, `model`, `n`, `size`, `resolution`, and `response_format`. Invalid `n`, `resolution`, or `response_format` values return a 400 response before any upstream xAI call.
+
 ## Codex Plugin Surface
 
 - `.codex-plugin/plugin.json` declares the plugin metadata, skill bundle, and MCP config.
 - `.mcp.json` starts the stdio MCP server from `dist/mcp/server.js`.
 - `skills/xai-grok/SKILL.md` tells Codex when to use the tools and how to avoid leaking secrets.
 
+## Built-In Skills
+
+The plugin bundles a general skill plus one dedicated skill for each MCP tool listed in What Works:
+
+- `xai-grok`: umbrella skill for plugin overview, setup orientation, or multi-tool requests when no dedicated `xai_*` skill is a better fit.
+- `xai_status`: dedicated trigger for `xai_status`.
+- `xai_login_instructions`: dedicated trigger for `xai_login_instructions`.
+- `xai_generate_text`: dedicated trigger for `xai_generate_text`.
+- `xai_web_search`: dedicated trigger for `xai_web_search`.
+- `xai_x_search`: dedicated trigger for `xai_x_search`.
+- `xai_image_generate`: dedicated trigger for `xai_image_generate`.
+- `xai_tts`: dedicated trigger for `xai_tts`.
+- `xai_video_generate`: dedicated trigger for `xai_video_generate`.
+
+The dedicated `xai_image_generate` skill lets Codex route natural-language image requests to `xai_image_generate`.
+
+MCP tool arguments:
+
+```json
+{
+  "prompt": "tiny minimalist blue dot icon on white background",
+  "resolution": "2k",
+  "artifact_dir": ".codex-xai-artifacts"
+}
+```
+
+Equivalent CLI:
+
+```bash
+npx codex-xai-oauth image \
+  --prompt "tiny minimalist blue dot icon on white background" \
+  --resolution 2k \
+  --artifact-dir .codex-xai-artifacts
+```
+
+For base64 image payloads saved locally:
+
+```bash
+npx codex-xai-oauth image \
+  --prompt "a cinematic robot reading a book" \
+  --response-format b64_json \
+  --artifact-dir .codex-xai-artifacts
+```
+
 Build before installing or using the MCP server:
 
 ```bash

package/RELEASE_NOTES.md

@@ -0,0 +1,13 @@
+# Release Notes
+
+## 0.2.2
+
+- Changed the default OAuth read/write path to the shared xAI OIDC store at `~/.grok/auth.json`.
+- Kept `CODEX_XAI_OAUTH_AUTH_FILE` as an explicit package-format override and `~/.config/codex-xai-oauth/auth.json` as a legacy fallback.
+- Updated README, MCP login instructions, and bundled skills to explain that `~/.grok/auth.json` is a shared xAI OIDC auth store, not a requirement to use a specific Grok CLI build.
+
+## 0.2.1
+
+- Added dedicated built-in skills for every README-listed MCP tool: `xai_status`, `xai_login_instructions`, `xai_generate_text`, `xai_web_search`, `xai_x_search`, `xai_image_generate`, `xai_tts`, and `xai_video_generate`.
+- Narrowed `xai-grok` to an umbrella skill for plugin overview, setup orientation, and multi-tool requests so specific `xai_*` skills can load only when needed.
+- Updated README skill documentation to match the plugin surface promised by the MCP tool list.