@profullstack/chat-plugins 0.0.0-stage → 0.2.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 +3 -0
- package/README.md +126 -2
- package/index.d.ts +360 -0
- package/package.json +53 -4
- package/src/catalog.js +79 -0
- package/src/discover.js +180 -0
- package/src/index.js +41 -0
- package/src/loop.js +403 -0
- package/src/mcp.js +323 -0
- package/src/money.js +372 -0
- package/src/net.js +299 -0
- package/src/oauth.js +280 -0
- package/src/seal.js +69 -0
- package/src/tools.js +114 -0
package/LICENSE
ADDED
package/README.md
CHANGED
|
@@ -1,3 +1,127 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @profullstack/chat-plugins
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Plugins for chat apps, with fewer hoops than "connectors". A plugin is a remote
|
|
4
|
+
[MCP](https://modelcontextprotocol.io) server. A person pastes a URL (or picks one from
|
|
5
|
+
a short catalog), signs in on the provider's own page if it asks, and the plugin's tools
|
|
6
|
+
are usable by the model in chat. No developer mode, no client id/secret forms, no manual
|
|
7
|
+
OAuth setup: the client registers itself (RFC 7591), uses PKCE S256, and refreshes tokens.
|
|
8
|
+
|
|
9
|
+
- Zero dependencies. ESM. Node 20+, Bun, Deno, Workers (WebCrypto + fetch).
|
|
10
|
+
- Streamable HTTP MCP client (protocol 2025-06-18): JSON and SSE responses, `Mcp-Session-Id`.
|
|
11
|
+
- An agent loop that works with models that have **no native tool calling** (a prompt
|
|
12
|
+
protocol with a robust parser) and with native OpenAI-style `tool_calls`.
|
|
13
|
+
- Approval cards for destructive tools.
|
|
14
|
+
- Safe by default on servers: https only, SSRF guard (DNS resolved, private ranges refused),
|
|
15
|
+
bearer tokens never follow a redirect to another host, response size caps, tool results
|
|
16
|
+
passed to the model as data and never as instructions.
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
npm i @profullstack/chat-plugins
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Add a plugin
|
|
23
|
+
|
|
24
|
+
```js
|
|
25
|
+
import { resolvePluginInput, discover, startAuth, finishAuth, listTools, sealToken } from "@profullstack/chat-plugins";
|
|
26
|
+
|
|
27
|
+
const input = resolvePluginInput("c0mpute"); // or a URL: "https://example.com/mcp"
|
|
28
|
+
const server = await discover(input.url); // { name, title, instructions, auth }
|
|
29
|
+
|
|
30
|
+
if (server.auth === "none") {
|
|
31
|
+
const tools = await listTools({ url: server.url }); // done
|
|
32
|
+
} else {
|
|
33
|
+
// store: your persistence for registered clients (getClient/setClient)
|
|
34
|
+
const { authorizeUrl, pending } = await startAuth({
|
|
35
|
+
server, redirectUri: "https://app.example/api/v1/plugins/callback", clientName: "My chat", store,
|
|
36
|
+
});
|
|
37
|
+
// keep `pending` server-side (keyed by pending.state), open authorizeUrl in a popup
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
// in the callback route:
|
|
41
|
+
const tokens = await finishAuth({ pending, code, state });
|
|
42
|
+
await db.save(slug, await sealToken(tokens, process.env.PLUGIN_TOKEN_KEY)); // AES-256-GCM at rest
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
`auth.required === false` means the server works without sign-in but offers it (more
|
|
46
|
+
tools when signed in).
|
|
47
|
+
|
|
48
|
+
## Use plugins in chat
|
|
49
|
+
|
|
50
|
+
```js
|
|
51
|
+
import { runToolLoop, ensureFresh } from "@profullstack/chat-plugins";
|
|
52
|
+
|
|
53
|
+
const plugins = [{ slug: "c0mpute", name: "c0mpute hosting", url, token, tools }];
|
|
54
|
+
|
|
55
|
+
const result = await runToolLoop({
|
|
56
|
+
messages,
|
|
57
|
+
plugins,
|
|
58
|
+
protocol: "prompt", // "auto" (default) | "native" | "prompt"
|
|
59
|
+
complete: (messages, tools) => myModel(messages, tools), // string, OpenAI completion, or message
|
|
60
|
+
approve: (call) => "pending", // "allow" | "deny" | "pending"
|
|
61
|
+
onEvent: (e) => send(e), // tool_call | tool_result | approval_needed | text
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
if (result.status === "pending") {
|
|
65
|
+
// show an approval card for result.pending.call; later:
|
|
66
|
+
await runToolLoop({ messages: result.pending.messages, resume: { pending: result.pending, decision: "allow" }, plugins, complete });
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Tools are named `<slug>__<tool>` (at most 64 chars, `[a-zA-Z0-9_-]`). `toOpenAITools(plugins)`
|
|
71
|
+
gives the OpenAI `tools` array. A tool needs approval when `annotations.destructiveHint === true`,
|
|
72
|
+
or when it is not read-only and `openWorldHint === true`.
|
|
73
|
+
|
|
74
|
+
**Prompt protocol.** For models without tool calling, the loop adds a system prompt listing
|
|
75
|
+
the tools with their JSON schemas. The model replies with one block:
|
|
76
|
+
|
|
77
|
+
````
|
|
78
|
+
```tool_call
|
|
79
|
+
{"name": "c0mpute__list_sites", "arguments": {}}
|
|
80
|
+
```
|
|
81
|
+
````
|
|
82
|
+
|
|
83
|
+
The parser also accepts `<tool_call>` tags, `json` fences that contain a call, alternate keys
|
|
84
|
+
(`tool`/`args`/`input`, `function: {name, arguments}`), stringified arguments, trailing commas,
|
|
85
|
+
an unclosed final fence, and ignores calls drafted inside `<think>`. Results go back as a
|
|
86
|
+
user message inside `<tool_result>` with a note that it is data, not instructions. With
|
|
87
|
+
`protocol: "auto"` both native `tool_calls` and the block are accepted.
|
|
88
|
+
|
|
89
|
+
Tool results keep the full text for the UI (`text`) and a ~16 KB cut for the model (`modelText`).
|
|
90
|
+
|
|
91
|
+
## Catalog
|
|
92
|
+
|
|
93
|
+
`CATALOG` ships c0mpute hosting and ThreatCrush. `makeCatalog(extra, { replace })` merges your
|
|
94
|
+
own entries (an entry with an empty `url` removes a built-in one).
|
|
95
|
+
|
|
96
|
+
## Server-side safety
|
|
97
|
+
|
|
98
|
+
Every request goes through `safeFetch`: https only (`allowHttpLocalhost` for dev,
|
|
99
|
+
`allowPrivate` for tests), hostnames resolved and checked against private, loopback,
|
|
100
|
+
link-local, CGNAT, multicast and reserved ranges, redirects re-checked hop by hop, and an
|
|
101
|
+
`Authorization` header never forwarded across origins. `guard(url)` adds your own check.
|
|
102
|
+
|
|
103
|
+
## License
|
|
104
|
+
|
|
105
|
+
MIT
|
|
106
|
+
|
|
107
|
+
## Money plugins (0.2.0)
|
|
108
|
+
|
|
109
|
+
`FINANCE_CATALOG` lists Mercury (business banking), CoinPay (crypto payments)
|
|
110
|
+
and moomoo (brokerage and trading); `DEFAULT_PLUGINS` are the ones apps turn
|
|
111
|
+
on for every account (Mercury and CoinPay; each person signs in to their own
|
|
112
|
+
account). The confirmation gate goes in your tool-call layer:
|
|
113
|
+
|
|
114
|
+
```js
|
|
115
|
+
import { applyPolicy, describeAction, policyFor, listTools } from "@profullstack/chat-plugins";
|
|
116
|
+
|
|
117
|
+
const policy = policyFor(plugin.url); // by server, not slug
|
|
118
|
+
const tools = applyPolicy(policy, await listTools(plugin), plugin.tradingMode ?? "paper");
|
|
119
|
+
// Only allowlisted reads run alone; every other tool (and any unknown name)
|
|
120
|
+
// is destructiveHint: true, so needsApproval() stops the loop for the person.
|
|
121
|
+
// describeAction(policy, tool, args) is the approval card: amount, currency,
|
|
122
|
+
// from, to, memo; or symbol, side, qty, type, prices, estimated cost, paper/live.
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
moomoo in paper mode offers reads plus `sim_trade_*` orders only; live order
|
|
126
|
+
tools appear only in `"live"` mode, and still ask. `redactLog()` masks tokens,
|
|
127
|
+
long digit runs and amounts before anything reaches a log.
|
package/index.d.ts
ADDED
|
@@ -0,0 +1,360 @@
|
|
|
1
|
+
// Types for @profullstack/chat-plugins
|
|
2
|
+
|
|
3
|
+
export interface NetOptions {
|
|
4
|
+
/** Custom fetch implementation. */
|
|
5
|
+
fetch?: typeof fetch;
|
|
6
|
+
/** Allow private/loopback targets and plain http (local dev, tests). Default false. */
|
|
7
|
+
allowPrivate?: boolean;
|
|
8
|
+
/** Allow http://localhost while still refusing other private targets. */
|
|
9
|
+
allowHttpLocalhost?: boolean;
|
|
10
|
+
/** Per-request timeout in ms. */
|
|
11
|
+
timeoutMs?: number;
|
|
12
|
+
/** Response body cap in bytes. */
|
|
13
|
+
maxBytes?: number;
|
|
14
|
+
/** Extra caller check, run for every URL (including each redirect hop). Throw to refuse. */
|
|
15
|
+
guard?: (url: URL) => void | Promise<void>;
|
|
16
|
+
clientInfo?: { name: string; version: string };
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export class PluginError extends Error {
|
|
20
|
+
code: string;
|
|
21
|
+
status?: number;
|
|
22
|
+
constructor(message: string, info?: { code?: string; status?: number; cause?: unknown });
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export interface Connection {
|
|
26
|
+
url: string;
|
|
27
|
+
token?: string;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export interface ToolAnnotations {
|
|
31
|
+
title?: string;
|
|
32
|
+
readOnlyHint?: boolean;
|
|
33
|
+
destructiveHint?: boolean;
|
|
34
|
+
idempotentHint?: boolean;
|
|
35
|
+
openWorldHint?: boolean;
|
|
36
|
+
[k: string]: unknown;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export interface McpTool {
|
|
40
|
+
name: string;
|
|
41
|
+
title?: string;
|
|
42
|
+
description?: string;
|
|
43
|
+
inputSchema: Record<string, unknown>;
|
|
44
|
+
annotations?: ToolAnnotations;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export interface ToolResult {
|
|
48
|
+
isError: boolean;
|
|
49
|
+
content: unknown[];
|
|
50
|
+
structuredContent?: unknown;
|
|
51
|
+
/** Full text, for the UI. */
|
|
52
|
+
text: string;
|
|
53
|
+
/** Text capped (~16 KB) for the model. */
|
|
54
|
+
modelText: string;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export interface AuthInfo {
|
|
58
|
+
issuer: string;
|
|
59
|
+
authorization_endpoint: string;
|
|
60
|
+
token_endpoint: string;
|
|
61
|
+
registration_endpoint?: string;
|
|
62
|
+
scopes?: string[];
|
|
63
|
+
/** RFC 8707 resource indicator sent on authorize and token requests. */
|
|
64
|
+
resource?: string;
|
|
65
|
+
/** false when the server answers without sign-in but offers it (more tools when signed in). */
|
|
66
|
+
required?: boolean;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export interface DiscoveredServer {
|
|
70
|
+
url: string;
|
|
71
|
+
name: string;
|
|
72
|
+
title: string;
|
|
73
|
+
instructions: string;
|
|
74
|
+
version?: string;
|
|
75
|
+
auth: "none" | AuthInfo;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
export interface ClientRecord {
|
|
79
|
+
client_id: string;
|
|
80
|
+
client_secret?: string;
|
|
81
|
+
registered_at?: number;
|
|
82
|
+
[k: string]: unknown;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
export interface Tokens {
|
|
86
|
+
access_token: string;
|
|
87
|
+
refresh_token?: string;
|
|
88
|
+
/** ms since epoch */
|
|
89
|
+
expires_at?: number;
|
|
90
|
+
token_type?: string;
|
|
91
|
+
scope?: string;
|
|
92
|
+
client_id?: string;
|
|
93
|
+
client_secret?: string;
|
|
94
|
+
token_endpoint?: string;
|
|
95
|
+
resource?: string;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Persistence the caller supplies. Clients are cached per issuer+redirectUri
|
|
100
|
+
* (key from clientKey()). Token methods are optional conveniences; tokens must be
|
|
101
|
+
* stored encrypted at rest (see sealToken).
|
|
102
|
+
*/
|
|
103
|
+
export interface PluginStore {
|
|
104
|
+
getClient(key: string): Promise<ClientRecord | null | undefined> | ClientRecord | null | undefined;
|
|
105
|
+
setClient(key: string, client: ClientRecord): Promise<void> | void;
|
|
106
|
+
deleteClient?(key: string): Promise<void> | void;
|
|
107
|
+
getTokens?(slug: string): Promise<Tokens | null | undefined> | Tokens | null | undefined;
|
|
108
|
+
setTokens?(slug: string, tokens: Tokens): Promise<void> | void;
|
|
109
|
+
deleteTokens?(slug: string): Promise<void> | void;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
export interface PendingAuth {
|
|
113
|
+
v: 1;
|
|
114
|
+
state: string;
|
|
115
|
+
verifier: string;
|
|
116
|
+
client_id: string;
|
|
117
|
+
client_secret?: string;
|
|
118
|
+
/** The plugin's MCP URL. */
|
|
119
|
+
url: string;
|
|
120
|
+
issuer: string;
|
|
121
|
+
token_endpoint: string;
|
|
122
|
+
resource?: string;
|
|
123
|
+
redirect_uri: string;
|
|
124
|
+
created_at: number;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
export interface StartAuthOptions extends NetOptions {
|
|
128
|
+
server: DiscoveredServer;
|
|
129
|
+
redirectUri: string;
|
|
130
|
+
clientName?: string;
|
|
131
|
+
store: PluginStore;
|
|
132
|
+
scopes?: string[];
|
|
133
|
+
clientUri?: string;
|
|
134
|
+
logoUri?: string;
|
|
135
|
+
/** Pre-registered client id, used when the server has no registration endpoint. */
|
|
136
|
+
clientId?: string;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
export interface FinishAuthOptions extends NetOptions {
|
|
140
|
+
pending: PendingAuth;
|
|
141
|
+
code: string;
|
|
142
|
+
state: string;
|
|
143
|
+
redirectUri?: string;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
export interface Plugin {
|
|
147
|
+
slug: string;
|
|
148
|
+
name?: string;
|
|
149
|
+
url: string;
|
|
150
|
+
token?: string;
|
|
151
|
+
enabled?: boolean;
|
|
152
|
+
tools: McpTool[];
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
export interface CatalogEntry {
|
|
156
|
+
slug: string;
|
|
157
|
+
name: string;
|
|
158
|
+
url: string;
|
|
159
|
+
description?: string;
|
|
160
|
+
homepage?: string;
|
|
161
|
+
icon?: string;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
export interface OpenAITool {
|
|
165
|
+
type: "function";
|
|
166
|
+
function: { name: string; description: string; parameters: Record<string, unknown> };
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
export interface ApprovalCall {
|
|
170
|
+
id: string;
|
|
171
|
+
/** Namespaced tool name `<slug>__<tool>`. */
|
|
172
|
+
name: string;
|
|
173
|
+
plugin: string;
|
|
174
|
+
pluginName: string;
|
|
175
|
+
tool: string;
|
|
176
|
+
title: string;
|
|
177
|
+
arguments: Record<string, unknown>;
|
|
178
|
+
annotations: ToolAnnotations;
|
|
179
|
+
kind: "native" | "prompt";
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export type ApprovalDecision = "allow" | "deny" | "pending";
|
|
183
|
+
|
|
184
|
+
export type LoopEvent =
|
|
185
|
+
| { type: "tool_call"; id: string; name: string; plugin: string; tool: string; title: string; arguments: Record<string, unknown> }
|
|
186
|
+
| {
|
|
187
|
+
type: "tool_result";
|
|
188
|
+
id: string;
|
|
189
|
+
name: string;
|
|
190
|
+
plugin: string;
|
|
191
|
+
tool: string;
|
|
192
|
+
isError: boolean;
|
|
193
|
+
denied?: boolean;
|
|
194
|
+
code?: string;
|
|
195
|
+
text: string;
|
|
196
|
+
modelText: string;
|
|
197
|
+
content: unknown[];
|
|
198
|
+
structuredContent?: unknown;
|
|
199
|
+
}
|
|
200
|
+
| { type: "approval_needed"; call: ApprovalCall }
|
|
201
|
+
| { type: "text"; text: string };
|
|
202
|
+
|
|
203
|
+
export interface PendingApproval {
|
|
204
|
+
call: ApprovalCall;
|
|
205
|
+
remaining: ApprovalCall[];
|
|
206
|
+
step: number;
|
|
207
|
+
messages: any[];
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
export interface LoopResult {
|
|
211
|
+
status: "done" | "pending";
|
|
212
|
+
text: string;
|
|
213
|
+
messages: any[];
|
|
214
|
+
steps: number;
|
|
215
|
+
exhausted?: boolean;
|
|
216
|
+
pending?: PendingApproval;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
export type ModelReply =
|
|
220
|
+
| string
|
|
221
|
+
| { content?: string | null; tool_calls?: any[] }
|
|
222
|
+
| { choices: Array<{ message: any }> }
|
|
223
|
+
| { message: any };
|
|
224
|
+
|
|
225
|
+
export interface ToolLoopOptions {
|
|
226
|
+
messages: any[];
|
|
227
|
+
plugins: Plugin[];
|
|
228
|
+
/** The caller's model call. `tools` is undefined when tools should not be offered natively. */
|
|
229
|
+
complete: (messages: any[], tools?: OpenAITool[]) => Promise<ModelReply> | ModelReply;
|
|
230
|
+
maxSteps?: number;
|
|
231
|
+
/** Default: () => "pending" (every gated call becomes an approval card). */
|
|
232
|
+
approve?: (call: ApprovalCall) => ApprovalDecision | Promise<ApprovalDecision>;
|
|
233
|
+
/**
|
|
234
|
+
* "auto" (default): offer native tools AND the prompt protocol, accept either.
|
|
235
|
+
* "prompt": models without tool calling (Ollama /api/chat etc.). "native": tools array only.
|
|
236
|
+
*/
|
|
237
|
+
protocol?: "auto" | "native" | "prompt";
|
|
238
|
+
onEvent?: (event: LoopEvent) => void | Promise<void>;
|
|
239
|
+
/** Override how a tool is executed (tests, proxies). */
|
|
240
|
+
callTool?: (plugin: Plugin, tool: string, args: Record<string, unknown>) => Promise<ToolResult>;
|
|
241
|
+
net?: NetOptions;
|
|
242
|
+
modelTextLimit?: number;
|
|
243
|
+
/** Continue after an approval card: pass the PendingApproval and the person's decision. */
|
|
244
|
+
resume?: { pending: PendingApproval; decision: "allow" | "deny" };
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
export const PROTOCOL_VERSION: string;
|
|
248
|
+
export const MODEL_TEXT_LIMIT: number;
|
|
249
|
+
export const MAX_TOOL_NAME: number;
|
|
250
|
+
export const PENDING_TTL_MS: number;
|
|
251
|
+
export const CATALOG: readonly CatalogEntry[];
|
|
252
|
+
|
|
253
|
+
export function discover(url: string, opts?: NetOptions): Promise<DiscoveredServer>;
|
|
254
|
+
export function startAuth(opts: StartAuthOptions): Promise<{ authorizeUrl: string; pending: PendingAuth }>;
|
|
255
|
+
export function finishAuth(opts: FinishAuthOptions): Promise<Tokens>;
|
|
256
|
+
export function refresh(tokens: Tokens, opts?: NetOptions): Promise<Tokens>;
|
|
257
|
+
export function ensureFresh(tokens: Tokens, opts?: NetOptions): Promise<{ tokens: Tokens; refreshed: boolean }>;
|
|
258
|
+
export function isExpired(tokens: Tokens | null | undefined, skewMs?: number): boolean;
|
|
259
|
+
export function memoryStore(): Required<PluginStore>;
|
|
260
|
+
export function clientKey(issuer: string, redirectUri: string): string;
|
|
261
|
+
export function pkceChallenge(verifier: string): Promise<string>;
|
|
262
|
+
export function randomToken(bytes?: number): string;
|
|
263
|
+
|
|
264
|
+
export function initialize(conn: Connection, opts?: NetOptions): Promise<{ info: any; sessionId?: string }>;
|
|
265
|
+
export function listTools(conn: Connection, opts?: NetOptions & { maxTools?: number }): Promise<McpTool[]>;
|
|
266
|
+
export function callTool(
|
|
267
|
+
conn: Connection,
|
|
268
|
+
name: string,
|
|
269
|
+
args?: Record<string, unknown>,
|
|
270
|
+
opts?: NetOptions & { modelTextLimit?: number },
|
|
271
|
+
): Promise<ToolResult>;
|
|
272
|
+
export function contentToText(content: unknown[], structured?: unknown): string;
|
|
273
|
+
export function truncateForModel(text: string, limit?: number): string;
|
|
274
|
+
export function parseSse(text: string, id: number | string): any;
|
|
275
|
+
export function resetSessions(conn?: Connection): void;
|
|
276
|
+
|
|
277
|
+
export function toOpenAITools(plugins: Plugin[]): OpenAITool[];
|
|
278
|
+
export function toolName(slug: string, tool: string): string;
|
|
279
|
+
export function buildToolIndex(plugins: Plugin[]): Map<string, { plugin: Plugin; tool: McpTool; name: string }>;
|
|
280
|
+
export function resolveTool(
|
|
281
|
+
index: Map<string, { plugin: Plugin; tool: McpTool; name: string }>,
|
|
282
|
+
name: string,
|
|
283
|
+
): { plugin: Plugin; tool: McpTool; name: string } | null;
|
|
284
|
+
export function needsApproval(tool: McpTool): boolean;
|
|
285
|
+
export function slugify(input: string): string;
|
|
286
|
+
|
|
287
|
+
export function runToolLoop(opts: ToolLoopOptions): Promise<LoopResult & { events: LoopEvent[] }>;
|
|
288
|
+
export function iterateToolLoop(opts: ToolLoopOptions): AsyncGenerator<LoopEvent, LoopResult>;
|
|
289
|
+
export function parseToolCall(text: string): { name: string; arguments: Record<string, unknown>; before: string } | null;
|
|
290
|
+
export function normalizeReply(reply: ModelReply): { content: string; tool_calls: Array<{ id?: string; name: string; arguments: Record<string, unknown> }> };
|
|
291
|
+
export function toolPrompt(plugins: Plugin[]): string;
|
|
292
|
+
export function wrapToolResult(name: string, text: string, isError: boolean): string;
|
|
293
|
+
|
|
294
|
+
export function makeCatalog(extra?: CatalogEntry[], opts?: { replace?: boolean }): CatalogEntry[];
|
|
295
|
+
export function resolvePluginInput(
|
|
296
|
+
input: string,
|
|
297
|
+
catalog?: readonly CatalogEntry[],
|
|
298
|
+
): { slug: string; url: string; name: string; entry?: CatalogEntry } | null;
|
|
299
|
+
export function uniqueSlug(base: string, taken: Iterable<string>): string;
|
|
300
|
+
|
|
301
|
+
export function sealToken(secret: string | object, key: string | Uint8Array): Promise<string>;
|
|
302
|
+
export function openToken(sealed: string, key: string | Uint8Array): Promise<any>;
|
|
303
|
+
|
|
304
|
+
export function assertSafeUrl(url: string | URL, opts?: NetOptions): Promise<URL>;
|
|
305
|
+
export function isPrivateAddress(ip: string): boolean;
|
|
306
|
+
export function isLocalHostname(host: string): boolean;
|
|
307
|
+
export function safeFetch(
|
|
308
|
+
url: string | URL,
|
|
309
|
+
init?: RequestInit & { headers?: Record<string, string> },
|
|
310
|
+
opts?: NetOptions,
|
|
311
|
+
): Promise<{ res: Response; url: URL; done: () => void }>;
|
|
312
|
+
export function fetchJson(
|
|
313
|
+
url: string | URL,
|
|
314
|
+
init?: RequestInit & { headers?: Record<string, string> },
|
|
315
|
+
opts?: NetOptions & { soft?: boolean },
|
|
316
|
+
): Promise<any>;
|
|
317
|
+
export function parseWwwAuthenticate(header: string): Record<string, string>;
|
|
318
|
+
export function protectedResourceCandidates(resource: URL): string[];
|
|
319
|
+
export function authServerCandidates(issuer: string): string[];
|
|
320
|
+
|
|
321
|
+
// ── money plugins (src/money.js) ────────────────────────────────────────────
|
|
322
|
+
|
|
323
|
+
export type MoneyKind = "banking" | "crypto" | "trading";
|
|
324
|
+
export type TradingMode = "paper" | "live";
|
|
325
|
+
export interface PluginPolicy {
|
|
326
|
+
slug: string;
|
|
327
|
+
kind: MoneyKind;
|
|
328
|
+
/** Tools that only read. Exact names; anything else asks first. */
|
|
329
|
+
readOnly: ReadonlySet<string>;
|
|
330
|
+
/** OAuth scopes to ask for instead of everything the server offers. */
|
|
331
|
+
scopes?: string[];
|
|
332
|
+
/** Brokerage: tools that place, change or cancel PAPER orders. */
|
|
333
|
+
paperWrites?: ReadonlySet<string>;
|
|
334
|
+
}
|
|
335
|
+
export interface FinanceCatalogEntry {
|
|
336
|
+
slug: string;
|
|
337
|
+
name: string;
|
|
338
|
+
url: string;
|
|
339
|
+
description: string;
|
|
340
|
+
homepage: string;
|
|
341
|
+
icon: string;
|
|
342
|
+
/** On for every account (listed and switched on, not signed in). */
|
|
343
|
+
default: boolean;
|
|
344
|
+
}
|
|
345
|
+
export interface ActionSummary {
|
|
346
|
+
title: string;
|
|
347
|
+
lines: { label: string; value: string }[];
|
|
348
|
+
account?: TradingMode;
|
|
349
|
+
note?: string;
|
|
350
|
+
}
|
|
351
|
+
export const MODEL_CAN_BE_WRONG: string;
|
|
352
|
+
export const FINANCE_CATALOG: readonly FinanceCatalogEntry[];
|
|
353
|
+
export const DEFAULT_PLUGINS: readonly FinanceCatalogEntry[];
|
|
354
|
+
export const POLICIES: Record<string, PluginPolicy>;
|
|
355
|
+
export function policyFor(url: string): PluginPolicy | null;
|
|
356
|
+
export function needsConfirmation(policy: PluginPolicy, tool: string): boolean;
|
|
357
|
+
export function visibleInMode(policy: PluginPolicy, tool: string, mode: TradingMode): boolean;
|
|
358
|
+
export function applyPolicy<T extends { name: string; annotations?: object }>(policy: PluginPolicy | null, tools: T[], mode?: TradingMode): T[];
|
|
359
|
+
export function describeAction(policy: PluginPolicy | null, tool: string, args: Record<string, unknown>): ActionSummary | null;
|
|
360
|
+
export function redactLog(v: unknown): string;
|
package/package.json
CHANGED
|
@@ -1,6 +1,55 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@profullstack/chat-plugins",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"description": "
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"description": "Chat plugins = remote MCP servers, with less hoops than connectors: paste a URL or pick from a catalog, sign-in is automatic (OAuth 2.1 + DCR + PKCE), and an agent loop runs the tools even on models with no native tool calling. Zero dependencies.",
|
|
6
|
+
"keywords": [
|
|
7
|
+
"mcp",
|
|
8
|
+
"model-context-protocol",
|
|
9
|
+
"plugins",
|
|
10
|
+
"connectors",
|
|
11
|
+
"oauth",
|
|
12
|
+
"dcr",
|
|
13
|
+
"pkce",
|
|
14
|
+
"tool-calling",
|
|
15
|
+
"agent",
|
|
16
|
+
"ollama",
|
|
17
|
+
"c0mpute",
|
|
18
|
+
"infernet"
|
|
19
|
+
],
|
|
20
|
+
"license": "MIT",
|
|
21
|
+
"author": "Profullstack, Inc.",
|
|
22
|
+
"repository": {
|
|
23
|
+
"type": "git",
|
|
24
|
+
"url": "git+https://github.com/profullstack/chat-plugins.git"
|
|
25
|
+
},
|
|
26
|
+
"homepage": "https://github.com/profullstack/chat-plugins#readme",
|
|
27
|
+
"bugs": {
|
|
28
|
+
"url": "https://github.com/profullstack/chat-plugins/issues"
|
|
29
|
+
},
|
|
30
|
+
"sideEffects": false,
|
|
31
|
+
"exports": {
|
|
32
|
+
".": {
|
|
33
|
+
"types": "./index.d.ts",
|
|
34
|
+
"import": "./src/index.js",
|
|
35
|
+
"default": "./src/index.js"
|
|
36
|
+
},
|
|
37
|
+
"./package.json": "./package.json"
|
|
38
|
+
},
|
|
39
|
+
"types": "./index.d.ts",
|
|
40
|
+
"files": [
|
|
41
|
+
"src",
|
|
42
|
+
"index.d.ts",
|
|
43
|
+
"README.md",
|
|
44
|
+
"LICENSE"
|
|
45
|
+
],
|
|
46
|
+
"scripts": {
|
|
47
|
+
"test": "bun test"
|
|
48
|
+
},
|
|
49
|
+
"engines": {
|
|
50
|
+
"node": ">=20"
|
|
51
|
+
},
|
|
52
|
+
"publishConfig": {
|
|
53
|
+
"access": "public"
|
|
54
|
+
}
|
|
55
|
+
}
|
package/src/catalog.js
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
// Built-in plugin catalog. Apps can pass their own list anywhere a catalog is taken.
|
|
2
|
+
|
|
3
|
+
import { slugify } from "./tools.js";
|
|
4
|
+
|
|
5
|
+
/** @type {readonly import("../index.js").CatalogEntry[]} */
|
|
6
|
+
export const CATALOG = Object.freeze([
|
|
7
|
+
Object.freeze({
|
|
8
|
+
slug: "c0mpute",
|
|
9
|
+
name: "c0mpute hosting",
|
|
10
|
+
url: "https://c0mpute.com/api/mcp",
|
|
11
|
+
description: "Host sites and apps on the c0mpute p2p network, check jobs, nodes and your balance.",
|
|
12
|
+
homepage: "https://c0mpute.com",
|
|
13
|
+
}),
|
|
14
|
+
Object.freeze({
|
|
15
|
+
slug: "threatcrush",
|
|
16
|
+
name: "ThreatCrush",
|
|
17
|
+
url: "https://threatcrush.com/api/mcp",
|
|
18
|
+
description: "File-hash, IP and domain reputation, plus your org's scan and pentest findings.",
|
|
19
|
+
homepage: "https://threatcrush.com",
|
|
20
|
+
}),
|
|
21
|
+
]);
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Merge a catalog override over the built-in list (same slug replaces; `false` url removes).
|
|
25
|
+
* @param {import("../index.js").CatalogEntry[]} [extra]
|
|
26
|
+
* @param {{ replace?: boolean }} [opts]
|
|
27
|
+
*/
|
|
28
|
+
export function makeCatalog(extra = [], opts = {}) {
|
|
29
|
+
/** @type {Map<string, import("../index.js").CatalogEntry>} */
|
|
30
|
+
const map = new Map();
|
|
31
|
+
if (!opts.replace) for (const e of CATALOG) map.set(e.slug, e);
|
|
32
|
+
for (const e of extra) {
|
|
33
|
+
if (!e || !e.slug) continue;
|
|
34
|
+
if (!e.url) map.delete(e.slug);
|
|
35
|
+
else map.set(e.slug, e);
|
|
36
|
+
}
|
|
37
|
+
return [...map.values()];
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Turn what a person typed after "/plugin add" into { slug, url, name, entry? }.
|
|
42
|
+
* Accepts a catalog slug ("c0mpute"), a catalog name, or a URL (scheme optional).
|
|
43
|
+
* @param {string} input
|
|
44
|
+
* @param {readonly import("../index.js").CatalogEntry[]} [catalog]
|
|
45
|
+
*/
|
|
46
|
+
export function resolvePluginInput(input, catalog = CATALOG) {
|
|
47
|
+
const raw = String(input || "").trim();
|
|
48
|
+
if (!raw) return null;
|
|
49
|
+
const lower = raw.toLowerCase();
|
|
50
|
+
const entry = catalog.find((e) => e.slug === lower || e.name.toLowerCase() === lower);
|
|
51
|
+
if (entry) return { slug: entry.slug, url: entry.url, name: entry.name, entry };
|
|
52
|
+
let url;
|
|
53
|
+
try {
|
|
54
|
+
url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `https://${raw}`);
|
|
55
|
+
} catch {
|
|
56
|
+
return null;
|
|
57
|
+
}
|
|
58
|
+
if (!url.hostname.includes(".") && url.hostname !== "localhost") return null;
|
|
59
|
+
const byUrl = catalog.find((e) => e.url.replace(/\/+$/, "") === url.toString().replace(/\/+$/, ""));
|
|
60
|
+
if (byUrl) return { slug: byUrl.slug, url: byUrl.url, name: byUrl.name, entry: byUrl };
|
|
61
|
+
const host = url.hostname.replace(/^(www|api|mcp)\./, "");
|
|
62
|
+
return { slug: slugify(host.split(".")[0] || host), url: url.toString(), name: host };
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* A slug not already taken: "foo", "foo-2", ...
|
|
67
|
+
* @param {string} base
|
|
68
|
+
* @param {Iterable<string>} taken
|
|
69
|
+
*/
|
|
70
|
+
export function uniqueSlug(base, taken) {
|
|
71
|
+
const set = new Set(taken);
|
|
72
|
+
const s = slugify(base);
|
|
73
|
+
if (!set.has(s)) return s;
|
|
74
|
+
for (let i = 2; i < 1000; i++) {
|
|
75
|
+
const c = `${s.slice(0, 28)}-${i}`;
|
|
76
|
+
if (!set.has(c)) return c;
|
|
77
|
+
}
|
|
78
|
+
return `${s.slice(0, 20)}-${Date.now().toString(36)}`;
|
|
79
|
+
}
|