@frontmcp/plugins 0.8.1 → 0.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.
Files changed (3) hide show
  1. package/README.md +38 -238
  2. package/esm/package.json +5 -5
  3. package/package.json +5 -5
package/README.md CHANGED
@@ -1,271 +1,71 @@
1
- # FrontMCP Plugins
1
+ # @frontmcp/plugins
2
2
 
3
- Pluggable extensions for FrontMCP live here. Each plugin can contribute **providers**, **hooks**, and optional
4
- **adapters** that extend the platform.
3
+ Official plugin collection for FrontMCP servers.
5
4
 
6
- If you want to use a specific plugin, open that plugin’s README for full details. This page serves as an index and a
7
- contributor guide.
5
+ [![NPM](https://img.shields.io/npm/v/@frontmcp/plugins.svg)](https://www.npmjs.com/package/@frontmcp/plugins)
8
6
 
9
- ---
7
+ ## Install
10
8
 
11
- ## Table of contents
12
-
13
- - [Available plugins](#available-plugins)
14
- - [Quick start: enabling a plugin](#quick-start-enabling-a-plugin)
15
- - [Contributor guide: authoring a plugin](#contributor-guide-authoring-a-plugin)
16
- - [1) Recommended folder layout](#1-recommended-folder-layout)
17
- - [2) Export surface (`index.ts`)](#2-export-surface-indexts)
18
- - [3) Extend tool metadata](#3-extend-tool-metadata)
19
- - [4) Implementing the plugin class](#4-implementing-the-plugin-class)
20
- - [5) Initialization styles (`DynamicPlugin.init`)](#5-initialization-styles-dynamicplugininit)
21
- - [6) Hooks contributed by plugins](#6-hooks-contributed-by-plugins)
22
- - [7) Registering your plugin in an app](#7-registering-your-plugin-in-an-app)
23
- - [8) Documentation checklist](#8-documentation-checklist)
24
- - [9) Hook families & roadmap](#9-hook-families--roadmap)
25
- - [Contributing](#contributing)
26
- - [License](#license)
27
-
28
- ---
29
-
30
- ## Available plugins
31
-
32
- | Plugin | Description | Docs | Path |
33
- | ------ | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------------------------- |
34
- | Cache | Transparent caching for tool outputs keyed by input. Supports in-memory and Redis stores; per-tool TTL and sliding windows. | [Cache Plugin README](./src/cache/README.md) | [`src/cache`](./src/cache) |
35
-
36
- > For configuration and usage examples, follow the plugin’s own README.
37
-
38
- ---
39
-
40
- ## Quick start: enabling a plugin
41
-
42
- ```ts
43
- // app.ts
44
- import { App } from '@frontmcp/sdk';
45
- import { CachePlugin } from '@frontmcp/plugins';
46
-
47
- @App({
48
- id: 'my-app',
49
- name: 'My App',
50
- plugins: [
51
- CachePlugin, // or CachePlugin.init({...}) — see below for init styles
52
- ],
53
- })
54
- export default class MyApp {}
9
+ ```bash
10
+ npm install @frontmcp/plugins
55
11
  ```
56
12
 
57
- ---
13
+ Individual plugins are also available as standalone packages (`@frontmcp/plugin-cache`, etc.).
58
14
 
59
- ## Contributor guide: authoring a plugin
15
+ ## Available Plugins
60
16
 
61
- The sections below summarize structure, type augmentation, dynamic providers, and hooks.
17
+ | Plugin | Package | Description | Docs |
18
+ | ------------- | ---------------------------- | ------------------------------------------------------------------------------ | ---------------------------------- |
19
+ | **Cache** | `@frontmcp/plugin-cache` | Transparent tool output caching with in-memory and Redis stores, per-tool TTL | [Cache Plugin][docs-cache] |
20
+ | **Remember** | `@frontmcp/plugin-remember` | Session memory — `this.remember.set/get`, scoped storage, tool approval system | [Remember Plugin][docs-remember] |
21
+ | **CodeCall** | `@frontmcp/plugin-codecall` | Sandboxed code execution within tool flows | [CodeCall Plugin][docs-codecall] |
22
+ | **Dashboard** | `@frontmcp/plugin-dashboard` | Built-in admin dashboard for inspecting server state | [Dashboard Plugin][docs-dashboard] |
62
23
 
63
- ### 1) Recommended folder layout
64
-
65
- ```
66
- plugins/
67
- src/<your-plugin>/
68
- ├─ <your-plugin>.plugin.ts
69
- ├─ <your-plugin>.types.ts
70
- ├─ <your-plugin>.symbol.ts # optional, for DI tokens
71
- ├─ providers/ # optional, runtime providers
72
- │ └─ ...
73
- ├─ index.ts
74
- └─ README.md # user-facing docs
75
- ```
76
-
77
- > If your repo uses a monorepo layout like `libs/plugins/src/...`, keep the same structure under that root. Paths in
78
- > this README are relative to the current `plugins` folder.
79
-
80
- ### 2) Export surface (`index.ts`)
81
-
82
- At `src/<your-plugin>/index.ts`, re-export the plugin and its types:
83
-
84
- ```ts
85
- export { default } from './<your-plugin>.plugin';
86
- export * from './<your-plugin>.types';
87
- ```
88
-
89
- ### 3) Extend tool metadata
90
-
91
- If your plugin adds tool-level options (e.g., `cache`, `authorization`), augment the ambient
92
- `ExtendFrontMcpToolMetadata` interface so tool authors get type-safe metadata.
93
-
94
- ```ts
95
- // src/my-feature/my-feature.types.ts
96
-
97
- declare global {
98
- interface ExtendFrontMcpToolMetadata {
99
- /** Enables MyFeature for a tool; `true` uses plugin defaults. */
100
- myFeature?: MyFeatureToolOptions | true;
101
- }
102
- }
103
-
104
- export interface MyFeatureToolOptions {
105
- level?: 'low' | 'medium' | 'high';
106
- }
107
-
108
- export interface MyFeaturePluginOptions {
109
- /** Options provided at plugin registration time. */
110
- defaultLevel?: 'low' | 'medium' | 'high';
111
- }
112
- ```
113
-
114
- > Why: `declare global` merges into the ambient tool metadata used by `@Tool` / `tool(...)`, so TypeScript validates
115
- > options wherever tools are defined.
116
-
117
- ### 4) Implementing the plugin class
118
-
119
- Plugins are classes decorated with `@Plugin(...)`. For plugins that need configuration and/or generated providers,
120
- extend `DynamicPlugin<TOptions>` so you can support both value and factory initialization while contributing dynamic
121
- providers.
122
-
123
- ```ts
124
- // src/my-feature/my-feature.plugin.ts
125
- import { Plugin, DynamicPlugin, FlowHooksOf, FlowCtxOf, ProviderType } from '@frontmcp/sdk';
126
- import { MyFeaturePluginOptions } from './my-feature.types';
127
-
128
- const ToolHook = FlowHooksOf('tools:call-tool');
129
-
130
- @Plugin({
131
- name: 'plugin:my-feature',
132
- description: 'Does something useful',
133
- providers: [
134
- // Static providers that always load with the plugin (optional)
135
- // { provide: MyToken, useClass: MyProvider },
136
- ],
137
- })
138
- export default class MyFeaturePlugin extends DynamicPlugin<MyFeaturePluginOptions> {
139
- static defaultOptions: MyFeaturePluginOptions = {
140
- defaultLevel: 'medium',
141
- };
142
-
143
- // Contribute providers based on resolved options (runs before instance creation)
144
- static override dynamicProviders(options: MyFeaturePluginOptions): readonly ProviderType[] {
145
- const providers: ProviderType[] = [];
146
- // Decide implementations based on options
147
- // providers.push({ provide: MyToken, useValue: new MyProvider(options) });
148
- return providers;
149
- }
150
-
151
- constructor(public readonly options: MyFeaturePluginOptions = MyFeaturePlugin.defaultOptions) {
152
- super();
153
- }
154
-
155
- // Optional: register global tool hooks contributed by the plugin
156
- @ToolHook.Will('execute', { priority: 100 })
157
- async willExecute(ctx: FlowCtxOf<'tools:call-tool'>) {
158
- // Observe/mutate ctx.state.toolContext before tool execution
159
- }
160
- }
161
- ```
162
-
163
- ### 5) Initialization styles (`DynamicPlugin.init`)
164
-
165
- `DynamicPlugin` exposes a static `init()` so apps can register your plugin in different ways:
166
-
167
- - **Raw class** — zero-arg constructor only; no dynamic providers from options:
168
-
169
- ```ts
170
- plugins: [MyFeaturePlugin];
171
- ```
172
-
173
- - **Value style** — options known upfront; `dynamicProviders(options)` is evaluated and merged:
174
-
175
- ```ts
176
- plugins: [MyFeaturePlugin.init({ defaultLevel: 'high' })];
177
- ```
178
-
179
- - **Factory style** — compute options from app DI; then merge `dynamicProviders(realOptions)`:
180
-
181
- ```ts
182
- plugins: [
183
- MyFeaturePlugin.init({
184
- inject: () => [SomeConfig],
185
- useFactory: (cfg) => ({ defaultLevel: cfg.level }),
186
- }),
187
- ];
188
- ```
189
-
190
- Under the hood (high level):
191
-
192
- - Static providers from `@Plugin({ providers: [...] })` are merged first.
193
- - In **value**/**factory** styles, the registry evaluates `dynamicProviders(...)` and merges results.
194
- - Provider tokens are de-duplicated to avoid conflicts.
195
-
196
- > Implementation references (repository paths may vary): `libs/sdk/src/common/dynamic/dynamic.plugin.ts` and
197
- > `libs/sdk/src/plugin/plugin.registry.ts`.
198
-
199
- ### 6) Hooks contributed by plugins
200
-
201
- Plugins can register global hooks via `FlowHooksOf(...)`. The SDK exports helpers for the most common flows:
202
-
203
- ```ts
204
- import { ToolHook, ListToolsHook, HttpHook } from '@frontmcp/sdk';
205
-
206
- @ToolHook.Will('validateInput')
207
- async ensureConstraints(ctx: FlowCtxOf<'tools:call-tool'>) {
208
- // ...
209
- }
210
- ```
211
-
212
- Available hook families today include:
213
-
214
- - `ToolHook` (`tools:call-tool`) — observe or mutate tool execution.
215
- - `ListToolsHook` (`tools:list-tools`) — filter/augment the tool catalog during discovery.
216
- - `HttpHook` (`http:request`) — shape raw inbound HTTP requests before flow execution.
217
-
218
- Within each family you can register `Will`, `Stage`, `Did`, or `Around` hooks. Use `FlowCtxOf<'flow-name'>` to access
219
- typed context/state for that flow.
220
-
221
- See the cache example hooks in: [`src/cache/cache.plugin.ts`](./src/cache/cache.plugin.ts).
222
-
223
- ### 7) Registering your plugin in an app
24
+ ## Quick Start
224
25
 
225
26
  ```ts
226
27
  import { App } from '@frontmcp/sdk';
227
- import { MyFeaturePlugin } from '@frontmcp/plugins';
28
+ import { CachePlugin, RememberPlugin } from '@frontmcp/plugins';
228
29
 
229
30
  @App({
230
31
  id: 'my-app',
231
32
  name: 'My App',
232
33
  plugins: [
233
- MyFeaturePlugin, // or MyFeaturePlugin.init({...})
34
+ CachePlugin, // zero-config
35
+ RememberPlugin.init({ store: 'memory' }), // with options
234
36
  ],
235
37
  })
236
38
  export default class MyApp {}
237
39
  ```
238
40
 
239
- ### 8) Documentation checklist
41
+ Plugins support three registration styles:
240
42
 
241
- Each plugin must ship a `README.md` that explains:
43
+ - **Raw class** — `CachePlugin` (default options)
44
+ - **Value init** — `CachePlugin.init({ ttl: 60_000 })` (options known upfront)
45
+ - **Factory init** — `CachePlugin.init({ inject: () => [...], useFactory: (dep) => ({...}) })`
242
46
 
243
- - **What it does** and **when to use it**
244
- - **Installation & registration** examples (raw/value/factory)
245
- - **Configuration options** (plugin-level and tool-level)
246
- - **Providers** it contributes and any required external services
247
- - **Hooks** it adds and how they affect tool/app behavior
248
- - **Examples** (minimal and advanced)
47
+ > Full plugin guide: [Plugins Overview][docs-overview]
249
48
 
250
- For a concrete example, see the [Cache Plugin README](./src/cache/README.md).
49
+ ## Creating Your Own Plugin
251
50
 
252
- ### 9) Hook families & roadmap
51
+ Extend `DynamicPlugin<Options>`, decorate with `@Plugin(...)`, and contribute providers, hooks, or context extensions.
253
52
 
254
- The SDK currently exposes flow hooks for tools (`ToolHook`), tool discovery (`ListToolsHook`), and HTTP requests
255
- (`HttpHook`). More flows (auth, transports, adapters) will land iteratively. Design plugins so you can adopt new hook
256
- families by switching to `FlowHooksOf('<future-flow>')` as they ship.
53
+ > Step-by-step guide: [Creating Plugins][docs-creating]
257
54
 
258
- ---
55
+ ## Related Packages
259
56
 
260
- ## Contributing
57
+ - [`@frontmcp/sdk`](../sdk) — core framework and `DynamicPlugin` base class
58
+ - [`@frontmcp/testing`](../testing) — E2E testing for plugin-contributed tools
261
59
 
262
- 1. Create your plugin under `src/<your-plugin>/` following the layout above.
263
- 2. Include a thorough `README.md` in your plugin folder.
264
- 3. Add your plugin to the **Available plugins** table (name, short description, links).
265
- 4. Submit a PR with tests and lint passing.
60
+ ## License
266
61
 
267
- ---
62
+ Apache-2.0 — see [LICENSE](../../LICENSE).
268
63
 
269
- ## License
64
+ <!-- links -->
270
65
 
271
- This folder inherits the repository’s license unless otherwise noted in individual plugin folders.
66
+ [docs-overview]: https://docs.agentfront.dev/frontmcp/plugins/overview
67
+ [docs-cache]: https://docs.agentfront.dev/frontmcp/plugins/cache
68
+ [docs-remember]: https://docs.agentfront.dev/frontmcp/plugins/remember
69
+ [docs-codecall]: https://docs.agentfront.dev/frontmcp/plugins/codecall
70
+ [docs-dashboard]: https://docs.agentfront.dev/frontmcp/plugins/dashboard
71
+ [docs-creating]: https://docs.agentfront.dev/frontmcp/plugins/creating-plugins
package/esm/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@frontmcp/plugins",
3
- "version": "0.8.1",
3
+ "version": "0.10.0",
4
4
  "description": "FrontMCP plugins meta-package - installs all official plugins",
5
5
  "author": "AgentFront <info@agentfront.dev>",
6
6
  "homepage": "https://docs.agentfront.dev",
@@ -47,10 +47,10 @@
47
47
  "node": ">=22.0.0"
48
48
  },
49
49
  "dependencies": {
50
- "@frontmcp/plugin-cache": "0.8.1",
51
- "@frontmcp/plugin-codecall": "0.8.1",
52
- "@frontmcp/plugin-dashboard": "0.8.1",
53
- "@frontmcp/plugin-remember": "0.8.1"
50
+ "@frontmcp/plugin-cache": "0.10.0",
51
+ "@frontmcp/plugin-codecall": "0.10.0",
52
+ "@frontmcp/plugin-dashboard": "0.10.0",
53
+ "@frontmcp/plugin-remember": "0.10.0"
54
54
  },
55
55
  "devDependencies": {
56
56
  "reflect-metadata": "^0.2.2"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@frontmcp/plugins",
3
- "version": "0.8.1",
3
+ "version": "0.10.0",
4
4
  "description": "FrontMCP plugins meta-package - installs all official plugins",
5
5
  "author": "AgentFront <info@agentfront.dev>",
6
6
  "homepage": "https://docs.agentfront.dev",
@@ -47,10 +47,10 @@
47
47
  "node": ">=22.0.0"
48
48
  },
49
49
  "dependencies": {
50
- "@frontmcp/plugin-cache": "0.8.1",
51
- "@frontmcp/plugin-codecall": "0.8.1",
52
- "@frontmcp/plugin-dashboard": "0.8.1",
53
- "@frontmcp/plugin-remember": "0.8.1"
50
+ "@frontmcp/plugin-cache": "0.10.0",
51
+ "@frontmcp/plugin-codecall": "0.10.0",
52
+ "@frontmcp/plugin-dashboard": "0.10.0",
53
+ "@frontmcp/plugin-remember": "0.10.0"
54
54
  },
55
55
  "devDependencies": {
56
56
  "reflect-metadata": "^0.2.2"