Skip to content

Commit d2bb2e3

Browse files
RavaniRoshanqwencoder
RavaniRoshan
and
qwencoder
committed
feat: add Claude Desktop Extension (.mcpb) support
- Add manifest.json for .mcpb extension packaging - Add build-extension.sh/bat scripts to build .mcpb file - Add EXTENSION_GUIDE.md with complete submission instructions - Update README to show Claude Desktop Extension as Option 1 - Extension will appear in Claude's built-in Extensions directory - Same distribution method as Desktop Commander Ready to: 1. Build winscript.mcpb with build-extension.bat 2. Test locally in Claude Desktop 3. Submit to Anthropic for curated directory approval Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
1 parent 539d354 commit d2bb2e3

5 files changed

Lines changed: 558 additions & 6 deletions

File tree

‎EXTENSION_GUIDE.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# WinScript - Claude Desktop Extension Guide
2+
3+
How to build, install, and submit WinScript to appear in Claude Desktop's built-in Extensions directory.
4+
5+
---
6+
7+
## What is a Claude Desktop Extension?
8+
9+
A **Claude Desktop Extension** (`.mcpb` file) is a packaged MCP server that users can install with one click in Claude Desktop. It's like a browser extension for Claude.
10+
11+
**The flow:**
12+
```
13+
Developer builds .mcpb → Submits to Anthropic → After review → Appears in Claude's Extensions directory → Users install with 1 click
14+
```
15+
16+
**This is how Desktop Commander and other popular connectors appear in Claude Desktop.**
17+
18+
---
19+
20+
## Quick Start
21+
22+
### 1. Build the Extension
23+
24+
**Windows:**
25+
```bash
26+
# Double-click build-extension.bat
27+
# or
28+
build-extension.bat
29+
```
30+
31+
**Linux/Mac:**
32+
```bash
33+
chmod +x build-extension.sh
34+
./build-extension.sh
35+
```
36+
37+
**Output:** `winscript.mcpb`
38+
39+
### 2. Test Locally
40+
41+
```bash
42+
# Double-click the .mcpb file
43+
# Claude Desktop opens → review → install
44+
45+
# Or drag into Claude Desktop:
46+
# Settings → Extensions → Drag winscript.mcpb onto window
47+
```
48+
49+
### 3. Submit to Anthropic
50+
51+
1. Go to: **https://console.anthropic.com** (or submission form)
52+
2. Submit your `.mcpb` file
53+
3. Wait for review (security + quality check)
54+
4. After approval → appears in Claude's Extensions directory
55+
56+
---
57+
58+
## How Users Install WinScript
59+
60+
### After Approval (In Claude Desktop)
61+
62+
1. Open Claude Desktop
63+
2. Go to **Settings → Extensions**
64+
3. Search for **"WinScript"**
65+
4. Click **Install**
66+
5. Wait ~30 seconds for 59 tools to load
67+
6. Done!
68+
69+
### Manual Install (Before Approval)
70+
71+
1. Download `winscript.mcpb` from GitHub releases
72+
2. Double-click the file
73+
3. Claude Desktop opens it
74+
4. Review permissions → **Install**
75+
5. Done!
76+
77+
---
78+
79+
## Extension Structure
80+
81+
```
82+
winscript.mcpb (ZIP archive)
83+
├── manifest.json ← Extension metadata and config
84+
├── icon.png ← Extension icon (512x512)
85+
└── server/ ← MCP server code
86+
├── winscript-server.py ← Entry point
87+
├── requirements.txt ← Python dependencies
88+
└── winscript/ ← Full server codebase
89+
├── __init__.py
90+
├── server.py
91+
├── tools/
92+
├── core/
93+
└── adapters/
94+
```
95+
96+
---
97+
98+
## manifest.json Explained
99+
100+
```json
101+
{
102+
"manifest_version": "0.3",
103+
"name": "winscript",
104+
"display_name": "WinScript",
105+
"version": "0.1.0",
106+
"description": "AppleScript for Windows. Control any Windows app from Claude.",
107+
"author": {
108+
"name": "Roshan Ravani",
109+
"email": "roshan@example.com"
110+
},
111+
"server": {
112+
"type": "python",
113+
"entry_point": "server/winscript-server.py",
114+
"mcp_config": {
115+
"command": "${server.python}",
116+
"args": ["${__dirname}/server/winscript-server.py"]
117+
}
118+
},
119+
"compatibility": {
120+
"platforms": ["win32"],
121+
"runtimes": {
122+
"python": ">=3.10"
123+
}
124+
}
125+
}
126+
```
127+
128+
**Key fields:**
129+
- `server.type`: `"python"` tells Claude to use Python runtime
130+
- `server.entry_point`: Path to server launcher
131+
- `${__dirname}`: Resolves to extension install directory
132+
- `${server.python}`: Uses Claude's bundled Python
133+
134+
---
135+
136+
## Requirements for Submission
137+
138+
Anthropic reviews extensions for:
139+
140+
### ✅ Must Have
141+
- Valid `manifest.json` with all required fields
142+
- Working `.mcpb` package
143+
- Clear description of functionality
144+
- Privacy policy (if handling user data)
145+
- MIT/Apache/open source license
146+
147+
### ✅ WinScript Meets
148+
- ✅ Valid manifest (created)
149+
- ✅ Working server (59 tools tested)
150+
- ✅ Clear description (written)
151+
- ✅ MIT license (included)
152+
- ✅ Privacy: all data stays local (user's machine)
153+
154+
### 📝 Recommended
155+
- Icon (512x512 PNG) - **Need to create**
156+
- Screenshots of functionality - **Optional**
157+
- Long description with examples - **Included**
158+
- Keywords for search - **Included**
159+
160+
---
161+
162+
## Build Process Details
163+
164+
### Step 1: Install mcpb CLI
165+
166+
```bash
167+
npm install -g @anthropic-ai/mcpb
168+
```
169+
170+
### Step 2: Prepare Bundle
171+
172+
The build script does this automatically:
173+
1. Creates `extension-build/server/` directory
174+
2. Copies `winscript/` package
175+
3. Copies `winscript-server.py` launcher
176+
4. Copies `manifest.json`
177+
5. Copies `icon.png` (if exists)
178+
179+
### Step 3: Pack
180+
181+
```bash
182+
cd extension-build
183+
mcpb pack
184+
# Output: winscript.mcpb
185+
```
186+
187+
### Step 4: Test
188+
189+
```bash
190+
# Double-click winscript.mcpb
191+
# Claude Desktop should open it
192+
# Review permissions → Install
193+
# Check that 59 tools appear
194+
```
195+
196+
### Step 5: Submit
197+
198+
Submit to Anthropic for inclusion in the curated directory.
199+
200+
---
201+
202+
## What Happens After Submission
203+
204+
1. **Review** (1-2 weeks): Anthropic checks security, quality, functionality
205+
2. **Approval**: Extension added to curated directory
206+
3. **Discovery**: Users can search "WinScript" in Claude Desktop → Settings → Extensions
207+
4. **Install**: One-click install, no technical knowledge needed
208+
5. **Updates**: Future `.mcpb` versions can be published for updates
209+
210+
---
211+
212+
## Comparison: Desktop Commander vs WinScript
213+
214+
| Feature | Desktop Commander | WinScript |
215+
|---------|------------------|-----------|
216+
| **Domain** | Terminal + filesystem | Full Windows automation |
217+
| **Tools** | 26 | 59 |
218+
| **Protocol** | MCP | MCP |
219+
| **Extension** | `.mcpb` | `.mcpb` (ready to build) |
220+
| **Install** | 1-click in Claude | 1-click after approval |
221+
| **Runtime** | Node.js | Python |
222+
223+
**WinScript complements Desktop Commander:**
224+
- Desktop Commander: file system + terminal
225+
- WinScript: UI automation + Office apps + workflows
226+
227+
**Together: Complete Windows automation.**
228+
229+
---
230+
231+
## Troubleshooting
232+
233+
### mcpb pack fails
234+
235+
```bash
236+
# Check manifest syntax
237+
python -c "import json; json.load(open('manifest.json'))"
238+
239+
# Check mcpb version
240+
mcpb --version
241+
```
242+
243+
### Extension doesn't appear in Claude
244+
245+
1. Check Claude Desktop is updated (Extensions supported in recent versions)
246+
2. Check `.mcpb` was created successfully
247+
3. Try dragging `.mcpb` into Claude Desktop manually
248+
249+
### Server won't start after install
250+
251+
1. Check Python 3.10+ is available
252+
2. Check `requirements.txt` dependencies install
253+
3. Look at Claude Desktop logs for errors
254+
255+
---
256+
257+
## Next Steps
258+
259+
### Immediate
260+
1. [ ] Create `icon.png` (512x512) - use the ASCII art logo
261+
2. [ ] Test `.mcpb` build locally
262+
3. [ ] Test `.mcpb` install in Claude Desktop
263+
4. [ ] Submit to Anthropic
264+
265+
### Long-term
266+
1. [ ] Get approved → appears in Extensions directory
267+
2. [ ] Promote on social media
268+
3. [ ] Gather user feedback
269+
4. [ ] Publish updates via new `.mcpb` versions
270+
271+
---
272+
273+
**Built by Roshan Ravani** · MIT License · April 2026

‎README.md‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,19 @@ Not a wrapper. Not a toy. Infrastructure.
3535

3636
## Quick Start — Get WinScript Running in Claude Desktop
3737

38-
### Option 1: One-Click Installer (Recommended)
38+
### Option 1: Claude Desktop Extension (Easiest — Coming Soon)
39+
40+
**Once approved in Claude's Extensions directory:**
41+
42+
1. Open Claude Desktop
43+
2. Go to **Settings → Extensions**
44+
3. Search for **"WinScript"**
45+
4. Click **Install**
46+
5. 59 tools appear — done!
47+
48+
**Until then:** Use Option 2 or 3 below.
49+
50+
### Option 2: One-Click Installer
3951

4052
**Step 1:** Download this repo and double-click `install.bat`:
4153
```bash
@@ -46,29 +58,29 @@ Then double-click `install.bat` (or run `python install.py`)
4658

4759
**Step 2:** Restart Claude Desktop
4860

49-
**Step 3:** WinScript appears in Claude's Extensions panel with 59 tools — just like Desktop Commander.
61+
**Step 3:** WinScript appears in Claude's Extensions panel with 59 tools.
5062

51-
### Option 2: PyPI (One Command)
63+
### Option 3: PyPI (One Command)
5264
```bash
5365
pip install winscript
5466
winscript
5567
```
5668
Then configure Claude Desktop manually (see below).
5769

58-
### Option 3: Docker (Isolated)
70+
### Option 4: Docker (Isolated)
5971
```bash
6072
docker run -v %USERPROFILE%/.winscript:~/.winscript ghcr.io/roshandamm/winscript-mcp:latest
6173
```
6274

63-
### Option 4: Direct from Source
75+
### Option 5: Direct from Source
6476
```bash
6577
git clone https://github.com/RavaniRoshan/winscript-mcp.git
6678
cd winscript-mcp
6779
pip install -r requirements.txt
6880
python winscript-server.py
6981
```
7082

71-
All options start an MCP server. The installer (Option 1) auto-configures Claude Desktop for you.
83+
All options start an MCP server. The Claude Desktop Extension (Option 1) will be the easiest once approved.
7284

7385
---
7486

0 commit comments

Comments
 (0)