W MCP Server (Wishfinity)

1# +W MCP Server (Wishfinity)
2 
3**+W** is a universal "save for later" action for commerce. This MCP server lets AI assistants save any product URL to a user's [Wishfinity](https://wishfinity.com) wishlist with one click.
4 
5Works with **Claude, ChatGPT, Gemini, LangChain, OpenAI Agents SDK**, and any MCP-compatible client.
6 
7[![npm version](https://badge.fury.io/js/wishfinity-mcp-plusw.svg)](https://www.npmjs.com/package/wishfinity-mcp-plusw)
8[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9 
10## What it does
11 
12When an AI recommends a product, it can offer **+W Add to Wishlist**. The user clicks the link, and the product is saved to their Wishfinity account — ready for later purchase or gifting.
13 
14```
15User: "Find me a good espresso machine under $200"
16 
17AI: Here are 3 options...
18    [+W Add to Wishlist] [View on Amazon]
19```
20 
21## Zero-dependency option: /add-wish
22 
23Don't need the full MCP server? The `/add-wish` skill teaches any AI agent the +W pattern using just a URL — no npm, no server, no setup:
24 
25```
26https://wishfinity.com/add?url={any_product_url}
27```
28 
29→ [View the /add-wish skill file](./add-wish/SKILL.md)
30 
31Works with any AI platform. The MCP server below adds richer tool integration, but `/add-wish` is all you need to get started.
32 
33## Quick start
34 
35### Option 1: Local installation (stdio transport)
36 
37Best for Claude Desktop, ChatGPT Desktop, Cursor, VS Code, and local development.
38 
39```bash
40npm install wishfinity-mcp-plusw
41```
42 
43Add to your MCP client configuration:
44 
45```json
46{
47  "mcpServers": {
48    "wishfinity": {
49      "command": "npx",
50      "args": ["wishfinity-mcp-plusw"]
51    }
52  }
53}
54```
55 
56### Option 2: Remote endpoint (HTTP transport)
57 
58Best for server-side agents, LangChain production deployments, and hosted AI applications.
59 
60```
61https://wishfinity-mcp-plusw.wishfinity.workers.dev/mcp
62```
63 
64---
65 
66## Platform Setup Guides
67 
68### Claude Desktop
69 
70Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
71 
72```json
73{
74  "mcpServers": {
75    "wishfinity": {
76      "command": "npx",
77      "args": ["wishfinity-mcp-plusw"]
78    }
79  }
80}
81```
82 
83### ChatGPT Desktop
84 
85When MCP support is available, add to your ChatGPT MCP configuration:
86 
87```json
88{
89  "mcpServers": {
90    "wishfinity": {
91      "command": "npx",
92      "args": ["wishfinity-mcp-plusw"]
93    }
94  }
95}
96```
97 
98### Cursor
99 
100Add to `.cursor/mcp.json` in your project:
101 
102```json
103{
104  "mcpServers": {
105    "wishfinity": {
106      "command": "npx",
107      "args": ["wishfinity-mcp-plusw"]
108    }
109  }
110}
111```
112 
113### LangChain
114 
115```python
116from langchain_mcp_adapters.client import MultiServerMCPClient
117from langchain.agents import create_agent
118 
119async def main():
120    client = MultiServerMCPClient({
121        "wishfinity": {
122            "command": "npx",
123            "args": ["wishfinity-mcp-plusw"],
124            "transport": "stdio",
125        }
126    })
127 
128    tools = await client.get_tools()
129    agent = create_agent("openai:gpt-4", tools)
130 
131    result = await agent.ainvoke({
132        "messages": [{"role": "user", "content": "Find me a coffee maker and save it to my wishlist"}]
133    })
134```
135 
136For production (HTTP transport):
137 
138```python
139client = MultiServerMCPClient({
140    "wishfinity": {
141        "url": "https://wishfinity-mcp-plusw.wishfinity.workers.dev/mcp",
142        "transport": "streamable_http",
143    }
144})
145```
146 
147### OpenAI Agents SDK
148 
149```python
150from agents import Agent, Runner
151from agents.mcp import MCPServerStdio
152 
153async def main():
154    async with MCPServerStdio(
155        name="wishfinity",
156        params={
157            "command": "npx",
158            "args": ["wishfinity-mcp-plusw"],
159        },
160    ) as server:
161        agent = Agent(
162            name="Shopping Assistant",
163            instructions="Help users find products and save them to wishlists.",
164            mcp_servers=[server],
165        )
166 
167        result = await Runner.run(agent, "Find a good gift for a coffee lover and save it")
168        print(result.final_output)
169```
170 
171### Hugging Face Agents
172 
173```python
174from huggingface_hub import Agent
175 
176agent = Agent(
177    model="meta-llama/Llama-3.1-70B-Instruct",
178    mcp_servers=[{
179        "command": "npx",
180        "args": ["wishfinity-mcp-plusw"]
181    }]
182)
183 
184response = agent.run("Find me running shoes under $150 and save to wishlist")
185```
186 
187---
188 
189## How it works
190 
1911. AI calls the `add_to_wishlist` tool with a product URL
1922. MCP server returns a Wishfinity link: `https://wishfinity.com/add?url=...`
1933. User clicks the link → logs in (first time only) → product is saved
1944. User can organize, share, or purchase later
195 
196**No API keys required.** Authentication happens on Wishfinity's website when the user clicks the link.
197 
198---
199 
200## Tool: `add_to_wishlist`
201 
202### Input
203 
204| Parameter | Type | Required | Description |
205| --- | --- | --- | --- |
206| `url` | string | Yes | Product page URL |
207 
208### Output
209 
210| Field | Type | Description |
211| --- | --- | --- |
212| `action_url` | string | Wishfinity link to open in browser |
213| `requires_user_action` | boolean | Always `true` (user must click) |
214| `display_text` | string | Suggested button label |
215 
216### Example
217 
218```json
219// Input
220{ "url": "https://amazon.com/dp/B0EXAMPLE" }
221 
222// Output
223{
224  "action_url": "https://wishfinity.com/add?url=https%3A%2F%2Famazon.com%2Fdp%2FB0EXAMPLE",
225  "requires_user_action": true,
226  "display_text": "Open to add to Wishfinity"
227}
228```
229 
230---
231 
232## When to offer +W
233 
234AI clients should offer +W when:
235 
236- **Explicit requests**: "save for later," "add to wishlist," "bookmark this"
237- **After recommending products**: Proactively offer to save shown items
238- **Indecision moments**: "maybe later," "too expensive right now," "need to think about it"
239- **Gift context**: "for my mom," "birthday gift," "perfect for my friend"
240 
241See [aliases.json](aliases.json) for the full list of trigger phrases.
242 
243---
244 
245## Transports
246 
247| Transport | Use Case | Endpoint |
248|-----------|----------|----------|
249| **stdio** | Local clients (Claude Desktop, Cursor, etc.) | `npx wishfinity-mcp-plusw` |
250| **HTTP** | Remote/server-side agents | `https://wishfinity-mcp-plusw.wishfinity.workers.dev/mcp` |
251 
252---
253 
254## Button kit
255 
256The `/button-kit` folder contains optional UI assets (SVG icon, HTML/CSS snippets) if you want a consistent +W button appearance.
257 
258CDN URLs:
259- Small: `https://cdn.jsdelivr.net/npm/wishfinity-mcp-plusw@latest/button-kit/Wishfinity-Button-Small.svg`
260- Medium: `https://cdn.jsdelivr.net/npm/wishfinity-mcp-plusw@latest/button-kit/Wishfinity-Button-Medium.svg`
261- Large: `https://cdn.jsdelivr.net/npm/wishfinity-mcp-plusw@latest/button-kit/Wishfinity-Button-Large.svg`
262 
263---
264 
265## Documentation
266 
267- [SPEC.md](SPEC.md) — Full technical specification
268- [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md) — How to integrate +W into your UI
269- [CLOUDFLARE_SETUP.md](CLOUDFLARE_SETUP.md) — Deploy your own HTTP endpoint
270- [aliases.json](aliases.json) — Machine-readable trigger phrases
271 
272---
273 
274## Links
275 
276- [Wishfinity](https://wishfinity.com)
277- [MCP Protocol](https://modelcontextprotocol.io)
278- [npm package](https://www.npmjs.com/package/wishfinity-mcp-plusw)
279- [MCP Registry](https://registry.modelcontextprotocol.io)
280 
281---
282 
283## Changelog
284 
285### v1.2.2 (December 24, 2025)
286 
287**Critical Fix:** npx execution for all developers
288 
289- Fixed main module detection to work with npx symlinks
290- Resolves crash when running `npx wishfinity-mcp-plusw`
291- Package now works flawlessly for all npm installations
292 
293### v1.2.1 (December 24, 2025)
294 
295**Critical Fix:** MCP SDK compatibility
296 
297- Updated `@modelcontextprotocol/sdk` dependency to `^1.25.0`
298- Resolves server disconnection with SDK 1.25.1+
299- Compatible with latest MCP SDK versions
300 
301### v1.2.0 (December 23, 2025)
302 
303- Added MCP prompts: `save_for_later`, `shopping_assistant`, `gift_ideas`
304- Added MCP resources: `wishfinity://guide`, `wishfinity://triggers`
305- Enhanced integration capabilities for AI assistants
306 
307---
308 
309## License
310 
311MIT
312