@graxia/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.
Files changed (96) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +169 -2
  3. package/dist/auth/bearer.d.ts +17 -0
  4. package/dist/auth/bearer.d.ts.map +1 -0
  5. package/dist/auth/metadata.d.ts +8 -0
  6. package/dist/auth/metadata.d.ts.map +1 -0
  7. package/dist/auth/principal.d.ts +17 -0
  8. package/dist/auth/principal.d.ts.map +1 -0
  9. package/dist/auth/resolve.d.ts +4 -0
  10. package/dist/auth/resolve.d.ts.map +1 -0
  11. package/dist/auth/scopes.d.ts +14 -0
  12. package/dist/auth/scopes.d.ts.map +1 -0
  13. package/dist/auth/types.d.ts +70 -0
  14. package/dist/auth/types.d.ts.map +1 -0
  15. package/dist/body.d.ts +6 -0
  16. package/dist/body.d.ts.map +1 -0
  17. package/dist/calls.d.ts +14 -0
  18. package/dist/calls.d.ts.map +1 -0
  19. package/dist/codes.d.ts +21 -0
  20. package/dist/codes.d.ts.map +1 -0
  21. package/dist/context.d.ts +20 -0
  22. package/dist/context.d.ts.map +1 -0
  23. package/dist/cors.d.ts +7 -0
  24. package/dist/cors.d.ts.map +1 -0
  25. package/dist/create.d.ts +29 -0
  26. package/dist/create.d.ts.map +1 -0
  27. package/dist/index.d.ts +8 -0
  28. package/dist/index.d.ts.map +1 -0
  29. package/dist/index.js +1533 -0
  30. package/dist/index.js.map +45 -0
  31. package/dist/operations/build.d.ts +10 -0
  32. package/dist/operations/build.d.ts.map +1 -0
  33. package/dist/operations/constraint.d.ts +16 -0
  34. package/dist/operations/constraint.d.ts.map +1 -0
  35. package/dist/operations/documents.d.ts +13 -0
  36. package/dist/operations/documents.d.ts.map +1 -0
  37. package/dist/operations/input-schema.d.ts +12 -0
  38. package/dist/operations/input-schema.d.ts.map +1 -0
  39. package/dist/operations/input-type.d.ts +18 -0
  40. package/dist/operations/input-type.d.ts.map +1 -0
  41. package/dist/operations/naming.d.ts +5 -0
  42. package/dist/operations/naming.d.ts.map +1 -0
  43. package/dist/operations/output-schema.d.ts +11 -0
  44. package/dist/operations/output-schema.d.ts.map +1 -0
  45. package/dist/operations/problems.d.ts +27 -0
  46. package/dist/operations/problems.d.ts.map +1 -0
  47. package/dist/operations/register.d.ts +20 -0
  48. package/dist/operations/register.d.ts.map +1 -0
  49. package/dist/operations/types.d.ts +49 -0
  50. package/dist/operations/types.d.ts.map +1 -0
  51. package/dist/operations/variable-usage.d.ts +16 -0
  52. package/dist/operations/variable-usage.d.ts.map +1 -0
  53. package/dist/operations/visible.d.ts +10 -0
  54. package/dist/operations/visible.d.ts.map +1 -0
  55. package/dist/options.d.ts +116 -0
  56. package/dist/options.d.ts.map +1 -0
  57. package/dist/origin-options.d.ts +9 -0
  58. package/dist/origin-options.d.ts.map +1 -0
  59. package/dist/origin.d.ts +18 -0
  60. package/dist/origin.d.ts.map +1 -0
  61. package/dist/pipeline.d.ts +16 -0
  62. package/dist/pipeline.d.ts.map +1 -0
  63. package/dist/refusal.d.ts +4 -0
  64. package/dist/refusal.d.ts.map +1 -0
  65. package/dist/server.d.ts +28 -0
  66. package/dist/server.d.ts.map +1 -0
  67. package/dist/tools/execute.d.ts +32 -0
  68. package/dist/tools/execute.d.ts.map +1 -0
  69. package/dist/tools/guard.d.ts +8 -0
  70. package/dist/tools/guard.d.ts.map +1 -0
  71. package/dist/tools/index.d.ts +17 -0
  72. package/dist/tools/index.d.ts.map +1 -0
  73. package/dist/tools/operation.d.ts +35 -0
  74. package/dist/tools/operation.d.ts.map +1 -0
  75. package/dist/tools/result.d.ts +13 -0
  76. package/dist/tools/result.d.ts.map +1 -0
  77. package/dist/tools/schema.d.ts +319 -0
  78. package/dist/tools/schema.d.ts.map +1 -0
  79. package/dist/tools/strict.d.ts +12 -0
  80. package/dist/tools/strict.d.ts.map +1 -0
  81. package/dist/toolset.d.ts +30 -0
  82. package/dist/toolset.d.ts.map +1 -0
  83. package/dist/view-cache.d.ts +13 -0
  84. package/dist/view-cache.d.ts.map +1 -0
  85. package/dist/view.d.ts +16 -0
  86. package/dist/view.d.ts.map +1 -0
  87. package/docs/README.md +9 -0
  88. package/docs/guide/auth.md +247 -0
  89. package/docs/guide/getting-started.md +82 -0
  90. package/docs/guide/operations.md +221 -0
  91. package/docs/guide/security.md +122 -0
  92. package/docs/guide/tools.md +102 -0
  93. package/docs/roadmap.md +32 -0
  94. package/docs/troubleshooting-auth.md +101 -0
  95. package/docs/troubleshooting.md +205 -0
  96. package/package.json +71 -5
@@ -0,0 +1,319 @@
1
+ import { type View } from '../view.js';
2
+ /** The most types one `search` returns; the answer says when more matched. */
3
+ export declare const SEARCH_LIMIT = 50;
4
+ /** No input: what the caller can do, and the type names to ask about. */
5
+ export declare function overview(view: View, mutations: boolean, note?: string): {
6
+ [x: string]: unknown;
7
+ content: ({
8
+ type: "text";
9
+ text: string;
10
+ annotations?: {
11
+ audience?: ("user" | "assistant")[] | undefined;
12
+ priority?: number | undefined;
13
+ lastModified?: string | undefined;
14
+ } | undefined;
15
+ _meta?: {
16
+ [x: string]: unknown;
17
+ } | undefined;
18
+ } | {
19
+ type: "image";
20
+ data: string;
21
+ mimeType: string;
22
+ annotations?: {
23
+ audience?: ("user" | "assistant")[] | undefined;
24
+ priority?: number | undefined;
25
+ lastModified?: string | undefined;
26
+ } | undefined;
27
+ _meta?: {
28
+ [x: string]: unknown;
29
+ } | undefined;
30
+ } | {
31
+ type: "audio";
32
+ data: string;
33
+ mimeType: string;
34
+ annotations?: {
35
+ audience?: ("user" | "assistant")[] | undefined;
36
+ priority?: number | undefined;
37
+ lastModified?: string | undefined;
38
+ } | undefined;
39
+ _meta?: {
40
+ [x: string]: unknown;
41
+ } | undefined;
42
+ } | {
43
+ uri: string;
44
+ name: string;
45
+ type: "resource_link";
46
+ description?: string | undefined;
47
+ mimeType?: string | undefined;
48
+ size?: number | undefined;
49
+ annotations?: {
50
+ audience?: ("user" | "assistant")[] | undefined;
51
+ priority?: number | undefined;
52
+ lastModified?: string | undefined;
53
+ } | undefined;
54
+ _meta?: {
55
+ [x: string]: unknown;
56
+ } | undefined;
57
+ icons?: {
58
+ src: string;
59
+ mimeType?: string | undefined;
60
+ sizes?: string[] | undefined;
61
+ theme?: "light" | "dark" | undefined;
62
+ }[] | undefined;
63
+ title?: string | undefined;
64
+ } | {
65
+ type: "resource";
66
+ resource: {
67
+ uri: string;
68
+ text: string;
69
+ mimeType?: string | undefined;
70
+ _meta?: {
71
+ [x: string]: unknown;
72
+ } | undefined;
73
+ } | {
74
+ uri: string;
75
+ blob: string;
76
+ mimeType?: string | undefined;
77
+ _meta?: {
78
+ [x: string]: unknown;
79
+ } | undefined;
80
+ };
81
+ annotations?: {
82
+ audience?: ("user" | "assistant")[] | undefined;
83
+ priority?: number | undefined;
84
+ lastModified?: string | undefined;
85
+ } | undefined;
86
+ _meta?: {
87
+ [x: string]: unknown;
88
+ } | undefined;
89
+ })[];
90
+ _meta?: {
91
+ [x: string]: unknown;
92
+ "io.modelcontextprotocol/serverInfo"?: {
93
+ version: string;
94
+ name: string;
95
+ websiteUrl?: string | undefined;
96
+ description?: string | undefined;
97
+ icons?: {
98
+ src: string;
99
+ mimeType?: string | undefined;
100
+ sizes?: string[] | undefined;
101
+ theme?: "light" | "dark" | undefined;
102
+ }[] | undefined;
103
+ title?: string | undefined;
104
+ } | undefined;
105
+ } | undefined;
106
+ structuredContent?: unknown;
107
+ isError?: boolean | undefined;
108
+ };
109
+ /** `types`: the SDL of the named types; unknown names are listed with a fix. */
110
+ export declare function typesSdl(view: View, names: readonly string[], mutations: boolean): {
111
+ [x: string]: unknown;
112
+ content: ({
113
+ type: "text";
114
+ text: string;
115
+ annotations?: {
116
+ audience?: ("user" | "assistant")[] | undefined;
117
+ priority?: number | undefined;
118
+ lastModified?: string | undefined;
119
+ } | undefined;
120
+ _meta?: {
121
+ [x: string]: unknown;
122
+ } | undefined;
123
+ } | {
124
+ type: "image";
125
+ data: string;
126
+ mimeType: string;
127
+ annotations?: {
128
+ audience?: ("user" | "assistant")[] | undefined;
129
+ priority?: number | undefined;
130
+ lastModified?: string | undefined;
131
+ } | undefined;
132
+ _meta?: {
133
+ [x: string]: unknown;
134
+ } | undefined;
135
+ } | {
136
+ type: "audio";
137
+ data: string;
138
+ mimeType: string;
139
+ annotations?: {
140
+ audience?: ("user" | "assistant")[] | undefined;
141
+ priority?: number | undefined;
142
+ lastModified?: string | undefined;
143
+ } | undefined;
144
+ _meta?: {
145
+ [x: string]: unknown;
146
+ } | undefined;
147
+ } | {
148
+ uri: string;
149
+ name: string;
150
+ type: "resource_link";
151
+ description?: string | undefined;
152
+ mimeType?: string | undefined;
153
+ size?: number | undefined;
154
+ annotations?: {
155
+ audience?: ("user" | "assistant")[] | undefined;
156
+ priority?: number | undefined;
157
+ lastModified?: string | undefined;
158
+ } | undefined;
159
+ _meta?: {
160
+ [x: string]: unknown;
161
+ } | undefined;
162
+ icons?: {
163
+ src: string;
164
+ mimeType?: string | undefined;
165
+ sizes?: string[] | undefined;
166
+ theme?: "light" | "dark" | undefined;
167
+ }[] | undefined;
168
+ title?: string | undefined;
169
+ } | {
170
+ type: "resource";
171
+ resource: {
172
+ uri: string;
173
+ text: string;
174
+ mimeType?: string | undefined;
175
+ _meta?: {
176
+ [x: string]: unknown;
177
+ } | undefined;
178
+ } | {
179
+ uri: string;
180
+ blob: string;
181
+ mimeType?: string | undefined;
182
+ _meta?: {
183
+ [x: string]: unknown;
184
+ } | undefined;
185
+ };
186
+ annotations?: {
187
+ audience?: ("user" | "assistant")[] | undefined;
188
+ priority?: number | undefined;
189
+ lastModified?: string | undefined;
190
+ } | undefined;
191
+ _meta?: {
192
+ [x: string]: unknown;
193
+ } | undefined;
194
+ })[];
195
+ _meta?: {
196
+ [x: string]: unknown;
197
+ "io.modelcontextprotocol/serverInfo"?: {
198
+ version: string;
199
+ name: string;
200
+ websiteUrl?: string | undefined;
201
+ description?: string | undefined;
202
+ icons?: {
203
+ src: string;
204
+ mimeType?: string | undefined;
205
+ sizes?: string[] | undefined;
206
+ theme?: "light" | "dark" | undefined;
207
+ }[] | undefined;
208
+ title?: string | undefined;
209
+ } | undefined;
210
+ } | undefined;
211
+ structuredContent?: unknown;
212
+ isError?: boolean | undefined;
213
+ };
214
+ /** `search`: the SDL of the types whose name, description, field or value names and descriptions hold every word. */
215
+ export declare function searchSdl(view: View, search: string, mutations: boolean): {
216
+ [x: string]: unknown;
217
+ content: ({
218
+ type: "text";
219
+ text: string;
220
+ annotations?: {
221
+ audience?: ("user" | "assistant")[] | undefined;
222
+ priority?: number | undefined;
223
+ lastModified?: string | undefined;
224
+ } | undefined;
225
+ _meta?: {
226
+ [x: string]: unknown;
227
+ } | undefined;
228
+ } | {
229
+ type: "image";
230
+ data: string;
231
+ mimeType: string;
232
+ annotations?: {
233
+ audience?: ("user" | "assistant")[] | undefined;
234
+ priority?: number | undefined;
235
+ lastModified?: string | undefined;
236
+ } | undefined;
237
+ _meta?: {
238
+ [x: string]: unknown;
239
+ } | undefined;
240
+ } | {
241
+ type: "audio";
242
+ data: string;
243
+ mimeType: string;
244
+ annotations?: {
245
+ audience?: ("user" | "assistant")[] | undefined;
246
+ priority?: number | undefined;
247
+ lastModified?: string | undefined;
248
+ } | undefined;
249
+ _meta?: {
250
+ [x: string]: unknown;
251
+ } | undefined;
252
+ } | {
253
+ uri: string;
254
+ name: string;
255
+ type: "resource_link";
256
+ description?: string | undefined;
257
+ mimeType?: string | undefined;
258
+ size?: number | undefined;
259
+ annotations?: {
260
+ audience?: ("user" | "assistant")[] | undefined;
261
+ priority?: number | undefined;
262
+ lastModified?: string | undefined;
263
+ } | undefined;
264
+ _meta?: {
265
+ [x: string]: unknown;
266
+ } | undefined;
267
+ icons?: {
268
+ src: string;
269
+ mimeType?: string | undefined;
270
+ sizes?: string[] | undefined;
271
+ theme?: "light" | "dark" | undefined;
272
+ }[] | undefined;
273
+ title?: string | undefined;
274
+ } | {
275
+ type: "resource";
276
+ resource: {
277
+ uri: string;
278
+ text: string;
279
+ mimeType?: string | undefined;
280
+ _meta?: {
281
+ [x: string]: unknown;
282
+ } | undefined;
283
+ } | {
284
+ uri: string;
285
+ blob: string;
286
+ mimeType?: string | undefined;
287
+ _meta?: {
288
+ [x: string]: unknown;
289
+ } | undefined;
290
+ };
291
+ annotations?: {
292
+ audience?: ("user" | "assistant")[] | undefined;
293
+ priority?: number | undefined;
294
+ lastModified?: string | undefined;
295
+ } | undefined;
296
+ _meta?: {
297
+ [x: string]: unknown;
298
+ } | undefined;
299
+ })[];
300
+ _meta?: {
301
+ [x: string]: unknown;
302
+ "io.modelcontextprotocol/serverInfo"?: {
303
+ version: string;
304
+ name: string;
305
+ websiteUrl?: string | undefined;
306
+ description?: string | undefined;
307
+ icons?: {
308
+ src: string;
309
+ mimeType?: string | undefined;
310
+ sizes?: string[] | undefined;
311
+ theme?: "light" | "dark" | undefined;
312
+ }[] | undefined;
313
+ title?: string | undefined;
314
+ } | undefined;
315
+ } | undefined;
316
+ structuredContent?: unknown;
317
+ isError?: boolean | undefined;
318
+ };
319
+ //# sourceMappingURL=schema.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/tools/schema.ts"],"names":[],"mappings":"AAQA,OAAO,EAAoB,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAGtD,8EAA8E;AAC9E,eAAO,MAAM,YAAY,KAAK,CAAC;AAyB/B,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,SAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAajE;AAOD,gFAAgF;AAChF,wBAAgB,QAAQ,CACvB,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAclB;AAoBD,qHAAqH;AACrH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwBvE"}
@@ -0,0 +1,12 @@
1
+ import type { McpServer } from '@modelcontextprotocol/server';
2
+ /** The fix of a generic tool called on a strict server: the typed tools the caller has, or that there is none. */
3
+ export declare const strictFix: (typed: readonly string[]) => string;
4
+ /**
5
+ * graxia runs trusted documents in strict mode: a document an agent writes
6
+ * must not run, though `graxia.execute` (in process) would run it. So
7
+ * `graphql_query` and `graphql_mutate` only answer core's
8
+ * `PERSISTED_QUERY_ONLY` refusal. Register them for a request that calls
9
+ * tools and does not list them: they are never advertised.
10
+ */
11
+ export declare function registerStrictRefusals(server: McpServer, typed: readonly string[]): void;
12
+ //# sourceMappingURL=strict.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"strict.d.ts","sourceRoot":"","sources":["../../src/tools/strict.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAI9D,kHAAkH;AAClH,eAAO,MAAM,SAAS,GAAI,OAAO,SAAS,MAAM,EAAE,KAAG,MAGoD,CAAC;AAE1G;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,MAAM,EAAE,GACtB,IAAI,CAYN"}
@@ -0,0 +1,30 @@
1
+ import type { OperationTool } from './operations/types.js';
2
+ import type { McpHost, McpOptions } from './options.js';
3
+ import type { View } from './view.js';
4
+ /**
5
+ * How `graphql_query` and `graphql_mutate` stand: `on`, `off`
6
+ * (`genericTools: false`), or `refused` when graxia runs trusted documents
7
+ * in strict mode, where a document an agent writes must not run.
8
+ */
9
+ export type GenericTools = 'on' | 'off' | 'refused';
10
+ /** The tools of one `createMcp`, decided once at boot. */
11
+ export interface Toolset {
12
+ /** The typed tools of `operations`; empty without it. */
13
+ typed: readonly OperationTool[];
14
+ generic: GenericTools;
15
+ /** The typed tools a view allows. */
16
+ visible(view: View): readonly OperationTool[];
17
+ /**
18
+ * Whether `name` is a tool that writes and that this caller would be
19
+ * offered with the write scope: `graphql_mutate`, or the typed tool of a
20
+ * mutation the caller's view allows. A view that fails to build offers none.
21
+ */
22
+ writes(name: string, view: () => Promise<View>): Promise<boolean>;
23
+ }
24
+ /**
25
+ * Builds the tools of a server: the typed tools of `operations`, and how the
26
+ * generic ones stand.
27
+ * @throws {GraxiaConfigError} for a problem in `operations`, or `genericTools: false` with no typed tool.
28
+ */
29
+ export declare function createToolset(graxia: McpHost<any>, options: McpOptions<any>, mutations: boolean, onError: (error: unknown) => void): Toolset;
30
+ //# sourceMappingURL=toolset.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"toolset.d.ts","sourceRoot":"","sources":["../src/toolset.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEnC;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,KAAK,GAAG,SAAS,CAAC;AAEpD,0DAA0D;AAC1D,MAAM,WAAW,OAAO;IACvB,yDAAyD;IACzD,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,OAAO,EAAE,YAAY,CAAC;IACtB,qCAAqC;IACrC,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,aAAa,EAAE,CAAC;IAC9C;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClE;AAyBD;;;;GAIG;AACH,wBAAgB,aAAa,CAC5B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,EACpB,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,EACxB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAC/B,OAAO,CAkCT"}
@@ -0,0 +1,13 @@
1
+ import type { Can } from '@graxia/core/agent';
2
+ import type { GraphQLSchema } from 'graphql';
3
+ import type { McpAuthInfo } from './auth/types.js';
4
+ import { type View } from './view.js';
5
+ /** Builds the caller's view on first use, once per request: `fetch` asks for it only when the request lists or calls tools. */
6
+ export type ViewSource = (request: Request, serverContext: object, auth: McpAuthInfo | undefined) => () => Promise<View>;
7
+ /**
8
+ * Without `can` every caller sees the same schema, so the view is built once;
9
+ * with `can` it is built once per request that needs it (`tools/list`,
10
+ * `tools/call`), never for `initialize`, `ping` or a notification.
11
+ */
12
+ export declare function createViewSource(schema: GraphQLSchema, can: ((request: Request, serverContext: any, auth?: McpAuthInfo) => Can | Promise<Can>) | undefined): ViewSource;
13
+ //# sourceMappingURL=view-cache.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"view-cache.d.ts","sourceRoot":"","sources":["../src/view-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE9C,+HAA+H;AAC/H,MAAM,MAAM,UAAU,GAAG,CACxB,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,WAAW,GAAG,SAAS,KACzB,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAEzB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,aAAa,EACrB,GAAG,EACA,CAAC,CACD,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,GAAG,EAClB,IAAI,CAAC,EAAE,WAAW,KACb,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,GACxB,SAAS,GACV,UAAU,CAwBZ"}
package/dist/view.d.ts ADDED
@@ -0,0 +1,16 @@
1
+ import { type Can } from '@graxia/core/agent';
2
+ import { type GraphQLSchema } from 'graphql';
3
+ /** The schema as one caller may see it, with the SDL of each type ready to hand out. */
4
+ export interface View {
5
+ /** The visible schema: validate operations against it. */
6
+ schema: GraphQLSchema;
7
+ /** SDL of each visible type, by name, in schema order (descriptions and applied agent directives kept). */
8
+ types: ReadonlyMap<string, string>;
9
+ /** SDL of each directive definition the visible SDL declares, by name. */
10
+ directives: ReadonlyMap<string, string>;
11
+ }
12
+ /** Builds the view of a caller (`can` absent: everything). Walks the whole schema, so cache it per kind of caller. */
13
+ export declare function buildView(schema: GraphQLSchema, can?: Can): View;
14
+ /** The directive definitions that the SDL `texts` use, so the output is self-contained. */
15
+ export declare function directivesUsedBy(view: View, texts: readonly string[]): string[];
16
+ //# sourceMappingURL=view.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../src/view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAkB,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAGN,KAAK,aAAa,EAGlB,MAAM,SAAS,CAAC;AAEjB,wFAAwF;AACxF,MAAM,WAAW,IAAI;IACpB,0DAA0D;IAC1D,MAAM,EAAE,aAAa,CAAC;IACtB,2GAA2G;IAC3G,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,0EAA0E;IAC1E,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAKD,sHAAsH;AACtH,wBAAgB,SAAS,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,CAchE;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,SAAS,MAAM,EAAE,GACtB,MAAM,EAAE,CAKV"}
package/docs/README.md ADDED
@@ -0,0 +1,9 @@
1
+ # @graxia/mcp documentation
2
+
3
+ - [Getting started](./guide/getting-started.md): install, mount, connect a client, host context.
4
+ - [Tools](./guide/tools.md): `graphql_schema`, `graphql_query`, `graphql_mutate`, results and errors.
5
+ - [Persisted operations as typed tools](./guide/operations.md): `operations`, descriptions, the input and output schemas, `genericTools`.
6
+ - [OAuth resource server](./guide/auth.md): `auth`, the metadata, scopes and step-up, `mcpAuth()`.
7
+ - [Security](./guide/security.md): authentication, `can`, the Origin and Host checks, CORS, body size, trusted documents.
8
+ - [Troubleshooting](./troubleshooting.md): every error message and code, with its fix; the ones of `auth` are in [troubleshooting auth](./troubleshooting-auth.md).
9
+ - [Roadmap](./roadmap.md): what is coming. The effort-wide roadmap is [`docs/roadmap.md`](https://github.com/softistx/graxia/blob/develop/docs/roadmap.md).
@@ -0,0 +1,247 @@
1
+ # OAuth resource server
2
+
3
+ With `auth`, `@graxia/mcp` is an OAuth 2.1 **resource server** (MCP authorization spec, RFC 9728,
4
+ RFC 8707): it accepts bearer access tokens, it never issues them. Your authorization server does.
5
+
6
+ ## The flow
7
+
8
+ 1. The client calls `/mcp` with no token: **401** and
9
+ `WWW-Authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp", scope="mcp:read"`.
10
+ 2. It reads that metadata (`mcp.metadata`) and signs the user in at the authorization server it
11
+ names, asking for a token for this resource.
12
+ 3. It retries with `Authorization: Bearer <token>`.
13
+
14
+ ## Mount it
15
+
16
+ ```ts
17
+ import { createGraxia } from '@graxia/core';
18
+ import { createMcp } from '@graxia/mcp';
19
+
20
+ const graxia = createGraxia({ schema });
21
+ const mcp = createMcp(graxia, {
22
+ name: 'library',
23
+ mutations: true,
24
+ auth: {
25
+ resource: 'https://api.example.com/mcp',
26
+ authorizationServers: ['https://auth.example.com'],
27
+ verifyToken: async (token) => {
28
+ // your verifier (signature, issuer): it resolves undefined for a bad token, see below
29
+ const claims = await verifyJwt(token);
30
+ if (!claims) return undefined; // a 401
31
+ return {
32
+ subject: claims.sub,
33
+ clientId: claims.client_id,
34
+ scopes: claims.scope.split(' '),
35
+ expiresAt: claims.exp, // seconds
36
+ audience: claims.aud, // compared with `resource`
37
+ };
38
+ },
39
+ },
40
+ });
41
+
42
+ Bun.serve({
43
+ routes: {
44
+ [mcp.metadataPath]: mcp.metadata, // /.well-known/oauth-protected-resource/mcp
45
+ '/mcp': (request, server) => mcp.fetch(request, { server }),
46
+ },
47
+ fetch: graxia.fetch,
48
+ });
49
+ ```
50
+
51
+ `metadataPath` is the RFC 9728 well-known path with the path of `resource` inserted. It is typed
52
+ `string` when `auth` is passed to `createMcp`, and is `undefined` without it. `metadata` answers GET
53
+ with the JSON document (CORS `*`, `Cache-Control: max-age=3600`), any other method with a 405, and
54
+ a 404 without `auth`. `scopes_supported` lists the write scope only with `mutations: true`.
55
+
56
+ ## Options
57
+
58
+ | option | meaning |
59
+ | ---------------------- | -------------------------------------------------------------------------------- |
60
+ | `resource` | canonical URL of the endpoint, what tokens are issued for; no query, no fragment |
61
+ | `authorizationServers` | issuer URLs (absolute, at least one), published in the metadata |
62
+ | `verifyToken` | `(token, request) => McpAuthInfo \| Response \| undefined`, see below |
63
+ | `audience` | `'resource'` (default) or `'verifier'`: who checks the audience, see below |
64
+ | `scopes` | `{ read, write }`, default `mcp:read` and `mcp:write` |
65
+ | `resourceName` | `resource_name` of the metadata |
66
+ | `documentation` | `resource_documentation` of the metadata |
67
+
68
+ A wrong `resource` or `authorizationServers` throws at `createMcp`
69
+ ([troubleshooting auth](../troubleshooting-auth.md)).
70
+
71
+ ## `verifyToken`
72
+
73
+ It receives the token of `Authorization: Bearer <token>` and the request. It must read the
74
+ request's headers only, **never its body**: the body is read after the gate.
75
+
76
+ It resolves the token's `McpAuthInfo`, `undefined` for a token it does not accept, or a `Response`
77
+ when it builds its own refusals: that response is sent as is (plus the CORS headers of an allowed
78
+ origin). A **throw is an outage, not a bad token**: the client gets a 503 with `Retry-After: 5`
79
+ and the error goes to `onError`.
80
+
81
+ **Do not let a bad token throw.** Many JWT libraries reject an expired, badly signed or
82
+ wrong-audience token by throwing (jose's `jwtVerify` does). Passed through, every expired token
83
+ becomes a 503 the client retries for ever instead of a 401 it refreshes on, and each one reaches
84
+ `onError`. Catch the library's invalid-token errors and resolve `undefined`; let only real outages
85
+ (a JWKS fetch, an introspection call) throw:
86
+
87
+ ```ts
88
+ verifyToken: async (token) => {
89
+ let claims;
90
+ try {
91
+ claims = await verifyJwt(token); // throws InvalidTokenError, or a network error
92
+ } catch (error) {
93
+ if (error instanceof InvalidTokenError) return undefined; // a bad token: 401
94
+ throw error; // an outage: 503, retried
95
+ }
96
+ return { subject: claims.sub, scopes: claims.scope.split(' '), audience: claims.aud };
97
+ },
98
+ ```
99
+
100
+ Tell the two apart by the error's class, as above. With jose (`import { errors } from 'jose'`),
101
+ `errors.JWTExpired`, `JWTClaimValidationFailed`, `JWSSignatureVerificationFailed`, `JWTInvalid`,
102
+ `JWSInvalid`, `JWKSNoMatchingKey` and `JOSEAlgNotAllowed` are bad tokens; `JWKSTimeout` and a failed
103
+ fetch are outages. A bare `catch { return undefined }` would
104
+ hide an outage as a 401 and make clients sign in again for nothing.
105
+
106
+ `McpAuthInfo` is `{ subject?, clientId?, scopes, expiresAt?, audience?, extra? }`:
107
+
108
+ - `scopes` is required, an array (empty for none).
109
+ - `expiresAt` is optional and **in seconds** since the epoch (the `exp` claim). A value in
110
+ milliseconds, `NaN` or `Infinity` is refused.
111
+ - `audience` is the `aud` claim, a string or a list.
112
+
113
+ Only the `Bearer` scheme is read. **DPoP is not supported**: `Authorization: DPoP <token>` gets the
114
+ 401 of a missing token.
115
+
116
+ ## What is checked, in order
117
+
118
+ After the origin, host and method checks, and before the body is read:
119
+
120
+ | case | answer |
121
+ | --------------------------------------------- | ----------------------------------------------------------- |
122
+ | `access_token` in the query string | 400, `MCP_TOKEN_IN_URL` (OAuth 2.1 forbids it) |
123
+ | no `Authorization: Bearer` | 401, `MCP_UNAUTHORIZED`, challenge with `scope="mcp:read"` |
124
+ | `verifyToken` throws | 503, `Retry-After: 5`, `onError` |
125
+ | it resolves a `Response` | that response |
126
+ | it resolves `undefined` | 401, `error="invalid_token"` |
127
+ | no `scopes` array, or an unusable `expiresAt` | 401, `invalid_token`, and `onError` (a verifier bug) |
128
+ | `expiresAt` in the past | 401, `invalid_token` |
129
+ | no `audience`, or one without `resource` | 401, `invalid_token` (unless `audience: 'verifier'`) |
130
+ | token without the read scope | 403, `error="insufficient_scope"`, `MCP_INSUFFICIENT_SCOPE` |
131
+
132
+ Every refusal of graxia's is a JSON-RPC error with a `fix`. A preflight from an allowed origin
133
+ needs no token, and `WWW-Authenticate` is exposed to allowed origins.
134
+
135
+ ## Audience
136
+
137
+ A token issued for another service must never be accepted here, so the check is on by default:
138
+ `verifyToken` returns `audience`, and it must contain `resource` (a fragment and one trailing slash
139
+ are ignored). A token whose info has **no** `audience` is refused.
140
+
141
+ When your verifier already refuses tokens issued for another resource (an introspection endpoint
142
+ bound to this resource, a library that takes the resource as an option), say so:
143
+
144
+ ```ts
145
+ auth: { resource, authorizationServers, verifyToken, audience: 'verifier' },
146
+ ```
147
+
148
+ Nothing is compared then, and a returned `audience` is only handed to `can` and `mcpAuth()`.
149
+
150
+ ## Scopes and step-up
151
+
152
+ The read scope opens every tool but the ones that write: `graphql_mutate` and the
153
+ [typed tools](./operations.md) of mutations. Those are listed only when `mutations: true` **and**
154
+ the token has the write scope; a read-only token also gets an overview without the `Mutation`
155
+ root. A read-only token that calls one anyway (a stale tool list), alone or inside a JSON-RPC
156
+ batch, gets a **403** `error="insufficient_scope", scope="mcp:read mcp:write"` whose description
157
+ names the tool called (`rename_book needs the scope mcp:write`): the step-up challenge that tells
158
+ the client to re-authorize with both scopes. It is an HTTP answer, not a tool error (the SDK's
159
+ tool `scopeChallenge` cannot guard a tool that is not registered for that caller).
160
+
161
+ With `mutations` off there is no step-up, since no scope opens these tools: the call gets the
162
+ protocol's `Tool graphql_mutate not found` (`Tool rename_book not found`). A mutation tool that
163
+ `can` hides from the caller gets no step-up either: it answers like a tool that does not exist.
164
+
165
+ ## The principal
166
+
167
+ `can(request, serverContext, auth)` receives the verified `McpAuthInfo` as its third argument, so
168
+ the schema a caller sees can follow its scopes or roles.
169
+
170
+ `mcpAuth()` returns the same info anywhere during a tool call, for graxia's `context` builder and
171
+ resolvers, with no second verification. Outside a tool call, and during a call to an instance
172
+ without `auth`, it is `undefined`.
173
+
174
+ ```ts
175
+ import { mcpAuth } from '@graxia/mcp';
176
+
177
+ const graxia = createGraxia({
178
+ schema,
179
+ context: () => ({ userId: mcpAuth()?.subject }),
180
+ });
181
+ ```
182
+
183
+ The `Authorization` header is still forwarded to `graxia.execute`, so a context builder that
184
+ verifies tokens itself keeps working.
185
+
186
+ ## With `@softistx/janus-oauth`
187
+
188
+ `bearerCaller` resolves a request to its caller (an API key or an access token for the resource)
189
+ or to the `Response` to answer instead, so it is the whole verifier. No dependency is added to
190
+ `@graxia/mcp`.
191
+
192
+ ```ts
193
+ import {
194
+ type BearerCaller,
195
+ bearerCaller,
196
+ protectedResource,
197
+ } from '@softistx/janus-oauth';
198
+ import { createMcp, mcpAuth } from '@graxia/mcp';
199
+
200
+ const resource = 'https://api.example.com/mcp';
201
+ const issuer = 'https://auth.example.com';
202
+ // `accounts` is your janus() instance, `oauth` your authorization server.
203
+ const callerOf = bearerCaller({
204
+ accounts,
205
+ oauth,
206
+ resource: protectedResource({
207
+ resource,
208
+ issuer,
209
+ scopes: ['mcp:read', 'mcp:write'],
210
+ }),
211
+ });
212
+
213
+ const mcp = createMcp(graxia, {
214
+ name: 'library',
215
+ mutations: true,
216
+ auth: {
217
+ resource,
218
+ authorizationServers: [issuer],
219
+ audience: 'verifier', // bearerCaller refuses a token for another resource
220
+ verifyToken: async (_token, request) => {
221
+ const caller = await callerOf(request);
222
+ return caller instanceof Response
223
+ ? caller
224
+ : { subject: caller.userId, scopes: caller.scopes, extra: { caller } };
225
+ },
226
+ },
227
+ });
228
+
229
+ // In graxia's context builder: what the key or the grant is pinned to.
230
+ const context = () => {
231
+ const caller = mcpAuth()?.extra?.['caller'] as BearerCaller | undefined;
232
+ return {
233
+ userId: caller?.userId,
234
+ bound: caller?.bound ?? null,
235
+ authorizationDetails: caller?.authorizationDetails ?? [],
236
+ };
237
+ };
238
+ ```
239
+
240
+ - `protectedResource({ resource, scopes })` must use the **same URL** as `auth.resource`, and list
241
+ the read and the write scope (`mcp:read`, `mcp:write`, or your `auth.scopes`): an unscoped API
242
+ key holds exactly those.
243
+ - `bearerCaller`'s refusals (401 with its challenge, 503 on a store outage) are returned as they
244
+ are. It checks the expiry and the audience itself, hence no `expiresAt` and `audience: 'verifier'`.
245
+ - `verifyToken` must not read the request body: hand the request to `callerOf` untouched, it
246
+ authenticates from the headers.
247
+ - A DPoP-bound token is not accepted by `@graxia/mcp`; leave `dpop` off on `protectedResource`.