Skip to content

Commit 609263f

Browse files
zhensherlockzhensherlock
committed
docs: update README files with comprehensive usage and examples
1 parent 87c91a8 commit 609263f

3 files changed

Lines changed: 246 additions & 54 deletions

File tree

‎README.md‎

Lines changed: 82 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -14,51 +14,115 @@ One-click launch URL generator for protocol-based apps.
1414
[![][github-action-build-shield]][github-action-build-link]
1515
[![][github-license-shield]][github-license-link]
1616

17-
## Features
17+
`protocol-launcher` helps you generate typed deep links and URL scheme links for desktop, mobile, productivity, AI, and developer tools. Use it to open apps, jump to files or projects, install MCP servers, import provider settings, and create safe one-click launch links for websites, docs, CLIs, and automation flows.
1818

19-
- 🛡️️ Type-Safe
20-
- 🌍 Multi-App Ready
21-
- 🌿 On-Demand / Tree-shakable
22-
- 🔐 Secure Encoding
23-
- ⚙️ Zero Runtime Dependencies
24-
- 📦 ESM First
19+
## Why Protocol Launcher?
20+
21+
- Type-safe builders for supported protocol payloads.
22+
- On-demand imports such as `protocol-launcher/vscode` and `protocol-launcher/cherry-studio`.
23+
- Safe query-string and base64 payload encoding, including Unicode payloads.
24+
- Broad protocol coverage across AI tools, editors, productivity apps, native macOS apps, and utilities.
25+
- ESM-first output for Node.js and modern bundlers.
26+
- Zero third-party runtime dependencies.
2527

2628
## Installation
2729

2830
```bash
29-
npm install protocol-launcher
31+
pnpm add protocol-launcher
3032
```
3133

32-
or
34+
```bash
35+
npm install protocol-launcher
36+
```
3337

3438
```bash
3539
yarn add protocol-launcher
3640
```
3741

38-
or
39-
4042
```bash
41-
pnpm install protocol-launcher
43+
bun add protocol-launcher
4244
```
4345

4446
## Usage
4547

46-
### On-Demand Import (Recommended)
48+
### On-Demand Import
49+
50+
Use direct subpath imports when you only need one app integration.
51+
52+
```ts
53+
import { installMCP } from 'protocol-launcher/cursor'
54+
55+
const url = installMCP({
56+
name: 'server-everything',
57+
type: 'stdio',
58+
command: 'npx',
59+
args: ['-y', '@modelcontextprotocol/server-everything'],
60+
openInNewWindow: true,
61+
})
62+
```
63+
64+
```ts
65+
import { installProvider } from 'protocol-launcher/cherry-studio'
66+
67+
const url = installProvider({
68+
id: 'new-api',
69+
baseUrl: 'https://open.cherryin.ai',
70+
apiKey: 'sk-xxxx',
71+
})
72+
```
4773

4874
```ts
49-
// Cherry Studio
50-
import { installMCP, installProvider } from 'protocol-launcher/cherry-studio'
75+
import { openFile } from 'protocol-launcher/vscode'
5176

52-
// Cursor
53-
import { installMCP as installCursorMCP } from 'protocol-launcher/cursor'
77+
const url = openFile({
78+
path: '/code/protocol-launcher/README.md',
79+
line: 1,
80+
column: 1,
81+
})
5482
```
5583

5684
### Full Import
5785

86+
The root entry exports each protocol as a namespace.
87+
5888
```ts
59-
import { cherryStudio, cursor } from 'protocol-launcher'
89+
import { cherryStudio, cursor, vscode } from 'protocol-launcher'
90+
91+
const settingsUrl = vscode.openSettings({
92+
path: 'terminal.integrated.suggest.enabled',
93+
})
94+
95+
const folderUrl = cursor.openFolder({
96+
path: '/code/protocol-launcher',
97+
})
98+
99+
const providerUrl = cherryStudio.installProvider({
100+
id: 'openai',
101+
baseUrl: 'https://api.openai.com/v1',
102+
apiKey: 'sk-xxxx',
103+
})
60104
```
61105

106+
Prefer subpath imports for production bundles when possible.
107+
108+
## Popular Integrations
109+
110+
```ts
111+
import { openThread } from 'protocol-launcher/codex'
112+
import { installMCP } from 'protocol-launcher/cursor'
113+
import { open } from 'protocol-launcher/telegram'
114+
import { openSettings } from 'protocol-launcher/vscode'
115+
```
116+
117+
Examples of supported app categories:
118+
119+
- AI and coding tools: `antigravity`, `cherry-studio`, `code-buddy`, `codex`, `cursor`, `kiro`, `lingma`, `opencode`, `qoder`, `trae`, `vscode`, `windsurf`, `zed`
120+
- Editors and IDEs: `bbedit`, `code-runner`, `goland`, `idea`, `macvim`, `nova`, `phpstorm`, `pycharm`, `rustrover`, `textastic`, `textmate`, `webstorm`, `xcode`
121+
- Productivity and notes: `agenda`, `bear`, `craft`, `drafts`, `evernote`, `fsnotes`, `obsidian`, `things`, `todoist`, `trello`, `ulysses`, `working-copy`
122+
- Platform and utilities: `app-store`, `apple-map`, `macos`, `microsoft-edge`, `shortcuts`, `steam`, `telegram`, `thunder`, `wemeet`
123+
124+
See the [documentation site](https://zhensherlock.github.io/protocol-launcher/) for the full app list and exact API examples.
125+
62126
## Docs
63127

64128
Full guides and examples: https://zhensherlock.github.io/protocol-launcher/

‎packages/protocol-launcher/README.md‎

Lines changed: 82 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -14,51 +14,115 @@ One-click launch URL generator for protocol-based apps.
1414
[![][github-action-build-shield]][github-action-build-link]
1515
[![][github-license-shield]][github-license-link]
1616

17-
## Features
17+
`protocol-launcher` helps you generate typed deep links and URL scheme links for desktop, mobile, productivity, AI, and developer tools. Use it to open apps, jump to files or projects, install MCP servers, import provider settings, and create safe one-click launch links for websites, docs, CLIs, and automation flows.
1818

19-
- 🛡️️ Type-Safe
20-
- 🌍 Multi-App Ready
21-
- 🌿 On-Demand / Tree-shakable
22-
- 🔐 Secure Encoding
23-
- ⚙️ Zero Runtime Dependencies
24-
- 📦 ESM First
19+
## Why Protocol Launcher?
20+
21+
- Type-safe builders for supported protocol payloads.
22+
- On-demand imports such as `protocol-launcher/vscode` and `protocol-launcher/cherry-studio`.
23+
- Safe query-string and base64 payload encoding, including Unicode payloads.
24+
- Broad protocol coverage across AI tools, editors, productivity apps, native macOS apps, and utilities.
25+
- ESM-first output for Node.js and modern bundlers.
26+
- Zero third-party runtime dependencies.
2527

2628
## Installation
2729

2830
```bash
29-
npm install protocol-launcher
31+
pnpm add protocol-launcher
3032
```
3133

32-
or
34+
```bash
35+
npm install protocol-launcher
36+
```
3337

3438
```bash
3539
yarn add protocol-launcher
3640
```
3741

38-
or
39-
4042
```bash
41-
pnpm install protocol-launcher
43+
bun add protocol-launcher
4244
```
4345

4446
## Usage
4547

46-
### On-Demand Import (Recommended)
48+
### On-Demand Import
49+
50+
Use direct subpath imports when you only need one app integration.
51+
52+
```ts
53+
import { installMCP } from 'protocol-launcher/cursor'
54+
55+
const url = installMCP({
56+
name: 'server-everything',
57+
type: 'stdio',
58+
command: 'npx',
59+
args: ['-y', '@modelcontextprotocol/server-everything'],
60+
openInNewWindow: true,
61+
})
62+
```
63+
64+
```ts
65+
import { installProvider } from 'protocol-launcher/cherry-studio'
66+
67+
const url = installProvider({
68+
id: 'new-api',
69+
baseUrl: 'https://open.cherryin.ai',
70+
apiKey: 'sk-xxxx',
71+
})
72+
```
4773

4874
```ts
49-
// Cherry Studio
50-
import { installMCP, installProvider } from 'protocol-launcher/cherry-studio'
75+
import { openFile } from 'protocol-launcher/vscode'
5176

52-
// Cursor
53-
import { installMCP as installCursorMCP } from 'protocol-launcher/cursor'
77+
const url = openFile({
78+
path: '/code/protocol-launcher/README.md',
79+
line: 1,
80+
column: 1,
81+
})
5482
```
5583

5684
### Full Import
5785

86+
The root entry exports each protocol as a namespace.
87+
5888
```ts
59-
import { cherryStudio, cursor } from 'protocol-launcher'
89+
import { cherryStudio, cursor, vscode } from 'protocol-launcher'
90+
91+
const settingsUrl = vscode.openSettings({
92+
path: 'terminal.integrated.suggest.enabled',
93+
})
94+
95+
const folderUrl = cursor.openFolder({
96+
path: '/code/protocol-launcher',
97+
})
98+
99+
const providerUrl = cherryStudio.installProvider({
100+
id: 'openai',
101+
baseUrl: 'https://api.openai.com/v1',
102+
apiKey: 'sk-xxxx',
103+
})
60104
```
61105

106+
Prefer subpath imports for production bundles when possible.
107+
108+
## Popular Integrations
109+
110+
```ts
111+
import { openThread } from 'protocol-launcher/codex'
112+
import { installMCP } from 'protocol-launcher/cursor'
113+
import { open } from 'protocol-launcher/telegram'
114+
import { openSettings } from 'protocol-launcher/vscode'
115+
```
116+
117+
Examples of supported app categories:
118+
119+
- AI and coding tools: `antigravity`, `cherry-studio`, `code-buddy`, `codex`, `cursor`, `kiro`, `lingma`, `opencode`, `qoder`, `trae`, `vscode`, `windsurf`, `zed`
120+
- Editors and IDEs: `bbedit`, `code-runner`, `goland`, `idea`, `macvim`, `nova`, `phpstorm`, `pycharm`, `rustrover`, `textastic`, `textmate`, `webstorm`, `xcode`
121+
- Productivity and notes: `agenda`, `bear`, `craft`, `drafts`, `evernote`, `fsnotes`, `obsidian`, `things`, `todoist`, `trello`, `ulysses`, `working-copy`
122+
- Platform and utilities: `app-store`, `apple-map`, `macos`, `microsoft-edge`, `shortcuts`, `steam`, `telegram`, `thunder`, `wemeet`
123+
124+
See the [documentation site](https://zhensherlock.github.io/protocol-launcher/) for the full app list and exact API examples.
125+
62126
## Docs
63127

64128
Full guides and examples: https://zhensherlock.github.io/protocol-launcher/

0 commit comments

Comments
 (0)