@frontmcp/plugin-codecall 1.9.6 → 1.10.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/README.md +141 -43
- package/esm/package.json +12 -8
- package/package.json +12 -8
package/README.md
CHANGED
|
@@ -1,70 +1,168 @@
|
|
|
1
1
|
# @frontmcp/plugin-codecall
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A FrontMCP plugin for servers with more tools than a model can usefully read. Instead of every tool and its schema,
|
|
4
|
+
`tools/list` shows CodeCall's meta-tools. The model searches your tools with `codecall:search`, reads the schemas of
|
|
5
|
+
the ones it picked with `codecall:describe`, and calls them: one at a time with `codecall:invoke`, or several in one
|
|
6
|
+
request with `codecall:execute`, which runs a short program written in AgentScript, a restricted subset of
|
|
7
|
+
JavaScript, in a sandbox on the server. A script can loop over results, filter and join them, so only the answer goes
|
|
8
|
+
back to the model.
|
|
4
9
|
|
|
5
|
-
|
|
10
|
+
[](https://www.npmjs.com/package/@frontmcp/plugin-codecall) [](https://github.com/agentfront/frontmcp/blob/main/LICENSE)
|
|
11
|
+
|
|
12
|
+
## Install
|
|
6
13
|
|
|
7
14
|
```bash
|
|
8
|
-
npm install @frontmcp/plugin-codecall @frontmcp/plugin-cache
|
|
15
|
+
npm install @frontmcp/plugin-codecall @frontmcp/plugin-cache @frontmcp/sdk
|
|
9
16
|
```
|
|
10
17
|
|
|
11
|
-
|
|
18
|
+
Requires Node.js 24 or later. [`@frontmcp/plugin-cache`](https://www.npmjs.com/package/@frontmcp/plugin-cache) is a
|
|
19
|
+
required peer dependency: install it next to this package, at the same version. CodeCall registers the cache plugin
|
|
20
|
+
itself, so you don't list it in `plugins`. Keep `@frontmcp/sdk` on the same version too.
|
|
21
|
+
|
|
22
|
+
For `embedding: { strategy: 'ml' }`, also install `@huggingface/transformers`, an optional peer dependency of
|
|
23
|
+
`vectoriadb`, which CodeCall uses for search.
|
|
12
24
|
|
|
13
25
|
## Usage
|
|
14
26
|
|
|
15
|
-
|
|
16
|
-
import { CachePlugin } from '@frontmcp/plugin-cache';
|
|
17
|
-
import { CodeCallPlugin } from '@frontmcp/plugin-codecall';
|
|
18
|
-
import { FrontMcp } from '@frontmcp/sdk';
|
|
27
|
+
Register the plugin with `init()`, in the `plugins` of an `@App` or of `@FrontMcp`:
|
|
19
28
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
}
|
|
29
|
+
```ts
|
|
30
|
+
import { CodeCallPlugin } from '@frontmcp/plugin-codecall';
|
|
31
|
+
import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
|
|
32
|
+
|
|
33
|
+
@Tool({
|
|
34
|
+
name: 'list_tickets',
|
|
35
|
+
description: 'List support tickets',
|
|
36
|
+
inputSchema: { status: z.enum(['open', 'closed']) },
|
|
37
|
+
})
|
|
38
|
+
class ListTickets extends ToolContext {
|
|
39
|
+
async execute({ status }: { status: 'open' | 'closed' }) {
|
|
40
|
+
return { tickets: [{ id: 'T-1', status, customerId: 'C-7' }] };
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
@Tool({ name: 'get_customer', description: 'Get a customer by id', inputSchema: { id: z.string() } })
|
|
45
|
+
class GetCustomer extends ToolContext {
|
|
46
|
+
async execute({ id }: { id: string }) {
|
|
47
|
+
return { id, name: 'Ada', plan: 'pro' };
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
@App({
|
|
52
|
+
id: 'help-desk',
|
|
53
|
+
name: 'Help Desk',
|
|
54
|
+
tools: [ListTickets, GetCustomer],
|
|
55
|
+
plugins: [CodeCallPlugin.init({ mode: 'codecall_only' })],
|
|
56
|
+
})
|
|
57
|
+
class HelpDeskApp {}
|
|
58
|
+
|
|
59
|
+
@FrontMcp({ info: { name: 'help-desk', version: '1.0.0' }, apps: [HelpDeskApp] })
|
|
60
|
+
export default class Server {}
|
|
23
61
|
```
|
|
24
62
|
|
|
25
|
-
|
|
63
|
+
`tools/list` now shows only the `codecall:*` tools. Registered on one app, CodeCall still hides every app's tools
|
|
64
|
+
(unless you set `appIds`), and its tools search and call every app's tools.
|
|
26
65
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
- **Tool Discovery**: Semantic search across available tools
|
|
30
|
-
- **Configurable Modes**: Control tool visibility and execution patterns
|
|
66
|
+
Every option is optional: `CodeCallPlugin.init()` and `plugins: [CodeCallPlugin]` use the defaults. `init()` checks
|
|
67
|
+
the options when your module is imported, and throws a `ZodError` naming a wrong one.
|
|
31
68
|
|
|
32
|
-
##
|
|
69
|
+
## The tools CodeCall adds
|
|
33
70
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
71
|
+
| Tool | What it does |
|
|
72
|
+
| -------------------------- | ------------------------------------------------------------- |
|
|
73
|
+
| `codecall:search` | Finds tools for short queries (`queries`: 1 to 10 phrases). |
|
|
74
|
+
| `codecall:describe` | Returns tools' input and output schemas, with usage examples. |
|
|
75
|
+
| `codecall:invoke` | Calls one tool and returns its result. |
|
|
76
|
+
| `codecall:execute` | Runs an AgentScript program that calls tools. |
|
|
77
|
+
| `codecall:searchSkills` | Finds skills that call tools. |
|
|
78
|
+
| `codecall:searchKnowledge` | Finds skills that are only instructions. |
|
|
38
79
|
|
|
39
|
-
|
|
80
|
+
They're listed in every mode, and neither `codecall:invoke` nor a script can call them.
|
|
40
81
|
|
|
41
|
-
|
|
42
|
-
|
|
82
|
+
## Modes
|
|
83
|
+
|
|
84
|
+
| `mode` | In `tools/list` | What CodeCall may use |
|
|
85
|
+
| --------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------- |
|
|
86
|
+
| `'codecall_only'` (default) | CodeCall's tools, and tools with `codecall: { visibleInListTools: true }` | Every tool, except those with `enabledInCodeCall: false` |
|
|
87
|
+
| `'codecall_opt_in'` | Every tool, except those with `visibleInListTools: false` | Only tools with `codecall: { enabledInCodeCall: true }` |
|
|
88
|
+
| `'metadata_driven'` | Every tool, except those with `visibleInListTools: false` | Every tool, except those with `enabledInCodeCall: false` |
|
|
89
|
+
|
|
90
|
+
A client that calls a tool CodeCall takes out of `tools/list` gets `Tool "…" not found` (`TOOL_NOT_FOUND`). Calls
|
|
91
|
+
from the server, through CodeCall's own tools or `this.callTool()`, still reach it. In `codecall_only`, a tool a
|
|
92
|
+
client or widget calls directly needs `visibleInListTools: true`.
|
|
93
|
+
|
|
94
|
+
The plugin adds a `codecall` field to `@Tool`:
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
@Tool({
|
|
98
|
+
name: 'delete_customer',
|
|
99
|
+
description: 'Delete a customer and all their tickets',
|
|
100
|
+
inputSchema: { id: z.string() },
|
|
101
|
+
codecall: { enabledInCodeCall: false, visibleInListTools: true },
|
|
102
|
+
})
|
|
103
|
+
```
|
|
43
104
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
105
|
+
## Options
|
|
106
|
+
|
|
107
|
+
| Option | Default | Description |
|
|
108
|
+
| ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
109
|
+
| `mode` | `'codecall_only'` | Which tools `tools/list` shows, and which CodeCall may use. See [Modes](#modes). |
|
|
110
|
+
| `appIds` | every app | In `codecall_only`, hide only these apps' tools from `tools/list`. It doesn't limit what CodeCall searches or calls. |
|
|
111
|
+
| `includeTools` | | `(tool) => boolean`. A tool it returns `false` for isn't searched, described, invoked or callable from scripts. |
|
|
112
|
+
| `directCalls` | unset | `{ enabled, allowedTools?, filter? }`, limits what `codecall:invoke` may call. |
|
|
113
|
+
| `vm` | `{ preset: 'secure' }` | The sandbox's limits: `preset` (`'locked_down'`, `'secure'`, `'balanced'`, `'experimental'`), `timeoutMs`, `maxSteps`, `allowLoops`, and others. |
|
|
114
|
+
| `embedding` | TF-IDF | How `codecall:search` ranks tools: `strategy` (`'tfidf'` or `'ml'`), `modelName`, `cacheDir`, `useHNSW`, `synonymExpansion`. |
|
|
115
|
+
| `sidecar` | `{ enabled: false }` | Allows scripts longer than 64 KB. |
|
|
116
|
+
| `topK` | `8` | Results per query when a `codecall:search` call doesn't give its own `topK`. |
|
|
117
|
+
| `maxDefinitions` | `8` | Most tools one `codecall:describe` call may name. |
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
CodeCallPlugin.init({
|
|
121
|
+
mode: 'codecall_opt_in',
|
|
122
|
+
directCalls: { enabled: true, allowedTools: ['get_customer'] },
|
|
123
|
+
vm: { preset: 'secure', timeoutMs: 3500 },
|
|
124
|
+
embedding: { strategy: 'ml' },
|
|
54
125
|
});
|
|
55
126
|
```
|
|
56
127
|
|
|
57
128
|
## Limits
|
|
58
129
|
|
|
59
|
-
- **
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
- **
|
|
130
|
+
- **Script time and calls.** Under the default `secure` preset, a script times out after 3.5 seconds (`vm.timeoutMs`)
|
|
131
|
+
and may call tools up to 5,000 times (`vm.maxSteps`). Loops are limited to `for…of`, and `for (…; …; …)` with
|
|
132
|
+
`vm.allowLoops: true`. The other presets set other limits.
|
|
133
|
+
- **Calls to one tool.** More than `vm.rapidEnumerationThreshold` calls (default 30) to one tool within about 2
|
|
134
|
+
seconds stop the script with `[RAPID_ENUMERATION]`; calls made through `parallel()` count. Set per-tool values with
|
|
135
|
+
`vm.rapidEnumerationOverrides` (`{ 'users:get': 100 }`). The sandbox's message says "in 5s", but it keeps only the
|
|
136
|
+
last 2 seconds of calls.
|
|
137
|
+
- **Embedding model.** With `embedding.strategy: 'ml'`, CodeCall loads a local model (`Xenova/all-MiniLM-L6-v2` by
|
|
138
|
+
default), downloading it into `embedding.cacheDir` if it isn't there. When the model can't be loaded or used
|
|
139
|
+
(offline with nothing cached, `@huggingface/transformers` missing, or embedding the tools fails), CodeCall logs one
|
|
140
|
+
warning and searches with TF-IDF. A tool whose metadata can't be read is skipped with a warning; the others stay
|
|
141
|
+
searchable.
|
|
142
|
+
|
|
143
|
+
## Docs
|
|
144
|
+
|
|
145
|
+
- [CodeCall reference](https://frontmcp.dev/reference/plugins/codecall): every option, the tools, AgentScript, the
|
|
146
|
+
sandbox's limits and security, with runnable examples
|
|
147
|
+
- [Letting the Model Write Code with CodeCall](https://frontmcp.dev/learn/letting-the-model-write-code-with-codecall):
|
|
148
|
+
a step-by-step lesson
|
|
149
|
+
- [CRM with CodeCall](https://frontmcp.dev/examples/crm-with-codecall): a whole server built on it
|
|
150
|
+
- [Plugins and adapters](https://frontmcp.dev/reference/plugins): where to register a plugin
|
|
151
|
+
|
|
152
|
+
## Related packages
|
|
153
|
+
|
|
154
|
+
- [`@frontmcp/sdk`](https://www.npmjs.com/package/@frontmcp/sdk): the framework this plugin extends
|
|
155
|
+
- [`@frontmcp/plugin-cache`](https://www.npmjs.com/package/@frontmcp/plugin-cache): a required peer dependency
|
|
156
|
+
- [`@frontmcp/plugin-skilled-openapi`](https://www.npmjs.com/package/@frontmcp/plugin-skilled-openapi): serves a
|
|
157
|
+
REST API as skills, which `codecall:searchSkills` finds
|
|
158
|
+
- [`@frontmcp/plugins`](https://www.npmjs.com/package/@frontmcp/plugins): a meta-package that re-exports this plugin
|
|
159
|
+
with three others
|
|
160
|
+
|
|
161
|
+
## Contributing
|
|
162
|
+
|
|
163
|
+
Source: [`plugins/plugin-codecall`](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-codecall). Issues
|
|
164
|
+
and pull requests are welcome; see [CONTRIBUTING.md](https://github.com/agentfront/frontmcp/blob/main/CONTRIBUTING.md).
|
|
67
165
|
|
|
68
166
|
## License
|
|
69
167
|
|
|
70
|
-
Apache-2.0
|
|
168
|
+
Apache-2.0. See [LICENSE](https://github.com/agentfront/frontmcp/blob/main/LICENSE).
|
package/esm/package.json
CHANGED
|
@@ -1,19 +1,22 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@frontmcp/plugin-codecall",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "CodeCall plugin for FrontMCP
|
|
3
|
+
"version": "1.10.0",
|
|
4
|
+
"description": "CodeCall plugin for FrontMCP: puts many tools behind search, describe, invoke and execute meta-tools, and runs scripts that call them in a sandbox",
|
|
5
5
|
"author": "AgentFront <info@agentfront.dev>",
|
|
6
6
|
"license": "Apache-2.0",
|
|
7
7
|
"engines": {
|
|
8
8
|
"node": ">=24.0.0"
|
|
9
9
|
},
|
|
10
10
|
"keywords": [
|
|
11
|
+
"frontmcp",
|
|
11
12
|
"mcp",
|
|
13
|
+
"model-context-protocol",
|
|
12
14
|
"codecall",
|
|
13
|
-
"orchestration",
|
|
14
15
|
"meta-tools",
|
|
16
|
+
"tool-search",
|
|
17
|
+
"agentscript",
|
|
18
|
+
"sandbox",
|
|
15
19
|
"plugin",
|
|
16
|
-
"frontmcp",
|
|
17
20
|
"agentfront"
|
|
18
21
|
],
|
|
19
22
|
"repository": {
|
|
@@ -50,16 +53,17 @@
|
|
|
50
53
|
"dependencies": {
|
|
51
54
|
"@enclave-vm/ast": "^2.16.0",
|
|
52
55
|
"@enclave-vm/core": "^2.16.0",
|
|
53
|
-
"@frontmcp/protocol": "1.
|
|
54
|
-
"@frontmcp/sdk": "1.9.6",
|
|
56
|
+
"@frontmcp/protocol": "1.10.0",
|
|
55
57
|
"acorn": "^8.15.0",
|
|
56
58
|
"vectoriadb": "^2.3.3"
|
|
57
59
|
},
|
|
58
60
|
"peerDependencies": {
|
|
59
|
-
"@frontmcp/lazy-zod": "1.
|
|
60
|
-
"@frontmcp/plugin-cache": "1.
|
|
61
|
+
"@frontmcp/lazy-zod": "1.10.0",
|
|
62
|
+
"@frontmcp/plugin-cache": "1.10.0",
|
|
63
|
+
"@frontmcp/sdk": "1.10.0"
|
|
61
64
|
},
|
|
62
65
|
"devDependencies": {
|
|
66
|
+
"@frontmcp/sdk": "1.10.0",
|
|
63
67
|
"reflect-metadata": "^0.2.2"
|
|
64
68
|
}
|
|
65
69
|
}
|
package/package.json
CHANGED
|
@@ -1,19 +1,22 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@frontmcp/plugin-codecall",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "CodeCall plugin for FrontMCP
|
|
3
|
+
"version": "1.10.0",
|
|
4
|
+
"description": "CodeCall plugin for FrontMCP: puts many tools behind search, describe, invoke and execute meta-tools, and runs scripts that call them in a sandbox",
|
|
5
5
|
"author": "AgentFront <info@agentfront.dev>",
|
|
6
6
|
"license": "Apache-2.0",
|
|
7
7
|
"engines": {
|
|
8
8
|
"node": ">=24.0.0"
|
|
9
9
|
},
|
|
10
10
|
"keywords": [
|
|
11
|
+
"frontmcp",
|
|
11
12
|
"mcp",
|
|
13
|
+
"model-context-protocol",
|
|
12
14
|
"codecall",
|
|
13
|
-
"orchestration",
|
|
14
15
|
"meta-tools",
|
|
16
|
+
"tool-search",
|
|
17
|
+
"agentscript",
|
|
18
|
+
"sandbox",
|
|
15
19
|
"plugin",
|
|
16
|
-
"frontmcp",
|
|
17
20
|
"agentfront"
|
|
18
21
|
],
|
|
19
22
|
"repository": {
|
|
@@ -50,16 +53,17 @@
|
|
|
50
53
|
"dependencies": {
|
|
51
54
|
"@enclave-vm/ast": "^2.16.0",
|
|
52
55
|
"@enclave-vm/core": "^2.16.0",
|
|
53
|
-
"@frontmcp/protocol": "1.
|
|
54
|
-
"@frontmcp/sdk": "1.9.6",
|
|
56
|
+
"@frontmcp/protocol": "1.10.0",
|
|
55
57
|
"acorn": "^8.15.0",
|
|
56
58
|
"vectoriadb": "^2.3.3"
|
|
57
59
|
},
|
|
58
60
|
"peerDependencies": {
|
|
59
|
-
"@frontmcp/lazy-zod": "1.
|
|
60
|
-
"@frontmcp/plugin-cache": "1.
|
|
61
|
+
"@frontmcp/lazy-zod": "1.10.0",
|
|
62
|
+
"@frontmcp/plugin-cache": "1.10.0",
|
|
63
|
+
"@frontmcp/sdk": "1.10.0"
|
|
61
64
|
},
|
|
62
65
|
"devDependencies": {
|
|
66
|
+
"@frontmcp/sdk": "1.10.0",
|
|
63
67
|
"reflect-metadata": "^0.2.2"
|
|
64
68
|
}
|
|
65
69
|
}
|