@graphql-hive/plugin-mcp 0.1.2 → 0.2.0-alpha-f84f2ebaebc35f9053f541f46d4a82d268681d4c
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/CHANGELOG.md +99 -3
- package/README.md +69 -15
- package/dist/index-CF-7q_sH.d.ts +793 -0
- package/dist/index.cjs +79 -94
- package/dist/index.d.cts +13 -794
- package/dist/index.d.ts +13 -794
- package/dist/index.js +79 -94
- package/dist/loaders/hive.cjs +46 -0
- package/dist/loaders/hive.d.cts +67 -0
- package/dist/loaders/hive.d.ts +67 -0
- package/dist/loaders/hive.js +44 -0
- package/package.json +18 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,10 +1,106 @@
|
|
|
1
1
|
# @graphql-hive/plugin-mcp
|
|
2
2
|
|
|
3
|
-
## 0.
|
|
3
|
+
## 0.2.0-alpha-f84f2ebaebc35f9053f541f46d4a82d268681d4c
|
|
4
|
+
### Minor Changes
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
- [#2408](https://github.com/graphql-hive/gateway/pull/2408) [`26e3b93`](https://github.com/graphql-hive/gateway/commit/26e3b9354378c48032bc325e6fe069352ed28eb7) Thanks [@enisdenjo](https://github.com/enisdenjo)! - Add Hive Loader that fetches persisted GraphQL documents from a Hive App Deployments
|
|
9
|
+
|
|
10
|
+
Resolves app deployment manifest from Hive CDN, fetches every persisted document in that manifest, and returns them as a concatenated GraphQL operations string.
|
|
11
|
+
|
|
12
|
+
The MCP plugin parses the string, registers tools from operations carrying `@mcpTool` directives.
|
|
13
|
+
|
|
14
|
+
```typescript
|
|
15
|
+
import { createHiveLoader } from '@graphql-hive/plugin-mcp/loaders/hive';
|
|
16
|
+
|
|
17
|
+
useMCP(ctx, {
|
|
18
|
+
name: 'my-api',
|
|
19
|
+
loader: createHiveLoader(ctx, {
|
|
20
|
+
endpoint: 'https://cdn.graphql-hive.com/artifacts/v1/<target-id>',
|
|
21
|
+
accessToken: '<cdn-access-token>',
|
|
22
|
+
appDeployment: {
|
|
23
|
+
appName: 'my-app',
|
|
24
|
+
appVersion: '1.0.0',
|
|
25
|
+
},
|
|
26
|
+
}),
|
|
27
|
+
});
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
CDN failover with two endpoints - first is primary, second is fallback:
|
|
31
|
+
|
|
32
|
+
```typescript
|
|
33
|
+
createHiveLoader(ctx, {
|
|
34
|
+
endpoint: [
|
|
35
|
+
'https://cdn.graphql-hive.com/artifacts/v1/<target-id>',
|
|
36
|
+
'https://cdn-mirror.graphql-hive.com/artifacts/v1/<target-id>',
|
|
37
|
+
],
|
|
38
|
+
accessToken: '<cdn-access-token>',
|
|
39
|
+
appDeployment: { appName: 'my-app', appVersion: '1.0.0' },
|
|
40
|
+
});
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`appDeployment` can be a per-request function for multi-tenant setups where deployment varies by request:
|
|
44
|
+
|
|
45
|
+
```typescript
|
|
46
|
+
createHiveLoader(ctx, {
|
|
47
|
+
endpoint: 'https://cdn.graphql-hive.com/artifacts/v1/<target-id>',
|
|
48
|
+
accessToken: '<cdn-access-token>',
|
|
49
|
+
appDeployment: ({ request }) => ({
|
|
50
|
+
appName: request.headers.get('x-app-name'),
|
|
51
|
+
appVersion: request.headers.get('x-app-version'),
|
|
52
|
+
}),
|
|
53
|
+
});
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
When `appDeployment` is a function, manifest and documents are fetched on every request. Plugin-level string cache still applies - identical responses reuse cached `ToolRegistry`.
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
- [#2408](https://github.com/graphql-hive/gateway/pull/2408) [`af25b9b`](https://github.com/graphql-hive/gateway/commit/af25b9b339d2bfe23a5a35e5b80fefa64658183b) Thanks [@enisdenjo](https://github.com/enisdenjo)! - Operations loader is now per-request instead of startup-time
|
|
60
|
+
|
|
61
|
+
Previously `load()` was called once at startup and `onUpdate()` was called to push live changes. Now `load()` is called on every MCP request and `onUpdate` has been removed entirely.
|
|
62
|
+
|
|
63
|
+
Before:
|
|
64
|
+
|
|
65
|
+
```typescript
|
|
66
|
+
const loader: MCPOperationsLoader = {
|
|
67
|
+
async load() {
|
|
68
|
+
return fetchOperations();
|
|
69
|
+
},
|
|
70
|
+
onUpdate(callback) {
|
|
71
|
+
const interval = setInterval(async () => {
|
|
72
|
+
callback(await fetchOperations());
|
|
73
|
+
}, 30_000);
|
|
74
|
+
return () => clearInterval(interval);
|
|
75
|
+
},
|
|
76
|
+
};
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
After:
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
const loader: MCPOperationsLoader = {
|
|
83
|
+
async load({ request, serverContext }) {
|
|
84
|
+
return fetchOperations();
|
|
85
|
+
},
|
|
86
|
+
};
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`load()` now receives `{ request, serverContext }` so the operations source can vary per request (e.g. driven by a request header for multi-tenant setups).
|
|
90
|
+
|
|
91
|
+
Results are cached by the returned string: if `load()` returns the same source as a previous call the cached `ToolRegistry` is reused without rebuilding. The cache is cleared whenever the schema changes.
|
|
92
|
+
|
|
93
|
+
If `load()` throws, the plugin logs the error and falls back to the static tool registry for that request.
|
|
94
|
+
|
|
4
95
|
### Patch Changes
|
|
5
96
|
|
|
6
|
-
|
|
7
|
-
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
- [#2408](https://github.com/graphql-hive/gateway/pull/2408) [`1549213`](https://github.com/graphql-hive/gateway/commit/15492134d3483781208d7671aa7b39e478edf208) Thanks [@enisdenjo](https://github.com/enisdenjo)! - dependencies updates:
|
|
100
|
+
|
|
101
|
+
- Added dependency [`@graphql-hive/core@0.21.1-alpha-20260604213042-0d6112116193a921a379bbc3b917702c29368479` ↗︎](https://www.npmjs.com/package/@graphql-hive/core/v/0.21.1) (to `dependencies`)
|
|
102
|
+
- Added dependency [`@whatwg-node/promise-helpers@^1.3.2` ↗︎](https://www.npmjs.com/package/@whatwg-node/promise-helpers/v/1.3.2) (to `dependencies`)
|
|
103
|
+
- Added dependency [`@whatwg-node/server@^0.11.0` ↗︎](https://www.npmjs.com/package/@whatwg-node/server/v/0.11.0) (to `dependencies`)
|
|
8
104
|
|
|
9
105
|
## 0.1.1
|
|
10
106
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -362,34 +362,88 @@ resources: [
|
|
|
362
362
|
|
|
363
363
|
Agents discover resources via `resources/list` and fetch them with `resources/read`. Templates allow dynamic URIs with parameters.
|
|
364
364
|
|
|
365
|
+
### Hive App Deployment loader
|
|
366
|
+
|
|
367
|
+
The `createHiveLoader` function creates an `MCPOperationsLoader` that fetches persisted GraphQL documents from a [Hive App Deployment](https://the-guild.dev/graphql/hive/docs/features/app-deployments) on every MCP request.
|
|
368
|
+
|
|
369
|
+
```typescript
|
|
370
|
+
import { createGatewayRuntime } from '@graphql-hive/gateway-runtime';
|
|
371
|
+
import { useMCP } from '@graphql-hive/plugin-mcp';
|
|
372
|
+
import { createHiveLoader } from '@graphql-hive/plugin-mcp/loaders/hive';
|
|
373
|
+
|
|
374
|
+
const gateway = createGatewayRuntime({
|
|
375
|
+
supergraph: 'supergraph.graphql',
|
|
376
|
+
plugins: (ctx) => [
|
|
377
|
+
useMCP(ctx, {
|
|
378
|
+
name: 'my-api',
|
|
379
|
+
loader: createHiveLoader(ctx, {
|
|
380
|
+
endpoint:
|
|
381
|
+
'https://cdn.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688',
|
|
382
|
+
accessToken: 'hv2ZjUxNGUzN2MtNjVhNS0=',
|
|
383
|
+
appDeployment: {
|
|
384
|
+
appName: 'my-app',
|
|
385
|
+
appVersion: '1.0.0',
|
|
386
|
+
},
|
|
387
|
+
}),
|
|
388
|
+
}),
|
|
389
|
+
],
|
|
390
|
+
});
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
The loader resolves the app deployment manifest from the Hive CDN, then fetches every persisted document listed in that manifest. All documents are concatenated and returned as a single GraphQL operations string. The plugin parses that string, registers tools from any operations carrying `@mcpTool` directives, and caches the result so identical sources skip the rebuild.
|
|
394
|
+
|
|
395
|
+
If the manifest is not found or any document cannot be resolved, the loader throws and the plugin falls back to the static tool registry.
|
|
396
|
+
|
|
397
|
+
#### CDN failover
|
|
398
|
+
|
|
399
|
+
Pass two CDN endpoint URLs to automatically fall back to the second if the first fails:
|
|
400
|
+
|
|
401
|
+
```typescript
|
|
402
|
+
createHiveLoader(ctx, {
|
|
403
|
+
endpoint: [
|
|
404
|
+
'https://cdn.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688',
|
|
405
|
+
'https://cdn-mirror.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688',
|
|
406
|
+
],
|
|
407
|
+
accessToken: 'hv2ZjUxNGUzN2MtNjVhNS0=',
|
|
408
|
+
appDeployment: { appName: 'my-app', appVersion: '1.0.0' },
|
|
409
|
+
});
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
#### Dynamic app deployment
|
|
413
|
+
|
|
414
|
+
`appDeployment` can be a function that receives `{ request, serverContext }` and returns `{ appName, appVersion }`. Use this for multi-tenant setups where the deployment varies per request (for example, driven by a request header):
|
|
415
|
+
|
|
416
|
+
```typescript
|
|
417
|
+
createHiveLoader(ctx, {
|
|
418
|
+
endpoint:
|
|
419
|
+
'https://cdn.graphql-hive.com/artifacts/v1/9fb37bc4-e520-4019-843a-0c8698c25688',
|
|
420
|
+
accessToken: 'hv2ZjUxNGUzN2MtNjVhNS0=',
|
|
421
|
+
appDeployment: ({ request }) => ({
|
|
422
|
+
appName: request.headers.get('x-app-name'),
|
|
423
|
+
appVersion: request.headers.get('x-app-version'),
|
|
424
|
+
}),
|
|
425
|
+
});
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
> ⚠️ When `appDeployment` is a function, the loader fetches the manifest and all persisted documents on **every** MCP request. The plugin-level string cache still applies (identical responses reuse the cached `ToolRegistry`), but if the deployment config changes frequently you should add your own caching inside the function to avoid repeated CDN round-trips.
|
|
429
|
+
|
|
365
430
|
## Dynamic operations loader
|
|
366
431
|
|
|
367
|
-
Supply a custom `loader` to fetch operations from any external source
|
|
432
|
+
Supply a custom `loader` to fetch operations from any external source on every MCP request. The plugin handles parsing, tool registration, and caching.
|
|
368
433
|
|
|
369
434
|
```typescript
|
|
370
435
|
useMCP(ctx, {
|
|
371
436
|
name: 'my-api',
|
|
372
437
|
loader: {
|
|
373
|
-
async load() {
|
|
438
|
+
async load({ request, serverContext }) {
|
|
374
439
|
const res = await fetch('https://my-cdn.example.com/operations.graphql');
|
|
375
440
|
return res.text();
|
|
376
441
|
},
|
|
377
|
-
onUpdate(callback) {
|
|
378
|
-
const interval = setInterval(async () => {
|
|
379
|
-
const res = await fetch(
|
|
380
|
-
'https://my-cdn.example.com/operations.graphql',
|
|
381
|
-
);
|
|
382
|
-
callback(await res.text());
|
|
383
|
-
}, 60_000);
|
|
384
|
-
return () => clearInterval(interval);
|
|
385
|
-
},
|
|
386
442
|
},
|
|
387
443
|
});
|
|
388
444
|
```
|
|
389
445
|
|
|
390
|
-
The `load()` method is called
|
|
391
|
-
|
|
392
|
-
If `load()` rejects, the error is logged and `onUpdate` is not called. The plugin continues without loader-sourced operations. Implement retry logic inside `load()` if you need automatic recovery.
|
|
446
|
+
The `load()` method is called on every MCP request and receives `{ request, serverContext }`. If `load()` returns the same string as a previous call, the cached `ToolRegistry` is reused without rebuilding. If `load()` rejects, the error is logged and the plugin falls back to the static tool registry.
|
|
393
447
|
|
|
394
448
|
## Langfuse integration
|
|
395
449
|
|
|
@@ -514,7 +568,7 @@ The same precedence applies to per-field descriptions via `input.schema.properti
|
|
|
514
568
|
- **Resource templates**: dynamic URI-based resources with custom handlers
|
|
515
569
|
- **Annotations**: tool hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) and content annotations (`audience`, `priority`)
|
|
516
570
|
- **Task support**: per-tool `execution.taskSupport` (`'forbidden'`, `'optional'`, `'required'`) for long-running operations
|
|
517
|
-
- **Dynamic loader**: fetch operations from any external source with
|
|
571
|
+
- **Dynamic loader**: fetch operations from any external source per request with built-in string caching
|
|
518
572
|
|
|
519
573
|
## Examples
|
|
520
574
|
|