snapstacker-mcp 0.0.0-stage → 0.1.0
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.
- package/LICENSE +44 -0
- package/README.md +66 -3
- package/package.json +38 -6
- package/server.js +258 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
snapstacker-mcp Licence
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Gersi Kereci (gerker-dev). All rights reserved.
|
|
4
|
+
|
|
5
|
+
1. Permission to use
|
|
6
|
+
|
|
7
|
+
You may install and run the snapstacker-mcp helper (the "Software"), free of charge, in unmodified form as published by the copyright holder on npm (or as provided in the copyright holder's Snapstacker repository), for your own personal or internal business use with the Snapstacker browser extension. This includes letting your AI agent app download and start it (for example with "npx -y snapstacker-mcp").
|
|
8
|
+
|
|
9
|
+
2. Restrictions
|
|
10
|
+
|
|
11
|
+
Except as expressly permitted in section 1, or by mandatory law that cannot be waived by contract, you may not, without the prior written permission of the copyright holder:
|
|
12
|
+
|
|
13
|
+
(a) copy, reproduce or redistribute the Software or any part of it, in source or any other form;
|
|
14
|
+
(b) modify, adapt, translate or create derivative works of the Software;
|
|
15
|
+
(c) publish, upload, host, sell, rent, lease, sublicense or otherwise make the Software or any part of it available to others, including in another extension store, website or code repository;
|
|
16
|
+
(d) remove or change any copyright, licence or attribution notice;
|
|
17
|
+
(e) use the name, icon, artwork, text or branding of the Software for any other product or service;
|
|
18
|
+
(f) reuse the code, design or content of the Software in another product.
|
|
19
|
+
|
|
20
|
+
Being able to see the Software's files on your computer does not give you any right to do the things listed above.
|
|
21
|
+
|
|
22
|
+
3. Third-party components
|
|
23
|
+
|
|
24
|
+
The Software uses open-source packages (@modelcontextprotocol/sdk, ws and zod), which npm installs alongside it under their own licences (MIT). This licence does not limit the rights those licences give you for those packages.
|
|
25
|
+
|
|
26
|
+
4. Ownership
|
|
27
|
+
|
|
28
|
+
The Software is licensed, not sold. The copyright holder keeps all rights in the Software that are not expressly granted here.
|
|
29
|
+
|
|
30
|
+
5. No warranty
|
|
31
|
+
|
|
32
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
33
|
+
|
|
34
|
+
6. Limitation of liability
|
|
35
|
+
|
|
36
|
+
TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
|
|
37
|
+
|
|
38
|
+
7. Termination
|
|
39
|
+
|
|
40
|
+
This licence ends automatically if you breach it. You must then stop using the Software and delete all copies.
|
|
41
|
+
|
|
42
|
+
8. Permission requests
|
|
43
|
+
|
|
44
|
+
To ask for permission to do something this licence does not allow, write to gerkerdev@gmail.com.
|
package/README.md
CHANGED
|
@@ -1,3 +1,66 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# snapstacker-mcp
|
|
2
|
+
|
|
3
|
+
Lets your AI agent use [Snapstacker](../README.md), the multi-copy clipboard for Chrome, as a tool.
|
|
4
|
+
|
|
5
|
+
- **You collect, the agent works.** Copy bits from many tabs with Ctrl+C, then tell your agent "use my stack".
|
|
6
|
+
- **The agent collects, you paste.** The agent puts its results in the stack, one snap per item, and one Ctrl+V fills a whole column in a sheet, CRM or form.
|
|
7
|
+
- **The agent pastes.** It can paste the stack where your cursor is in the current Chrome tab.
|
|
8
|
+
|
|
9
|
+
The agent only sees what you copied into Snapstacker, nothing else in your browser. Everything stays on your computer: this helper talks to the extension over `127.0.0.1` only.
|
|
10
|
+
|
|
11
|
+
## Tools
|
|
12
|
+
|
|
13
|
+
| Tool | What it does | Hint to the agent app |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| `pair` | Links the agent app to Snapstacker with the one-time code from the Agents page | |
|
|
16
|
+
| `read_stack` | Lists the snaps, which ones an agent added, the paste format, and whether collecting is on | read only |
|
|
17
|
+
| `add_snaps` | Adds items to the end of the stack, one snap each; while Snapstacker is on, the stack goes on the clipboard | |
|
|
18
|
+
| `set_format` | Rows, or one line with a separator | |
|
|
19
|
+
| `copy_stack` | Puts the stack on the clipboard | |
|
|
20
|
+
| `paste_stack` | Pastes the stack where the cursor is in the current tab, then empties the stack (Undo on the page brings it back). Never presses Enter, submits or clicks | changes things |
|
|
21
|
+
| `clear_stack` | Empties the stack (it becomes the last stack, Alt+V brings it back) | changes things |
|
|
22
|
+
|
|
23
|
+
What an agent may do is decided in your agent app: it asks you before tools marked as changing things, and you can choose "always allow" or "deny" per tool there. Snapstacker itself only has the master switch ("Let AI agents use Snapstacker") and the list of paired apps.
|
|
24
|
+
|
|
25
|
+
## Set up
|
|
26
|
+
|
|
27
|
+
> **Not on npm yet.** Until `snapstacker-mcp` is published, use the helper from this repository: run `npm install` in this `mcp` folder, then use `node <clipstack folder>/mcp/server.js` wherever the steps below say `npx -y snapstacker-mcp` (command `node`, args `["<clipstack folder>/mcp/server.js"]`). An unpacked (test) build of the extension already writes the setup prompt that way. Publishing steps: [PUBLISHING.md](PUBLISHING.md).
|
|
28
|
+
|
|
29
|
+
1. In the Snapstacker popup, click **+ Set up agents** (between the snap count and Clear).
|
|
30
|
+
2. Click **Copy setup prompt** and paste it into your agent (Claude Code, Cursor, Codex and other agents that can add tools to themselves). It adds this server and pairs with the code inside the prompt.
|
|
31
|
+
|
|
32
|
+
Or add it by hand, then ask the agent to pair with the code from the Agents page:
|
|
33
|
+
|
|
34
|
+
**Claude Desktop** (Settings → Developer → Edit Config, `claude_desktop_config.json`):
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
{ "mcpServers": { "snapstacker": { "command": "npx", "args": ["-y", "snapstacker-mcp"] } } }
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**Claude Code**: `claude mcp add snapstacker -- npx -y snapstacker-mcp`, or without the `claude` command, a `.mcp.json` in your project folder:
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{ "mcpServers": { "snapstacker": { "command": "npx", "args": ["-y", "snapstacker-mcp"] } } }
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
**Cursor** (`~/.cursor/mcp.json`) and **VS Code** (`.vscode/mcp.json`, key `servers`): same `command` / `args` as Claude Desktop.
|
|
47
|
+
|
|
48
|
+
**Codex** (`~/.codex/config.toml`):
|
|
49
|
+
|
|
50
|
+
```toml
|
|
51
|
+
[mcp_servers.snapstacker]
|
|
52
|
+
command = "npx"
|
|
53
|
+
args = ["-y", "snapstacker-mcp"]
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Needs Node.js 18 or newer.
|
|
57
|
+
|
|
58
|
+
## Good to know
|
|
59
|
+
|
|
60
|
+
- **One Chrome profile.** Snapstacker only sees the tabs of the Chrome profile it is installed and paired in. If your agent's own browser tool drives a different profile (or a separate browser), `paste_stack` can't reach those tabs. Its "no tab matches" error lists the tabs it can see, which shows the mismatch.
|
|
61
|
+
- **After updating the helper, reconnect the agent.** Agent apps load the tool list when they start. A new tool or argument (like `paste_stack`'s `tab`) appears only after the agent app reconnects to the server: restart it, or reconnect the server in its MCP settings (`/mcp` in Claude Code).
|
|
62
|
+
- **Chrome must be open.** If Chrome is closed or agent access is off, the tools say so. The first call after the agent app starts may take up to about 30 seconds while Snapstacker wakes up and finds the helper; opening the Snapstacker popup speeds it up.
|
|
63
|
+
|
|
64
|
+
## How it works
|
|
65
|
+
|
|
66
|
+
The agent app starts this helper and talks MCP to it over stdin/stdout. The helper opens a WebSocket on `127.0.0.1`, port 48710 (the next free one up to 48714 when several agent apps run). While agent access is on, the Snapstacker extension connects to it. Only Chrome extensions may connect (web pages are refused), and the extension answers a helper only after it shows a token, which it hands out only for the pairing code on the Agents page. The token is kept in `~/.snapstacker-mcp/tokens.json`. Removing an app on the Agents page revokes its token.
|
package/package.json
CHANGED
|
@@ -1,6 +1,38 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "snapstacker-mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "snapstacker-mcp",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "MCP server that lets AI agents read, fill and paste your Snapstacker stack in Chrome.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"snapstacker-mcp": "server.js"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"server.js",
|
|
11
|
+
"README.md",
|
|
12
|
+
"LICENSE"
|
|
13
|
+
],
|
|
14
|
+
"engines": {
|
|
15
|
+
"node": ">=18"
|
|
16
|
+
},
|
|
17
|
+
"keywords": [
|
|
18
|
+
"mcp",
|
|
19
|
+
"model-context-protocol",
|
|
20
|
+
"clipboard",
|
|
21
|
+
"chrome-extension",
|
|
22
|
+
"snapstacker",
|
|
23
|
+
"ai-agent"
|
|
24
|
+
],
|
|
25
|
+
"license": "SEE LICENSE IN LICENSE",
|
|
26
|
+
"dependencies": {
|
|
27
|
+
"@modelcontextprotocol/sdk": "1.32.2",
|
|
28
|
+
"ws": "8.23.0",
|
|
29
|
+
"zod": "4.6.7"
|
|
30
|
+
},
|
|
31
|
+
"author": "Gersi Kereci (gerker-dev)",
|
|
32
|
+
"repository": {
|
|
33
|
+
"type": "git",
|
|
34
|
+
"url": "git+https://github.com/gerker-dev/clipstack.git",
|
|
35
|
+
"directory": "mcp"
|
|
36
|
+
},
|
|
37
|
+
"homepage": "https://github.com/gerker-dev/clipstack/tree/main/mcp#readme"
|
|
38
|
+
}
|
package/server.js
ADDED
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Snapstacker MCP helper. An agent app (Claude Desktop, Claude Code, Cursor, VS Code, Codex...) starts this program
|
|
3
|
+
// and talks MCP to it over stdin/stdout. The program in turn waits for the Snapstacker extension on a local
|
|
4
|
+
// WebSocket (127.0.0.1 only). The extension connects to it, and every tool call is passed on to the extension.
|
|
5
|
+
//
|
|
6
|
+
// Trust: the extension only answers a helper that shows a token, and it hands out a token only for the one-time
|
|
7
|
+
// pairing code shown on its Agents page. The token is kept in ~/.snapstacker-mcp/tokens.json, one per agent app.
|
|
8
|
+
// What an agent may do (ask, allow, deny) is up to the agent app: every tool carries MCP hints for that.
|
|
9
|
+
|
|
10
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
11
|
+
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
12
|
+
import { WebSocketServer } from 'ws';
|
|
13
|
+
import { z } from 'zod';
|
|
14
|
+
import fs from 'node:fs';
|
|
15
|
+
import os from 'node:os';
|
|
16
|
+
import path from 'node:path';
|
|
17
|
+
|
|
18
|
+
const VERSION = '0.1.0';
|
|
19
|
+
const PORTS = [48710, 48711, 48712, 48713, 48714]; // the extension tries all of them; each agent app takes the first free one
|
|
20
|
+
const CALL_TIMEOUT_MS = 15000;
|
|
21
|
+
// How long a tool call waits for the extension. Chrome may have put Snapstacker's service worker to sleep; it looks for
|
|
22
|
+
// helpers at least every 30 s (and at once when the popup opens), so the first call after the helper starts waits long
|
|
23
|
+
// enough for that. Once the extension was here, a missing one is more likely Chrome being closed: fail sooner.
|
|
24
|
+
const FIRST_WAIT_MS = 35000;
|
|
25
|
+
const LATER_WAIT_MS = 10000;
|
|
26
|
+
let everConnected = false;
|
|
27
|
+
const PING_MS = 20000; // keeps the extension's service worker awake while it is connected
|
|
28
|
+
|
|
29
|
+
const log = (...args) => process.stderr.write(`[snapstacker-mcp] ${args.join(' ')}\n`); // stdout belongs to MCP
|
|
30
|
+
|
|
31
|
+
// ---- tokens, one per agent app (keyed by the name the app reports when it connects)
|
|
32
|
+
const TOKEN_DIR = process.env.SNAPSTACKER_MCP_HOME || path.join(os.homedir(), '.snapstacker-mcp');
|
|
33
|
+
const TOKEN_FILE = path.join(TOKEN_DIR, 'tokens.json');
|
|
34
|
+
function readTokens() {
|
|
35
|
+
try { return JSON.parse(fs.readFileSync(TOKEN_FILE, 'utf8')); } catch { return {}; }
|
|
36
|
+
}
|
|
37
|
+
function writeTokens(tokens) {
|
|
38
|
+
fs.mkdirSync(TOKEN_DIR, { recursive: true });
|
|
39
|
+
fs.writeFileSync(TOKEN_FILE, JSON.stringify(tokens, null, 2), { mode: 0o600 });
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
// Friendly names for the apps we know; anything else shows the name the app reports.
|
|
43
|
+
const APP_NAMES = {
|
|
44
|
+
'claude-ai': 'Claude Desktop',
|
|
45
|
+
'claude-code': 'Claude Code',
|
|
46
|
+
'cursor-vscode': 'Cursor',
|
|
47
|
+
'visual studio code': 'VS Code',
|
|
48
|
+
'visual-studio-code': 'VS Code',
|
|
49
|
+
'codex-mcp-client': 'Codex',
|
|
50
|
+
'windsurf-client': 'Windsurf',
|
|
51
|
+
};
|
|
52
|
+
let clientKey = 'agent';
|
|
53
|
+
function agentName() {
|
|
54
|
+
return APP_NAMES[clientKey.toLowerCase()] || clientKey;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
// ---- the link to the extension
|
|
58
|
+
let socket = null; // the extension's connection, once it said hello
|
|
59
|
+
let authed = false; // the extension accepted our token
|
|
60
|
+
let nextId = 1;
|
|
61
|
+
const pending = new Map();
|
|
62
|
+
const waiters = new Set();
|
|
63
|
+
|
|
64
|
+
function send(message) {
|
|
65
|
+
return new Promise((resolve, reject) => {
|
|
66
|
+
if (!socket) return reject(new Error('not connected'));
|
|
67
|
+
const id = nextId++;
|
|
68
|
+
const timer = setTimeout(() => { pending.delete(id); reject(new Error('Snapstacker did not answer in time.')); }, CALL_TIMEOUT_MS);
|
|
69
|
+
pending.set(id, { resolve, reject, timer });
|
|
70
|
+
socket.send(JSON.stringify({ id, ...message }));
|
|
71
|
+
});
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
async function authenticate() {
|
|
75
|
+
authed = false;
|
|
76
|
+
const token = readTokens()[clientKey];
|
|
77
|
+
if (!token || !socket) return;
|
|
78
|
+
try {
|
|
79
|
+
const reply = await send({ type: 'auth', token, name: agentName() });
|
|
80
|
+
authed = reply.ok === true;
|
|
81
|
+
if (!authed) {
|
|
82
|
+
// Removed on the Agents page: forget it, so the agent asks for a new code.
|
|
83
|
+
const tokens = readTokens();
|
|
84
|
+
delete tokens[clientKey];
|
|
85
|
+
writeTokens(tokens);
|
|
86
|
+
}
|
|
87
|
+
} catch (err) {
|
|
88
|
+
log('auth failed:', err.message);
|
|
89
|
+
}
|
|
90
|
+
for (const wake of waiters) wake();
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
function startLink() {
|
|
94
|
+
let i = 0;
|
|
95
|
+
const tryPort = () => {
|
|
96
|
+
const port = PORTS[i];
|
|
97
|
+
const wss = new WebSocketServer({
|
|
98
|
+
host: '127.0.0.1',
|
|
99
|
+
port,
|
|
100
|
+
// Only a Chrome extension may connect, never a web page (pages could otherwise reach localhost).
|
|
101
|
+
verifyClient: ({ origin }) => typeof origin === 'string' && origin.startsWith('chrome-extension://'),
|
|
102
|
+
});
|
|
103
|
+
wss.on('listening', () => log(`waiting for Snapstacker on 127.0.0.1:${port}`));
|
|
104
|
+
wss.on('error', (err) => {
|
|
105
|
+
if (err.code === 'EADDRINUSE' && ++i < PORTS.length) return tryPort();
|
|
106
|
+
log('could not open a local port:', err.message);
|
|
107
|
+
});
|
|
108
|
+
wss.on('connection', (ws) => {
|
|
109
|
+
ws.once('message', (raw) => {
|
|
110
|
+
let hello;
|
|
111
|
+
try { hello = JSON.parse(String(raw)); } catch { return ws.close(); }
|
|
112
|
+
if (hello?.type !== 'hello' || hello.app !== 'snapstacker') return ws.close();
|
|
113
|
+
if (socket && socket !== ws) socket.close(); // one extension at a time; the newest wins
|
|
114
|
+
socket = ws;
|
|
115
|
+
everConnected = true;
|
|
116
|
+
log(`Snapstacker ${hello.version || ''} connected`);
|
|
117
|
+
ws.on('message', onMessage);
|
|
118
|
+
ws.on('close', () => {
|
|
119
|
+
if (socket !== ws) return;
|
|
120
|
+
socket = null;
|
|
121
|
+
authed = false;
|
|
122
|
+
for (const { reject, timer } of pending.values()) { clearTimeout(timer); reject(new Error('Snapstacker disconnected.')); }
|
|
123
|
+
pending.clear();
|
|
124
|
+
});
|
|
125
|
+
const ping = setInterval(() => (ws.readyState === ws.OPEN ? ws.send('{"type":"ping"}') : clearInterval(ping)), PING_MS);
|
|
126
|
+
authenticate();
|
|
127
|
+
});
|
|
128
|
+
});
|
|
129
|
+
};
|
|
130
|
+
tryPort();
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
function onMessage(raw) {
|
|
134
|
+
let message;
|
|
135
|
+
try { message = JSON.parse(String(raw)); } catch { return; }
|
|
136
|
+
if (message.type === 'revoked') {
|
|
137
|
+
authed = false;
|
|
138
|
+
const tokens = readTokens();
|
|
139
|
+
delete tokens[clientKey];
|
|
140
|
+
writeTokens(tokens);
|
|
141
|
+
return;
|
|
142
|
+
}
|
|
143
|
+
const waiting = pending.get(message.id);
|
|
144
|
+
if (!waiting) return;
|
|
145
|
+
pending.delete(message.id);
|
|
146
|
+
clearTimeout(waiting.timer);
|
|
147
|
+
waiting.resolve(message);
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
// Waits a little for the extension: its service worker may be asleep and reconnects within seconds.
|
|
151
|
+
function waitForLink(needAuth) {
|
|
152
|
+
const ready = () => socket && (!needAuth || authed);
|
|
153
|
+
if (ready()) return Promise.resolve(true);
|
|
154
|
+
return new Promise((resolve) => {
|
|
155
|
+
const done = (ok) => { clearTimeout(timer); waiters.delete(check); clearInterval(poll); resolve(ok); };
|
|
156
|
+
const check = () => { if (ready()) done(true); };
|
|
157
|
+
const timer = setTimeout(() => done(Boolean(ready())), everConnected ? LATER_WAIT_MS : FIRST_WAIT_MS);
|
|
158
|
+
const poll = setInterval(check, 250);
|
|
159
|
+
waiters.add(check);
|
|
160
|
+
});
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
const NOT_CONNECTED = 'Snapstacker is not connected. Ask the user to open Chrome and open the Snapstacker popup once (that makes it look for this agent right away). If that does not help: in the popup click "Set up agents" (or "Agents") and make sure "Let AI agents use Snapstacker" is switched on.';
|
|
164
|
+
const NOT_PAIRED = 'Snapstacker is not paired with this agent yet. Ask the user for the pairing code shown on Snapstacker\'s Agents page (click "Set up agents" in the popup), then call the pair tool with it.';
|
|
165
|
+
|
|
166
|
+
const text = (value) => ({ content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] });
|
|
167
|
+
const fail = (message) => ({ content: [{ type: 'text', text: message }], isError: true });
|
|
168
|
+
|
|
169
|
+
async function call(tool, args = {}) {
|
|
170
|
+
if (!(await waitForLink(false))) return fail(NOT_CONNECTED);
|
|
171
|
+
if (!(await waitForLink(true))) return fail(NOT_PAIRED);
|
|
172
|
+
try {
|
|
173
|
+
const reply = await send({ type: 'call', tool, args });
|
|
174
|
+
return reply.ok ? text(reply.result) : fail(reply.error || 'Snapstacker could not do that.');
|
|
175
|
+
} catch (err) {
|
|
176
|
+
return fail(err.message);
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
// ---- MCP
|
|
181
|
+
const server = new McpServer({ name: 'snapstacker', version: VERSION }, {
|
|
182
|
+
instructions: 'Snapstacker is the user\'s multi-copy clipboard in Chrome: a list ("stack") of text snippets ("snaps") that the user collects with Ctrl+C and pastes all at once with Ctrl+V, either as rows (one per line, so a spreadsheet gets one cell per row) or on one line with a separator. Use read_stack to see what the user collected. Use add_snaps to hand results to the user: each item becomes one snap, so a list of names or prices pastes as a column. Use paste_stack to paste the stack where the user\'s cursor is in their current Chrome tab. If a tool says the agent is not paired, ask the user for the pairing code from Snapstacker\'s Agents page and call pair.',
|
|
183
|
+
});
|
|
184
|
+
|
|
185
|
+
server.registerTool('pair', {
|
|
186
|
+
title: 'Pair with Snapstacker',
|
|
187
|
+
description: 'Links this agent app to the user\'s Snapstacker extension. Needs the one-time code shown on Snapstacker\'s Agents page (format ABC-123). Only needed once per agent app.',
|
|
188
|
+
inputSchema: { code: z.string().describe('The pairing code from Snapstacker\'s Agents page, for example K7Q-42M') },
|
|
189
|
+
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
|
|
190
|
+
}, async ({ code }) => {
|
|
191
|
+
if (!(await waitForLink(false))) return fail(NOT_CONNECTED);
|
|
192
|
+
try {
|
|
193
|
+
const reply = await send({ type: 'pair', code: code.trim().toUpperCase(), name: agentName() });
|
|
194
|
+
if (!reply.ok) return fail(reply.error || 'That code did not work. Ask the user for the current code on Snapstacker\'s Agents page (it changes every 5 minutes).');
|
|
195
|
+
const tokens = readTokens();
|
|
196
|
+
tokens[clientKey] = reply.token;
|
|
197
|
+
writeTokens(tokens);
|
|
198
|
+
authed = true;
|
|
199
|
+
return text(`Paired. Snapstacker now lists this agent as "${agentName()}". You can use read_stack, add_snaps, set_format, copy_stack, paste_stack and clear_stack.`);
|
|
200
|
+
} catch (err) {
|
|
201
|
+
return fail(err.message);
|
|
202
|
+
}
|
|
203
|
+
});
|
|
204
|
+
|
|
205
|
+
server.registerTool('read_stack', {
|
|
206
|
+
title: 'Read the Snapstacker stack',
|
|
207
|
+
description: 'Returns the snaps the user collected in Snapstacker, in paste order, with whether each was added by an agent, plus the paste format and whether collecting is switched on. Use it when the user refers to "my stack", "what I copied" or "my Snapstacker".',
|
|
208
|
+
inputSchema: {},
|
|
209
|
+
annotations: { readOnlyHint: true, openWorldHint: false },
|
|
210
|
+
}, async () => call('read_stack'));
|
|
211
|
+
|
|
212
|
+
server.registerTool('add_snaps', {
|
|
213
|
+
title: 'Add snaps to the stack',
|
|
214
|
+
description: 'Adds items to the end of the user\'s Snapstacker stack. Each item becomes one snap (one row when pasted). Line breaks inside an item become spaces. While Snapstacker is switched on, the whole stack is also put on the clipboard, so the user\'s next Ctrl+V pastes everything.',
|
|
215
|
+
inputSchema: { items: z.array(z.string()).min(1).max(500).describe('The snippets to add, one per snap, in order') },
|
|
216
|
+
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
|
|
217
|
+
}, async ({ items }) => call('add_snaps', { items }));
|
|
218
|
+
|
|
219
|
+
server.registerTool('set_format', {
|
|
220
|
+
title: 'Set the paste format',
|
|
221
|
+
description: 'Chooses how the stack is pasted: "rows" (one snap per line; spreadsheets get one cell per row) or "line" (all snaps on one line, joined by the separator).',
|
|
222
|
+
inputSchema: {
|
|
223
|
+
mode: z.enum(['rows', 'line']),
|
|
224
|
+
separator: z.string().max(3).optional().describe('Only for "line": the text between snaps, up to 3 characters, for example ", " or " | "'),
|
|
225
|
+
},
|
|
226
|
+
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
|
|
227
|
+
}, async (args) => call('set_format', args));
|
|
228
|
+
|
|
229
|
+
server.registerTool('copy_stack', {
|
|
230
|
+
title: 'Put the stack on the clipboard',
|
|
231
|
+
description: 'Puts the whole stack on the clipboard in the current paste format, so the user (or an agent that can press keys) can paste it anywhere, desktop apps included, with Ctrl+V.',
|
|
232
|
+
inputSchema: {},
|
|
233
|
+
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
|
|
234
|
+
}, async () => call('copy_stack'));
|
|
235
|
+
|
|
236
|
+
server.registerTool('paste_stack', {
|
|
237
|
+
title: 'Paste the stack into the page',
|
|
238
|
+
description: 'Pastes the whole stack into the text field where the user left the cursor (an input, text area or editor) in a Chrome tab, in the current paste format, then empties the stack like a normal paste. By default the tab is the front tab of the last used Chrome window; pass tab to choose one by part of its title or address. It only inserts text: it never presses Enter, submits or clicks. If the cursor is not in a field it fails and says so; ask the user to click into the field first. Some apps (Google Sheets, for example) ignore pasted text that does not come from a real key press; then the stack is left on the clipboard and the user should press Ctrl+V.',
|
|
239
|
+
inputSchema: { tab: z.string().max(200).optional().describe('Optional: part of the title or address of the tab to paste into, for example "docs.google.com" or "Order form"') },
|
|
240
|
+
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
|
|
241
|
+
}, async ({ tab }) => call('paste_stack', tab ? { tab } : {}));
|
|
242
|
+
|
|
243
|
+
server.registerTool('clear_stack', {
|
|
244
|
+
title: 'Clear the stack',
|
|
245
|
+
description: 'Empties the stack. The cleared snaps become the "last stack", so the user can bring them back with Alt+V or "Copy last stack".',
|
|
246
|
+
inputSchema: {},
|
|
247
|
+
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
|
|
248
|
+
}, async () => call('clear_stack'));
|
|
249
|
+
|
|
250
|
+
server.server.oninitialized = () => {
|
|
251
|
+
const info = server.server.getClientVersion();
|
|
252
|
+
if (info?.name) clientKey = String(info.name);
|
|
253
|
+
log(`agent app: ${agentName()}`);
|
|
254
|
+
if (socket) authenticate();
|
|
255
|
+
};
|
|
256
|
+
|
|
257
|
+
startLink();
|
|
258
|
+
await server.connect(new StdioServerTransport());
|