gobananas-mcp 1.0.9 → 1.0.11

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.
Files changed (2) hide show
  1. package/README.md +117 -30
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -2,31 +2,55 @@
2
2
 
3
3
  MCP server for [Go Bananas](https://gobananasai.com) AI image generation. Connects MCP clients (Claude Desktop, Claude Code, Cursor, VS Code, Codex) to the Go Bananas server.
4
4
 
5
- **42 tools** for image generation, conversational editing, character consistency, product marketing, style presets, and analytics — powered by Google Gemini.
5
+ **47 tools** for image generation, conversational editing, character consistency, product marketing, posters, style presets, model discovery, quota/cost checks, and analytics — powered by Gemini Flash, Gemini Pro, and OpenAI GPT Image 2.
6
+
7
+ ## What's New (v1.0.7)
8
+
9
+ - **Prompt Optimization**: New `enhance_prompt` parameter enriches short prompts with AI-powered visual details (lighting, composition, style) before generation
10
+ - **Timeout Fix**: Fixed MCP SDK 60s timeout causing `-32001` errors on parallel Pro model requests. Now uses 10-minute timeout with progress-based keep-alive.
6
11
 
7
12
  ## Quick Start
8
13
 
9
- ### Claude Desktop / claude.ai (Easiest — Remote Connector)
14
+ ### Auth Modes
15
+
16
+ There are two supported ways to connect:
17
+
18
+ | Mode | Best For | How Auth Works |
19
+ | --------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
20
+ | **Remote HTTP OAuth** | claude.ai connectors, Claude Code, Codex, Cursor/VS Code clients that support remote MCP OAuth | The client connects to `https://gobananasai.com/mcp` and stores OAuth tokens for that URL |
21
+ | **STDIO proxy** | Claude Desktop config files, older editors, Hermes/cloud agents, or clients without remote HTTP OAuth | The client launches `gobananas-mcp`; the proxy reads local `gobananas-cli` OAuth tokens or `GO_BANANAS_API_KEY` |
10
22
 
11
- No installation needed. Works on desktop, web, and mobile:
23
+ Keep only one `go-bananas` entry per client/scope. Logging in with
24
+ `npx -y gobananas-cli auth login` authenticates the STDIO proxy only; it does not authenticate
25
+ a separate direct HTTP config entry.
26
+
27
+ ### Claude Desktop / claude.ai Remote Connector
28
+
29
+ No installation needed when using the hosted connector flow:
12
30
 
13
31
  1. Go to **Settings > Connectors > Add custom connector**
14
32
  2. Enter URL: `https://gobananasai.com/mcp`
15
33
  3. Authenticate with your Go Bananas account
16
34
 
17
- That's it. All 42 tools are available immediately.
35
+ That's it. All 47 tools are available immediately.
18
36
 
19
- ### Claude Code (One Command)
37
+ ### Claude Code (Recommended — Remote HTTP OAuth)
20
38
 
21
39
  ```bash
22
- claude mcp add go-bananas \
23
- -e GO_BANANAS_API_KEY=sk_live_your_api_key \
24
- -e GO_BANANAS_SERVER_URL=https://gobananasai.com \
25
- -e GO_BANANAS_MCP_TRANSPORT=streamable-http \
26
- -- npx -y gobananas-mcp
40
+ claude mcp add --transport http -s user go-bananas https://gobananasai.com/mcp
41
+ ```
42
+
43
+ Then run `/mcp` in Claude Code and authenticate in the browser. This uses Go Bananas OAuth;
44
+ you do not need to paste an API key into your MCP config.
45
+
46
+ ### Codex (Remote HTTP OAuth)
47
+
48
+ ```bash
49
+ codex mcp add go-bananas --url https://gobananasai.com/mcp
50
+ codex mcp login go-bananas
27
51
  ```
28
52
 
29
- Add `-s user` to install for all projects.
53
+ Use `codex mcp get go-bananas` to verify the configured endpoint.
30
54
 
31
55
  ### Universal Install (9+ Clients)
32
56
 
@@ -36,9 +60,20 @@ Works across Claude, Cursor, VS Code, Gemini CLI, and more:
36
60
  npx add-mcp https://gobananasai.com/mcp
37
61
  ```
38
62
 
39
- ### Claude Desktop (Local STDIO)
63
+ ### STDIO Clients / Hermes / Cloud Agents
40
64
 
41
- If you prefer a local proxy instead of the remote connector, add to your config file:
65
+ If your client cannot use remote HTTP MCP connectors, use this local STDIO proxy.
66
+ Run browser login once, then point the client at `gobananas-mcp` without putting an
67
+ API key in the MCP config:
68
+
69
+ ```bash
70
+ npx -y gobananas-cli auth login
71
+ ```
72
+
73
+ This opens Go Bananas in your browser, stores OAuth tokens locally, and the STDIO
74
+ proxy automatically sends/refreshes bearer tokens when connecting upstream.
75
+
76
+ Then add the proxy to your MCP config.
42
77
 
43
78
  - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
44
79
  - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
@@ -50,7 +85,6 @@ If you prefer a local proxy instead of the remote connector, add to your config
50
85
  "command": "npx",
51
86
  "args": ["-y", "gobananas-mcp"],
52
87
  "env": {
53
- "GO_BANANAS_API_KEY": "sk_live_your_api_key",
54
88
  "GO_BANANAS_SERVER_URL": "https://gobananasai.com",
55
89
  "GO_BANANAS_MCP_TRANSPORT": "streamable-http"
56
90
  }
@@ -61,9 +95,27 @@ If you prefer a local proxy instead of the remote connector, add to your config
61
95
 
62
96
  Restart Claude Desktop after saving.
63
97
 
64
- ### Cursor
98
+ For Claude Code STDIO:
65
99
 
66
- Add to `.cursor/mcp.json`:
100
+ ```bash
101
+ claude mcp add -s user go-bananas \
102
+ -e GO_BANANAS_SERVER_URL=https://gobananasai.com \
103
+ -e GO_BANANAS_MCP_TRANSPORT=streamable-http \
104
+ -- npx -y gobananas-mcp
105
+ ```
106
+
107
+ For Codex STDIO:
108
+
109
+ ```bash
110
+ codex mcp add go-bananas \
111
+ --env GO_BANANAS_SERVER_URL=https://gobananasai.com \
112
+ --env GO_BANANAS_MCP_TRANSPORT=streamable-http \
113
+ -- npx -y gobananas-mcp
114
+ ```
115
+
116
+ For headless/cloud environments, run `npx -y gobananas-cli auth login --no-open`
117
+ and open the printed authorization URL in a browser that can reach the local
118
+ callback address. If that is not possible, use the API-key fallback:
67
119
 
68
120
  ```json
69
121
  {
@@ -81,6 +133,39 @@ Add to `.cursor/mcp.json`:
81
133
  }
82
134
  ```
83
135
 
136
+ ### Cursor
137
+
138
+ Prefer remote HTTP OAuth when supported:
139
+
140
+ ```json
141
+ {
142
+ "mcpServers": {
143
+ "go-bananas": {
144
+ "type": "http",
145
+ "url": "https://gobananasai.com/mcp"
146
+ }
147
+ }
148
+ }
149
+ ```
150
+
151
+ Otherwise add the STDIO proxy to `.cursor/mcp.json` after running
152
+ `npx -y gobananas-cli auth login`:
153
+
154
+ ```json
155
+ {
156
+ "mcpServers": {
157
+ "go-bananas": {
158
+ "command": "npx",
159
+ "args": ["-y", "gobananas-mcp"],
160
+ "env": {
161
+ "GO_BANANAS_SERVER_URL": "https://gobananasai.com",
162
+ "GO_BANANAS_MCP_TRANSPORT": "streamable-http"
163
+ }
164
+ }
165
+ }
166
+ }
167
+ ```
168
+
84
169
  ### Global Install
85
170
 
86
171
  ```bash
@@ -91,26 +176,28 @@ Then use `"command": "gobananas-mcp"` without the `args` field.
91
176
 
92
177
  ## What You Can Do
93
178
 
94
- | Category | Tools | Examples |
95
- |----------|-------|---------|
96
- | **Generate** | `generate_image`, `batch_generate` | Create images from text prompts |
97
- | **Edit** | `edit_image`, `continue_editing` | "add clouds", "make it brighter" |
98
- | **Characters** | `create_character`, `generate_with_character` | Consistent characters across scenes |
99
- | **Products** | `create_product_reference`, `generate_with_product` | Marketing images with real products |
100
- | **Styles** | `create_style_preset`, `list_style_presets` | Reusable brand templates |
101
- | **Analytics** | `check_quota`, `get_usage_stats` | Usage tracking and quota management |
179
+ | Category | Tools | Examples |
180
+ | ---------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------ |
181
+ | **Generate** | `generate_image`, `batch_generate` | Create images from text prompts (use `enhance_prompt` for AI-enhanced results) |
182
+ | **Edit** | `edit_image`, `continue_editing` | "add clouds", "make it brighter" |
183
+ | **Characters** | `create_character`, `generate_with_character` | Consistent characters across scenes |
184
+ | **Products** | `create_product_reference`, `generate_with_product` | Marketing images with real products |
185
+ | **Styles** | `create_style_preset`, `list_style_presets` | Reusable brand templates |
186
+ | **Models & Analytics** | `list_models`, `check_quota`, `get_usage_stats` | Capability discovery, cost estimates, quota tracking |
187
+
188
+ Run `list_models` before advanced model choices, and run `check_quota` before large batches, OpenAI high quality, or 2K/4K generations. `check_quota` returns storage/rate/service health plus an approximate provider-cost estimate.
102
189
 
103
190
  ## Environment Variables
104
191
 
105
- | Variable | Default | Description |
106
- |----------|---------|-------------|
107
- | `GO_BANANAS_API_KEY` | — | Your API key (required for STDIO mode) |
108
- | `GO_BANANAS_SERVER_URL` | `https://gobananasai.com` | Server URL |
109
- | `GO_BANANAS_MCP_TRANSPORT` | `streamable-http` | Transport protocol |
192
+ | Variable | Default | Description |
193
+ | -------------------------- | ------------------------- | ------------------------------- |
194
+ | `GO_BANANAS_API_KEY` | — | API-key fallback for STDIO mode |
195
+ | `GO_BANANAS_SERVER_URL` | `https://gobananasai.com` | Server URL |
196
+ | `GO_BANANAS_MCP_TRANSPORT` | `streamable-http` | Transport protocol |
110
197
 
111
198
  ## How It Works
112
199
 
113
- This package re-exports the MCP STDIO proxy from [`gobananas-cli`](https://www.npmjs.com/package/gobananas-cli). The proxy bridges STDIO-based MCP clients to the remote Go Bananas server using Streamable HTTP transport.
200
+ This package re-exports the MCP STDIO proxy from [`gobananas-cli`](https://www.npmjs.com/package/gobananas-cli). The proxy bridges STDIO-based MCP clients to the remote Go Bananas server using Streamable HTTP transport. For clients with remote HTTP MCP support, connect directly to `https://gobananasai.com/mcp` so the client can perform OAuth login and token refresh itself. For STDIO-only clients, run `gobananas auth login` or `gb auth login` once; the proxy will use the saved OAuth tokens and refresh them automatically. If you configure both direct HTTP and STDIO under the same name, authenticate the exact entry your client reports in its MCP status.
114
201
 
115
202
  - **Connect timeout**: 30 seconds
116
203
  - **Request timeout**: 10 minutes (image generation can take 25-55s)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gobananas-mcp",
3
- "version": "1.0.9",
3
+ "version": "1.0.11",
4
4
  "description": "MCP server for Go Bananas AI image generation — use with Claude Desktop, claude.ai, Cursor, Claude Code, VS Code, Codex",
5
5
  "type": "module",
6
6
  "bin": {
@@ -35,6 +35,6 @@
35
35
  "node": ">=18.0.0"
36
36
  },
37
37
  "dependencies": {
38
- "gobananas-cli": "^1.0.4"
38
+ "gobananas-cli": "^1.0.10"
39
39
  }
40
40
  }