@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,49 @@
1
+ import type { TrustedManifest } from '@graxia/core';
2
+ import type { DocumentNode } from 'graphql';
3
+ /** A JSON Schema (2020-12) node, as plain JSON. */
4
+ export type JsonSchema = Record<string, unknown>;
5
+ /** One persisted operation, as `include` sees it. */
6
+ export interface McpOperationInfo {
7
+ /** The operation name (`BookById`). */
8
+ name: string;
9
+ kind: 'query' | 'mutation';
10
+ /** The id of its document in the manifest. */
11
+ id: string;
12
+ }
13
+ /** The `operations` option of `createMcp`: the persisted operations to expose as typed tools. */
14
+ export interface McpOperationsOptions {
15
+ /**
16
+ * The persisted documents, in any format `trustedDocuments.manifest` takes:
17
+ * `{ [id]: source }` (graphql-codegen `persisted-documents.json`, Relay
18
+ * `persisted-queries.json`), an Apollo persisted query manifest, or a `Map`.
19
+ * Every named query becomes a tool (`BookById` is `book_by_id`); mutations
20
+ * too with `mutations: true`; subscriptions are skipped.
21
+ */
22
+ documents: TrustedManifest;
23
+ /** Keeps an operation as a tool when it returns `true`. Absent: every operation. */
24
+ include?: (operation: McpOperationInfo) => boolean;
25
+ /**
26
+ * Tool descriptions by operation name. One wins over the description
27
+ * written on the operation itself (`"""…""" query BookById`); an operation
28
+ * with neither is a boot error.
29
+ */
30
+ descriptions?: Readonly<Record<string, string>>;
31
+ }
32
+ /** A typed tool, built once at `createMcp`. */
33
+ export interface OperationTool {
34
+ /** The tool name: the operation name in snake_case. */
35
+ name: string;
36
+ /** The operation name. */
37
+ title: string;
38
+ description: string;
39
+ kind: 'query' | 'mutation';
40
+ /** The manifest id of the document. */
41
+ id: string;
42
+ /** The document source, as the manifest holds it. */
43
+ source: string;
44
+ /** The parsed document, to check against a caller's view. */
45
+ document: DocumentNode;
46
+ inputSchema: JsonSchema;
47
+ outputSchema: JsonSchema;
48
+ }
49
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/operations/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,mDAAmD;AACnD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAChC,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC;IAC3B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;CACX;AAED,iGAAiG;AACjG,MAAM,WAAW,oBAAoB;IACpC;;;;;;OAMG;IACH,SAAS,EAAE,eAAe,CAAC;IAC3B,oFAAoF;IACpF,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACnD;;;;OAIG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAChD;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC7B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC;IAC3B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,EAAE,UAAU,CAAC;IACxB,YAAY,EAAE,UAAU,CAAC;CACzB"}
@@ -0,0 +1,16 @@
1
+ import { type Constraint } from '@graxia/core/agent';
2
+ import { type DocumentNode, type GraphQLSchema, type OperationDefinitionNode } from 'graphql';
3
+ /** What the places a variable is used at say about it. */
4
+ export interface VariableUsage {
5
+ /** The `@constraint` of each argument or input field the variable feeds. */
6
+ constraints: Constraint[];
7
+ /** The description of the first such argument or input field that has one. */
8
+ description?: string;
9
+ }
10
+ /**
11
+ * Where each variable of `operation` is used as a whole argument or input
12
+ * field value (in the operation and the fragments it reaches): the
13
+ * constraints and the description of those arguments and fields.
14
+ */
15
+ export declare function variableUsages(schema: GraphQLSchema, document: DocumentNode, operation: OperationDefinitionNode): Map<string, VariableUsage>;
16
+ //# sourceMappingURL=variable-usage.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"variable-usage.d.ts","sourceRoot":"","sources":["../../src/operations/variable-usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAgB,MAAM,oBAAoB,CAAC;AACnE,OAAO,EACN,KAAK,YAAY,EAIjB,KAAK,aAAa,EAIlB,KAAK,uBAAuB,EAI5B,MAAM,SAAS,CAAC;AAEjB,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC7B,4EAA4E;IAC5E,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAyBD;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,uBAAuB,GAChC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAgC5B"}
@@ -0,0 +1,10 @@
1
+ import type { View } from '../view.js';
2
+ import type { OperationTool } from './types.js';
3
+ /** The typed tools a caller may use: those whose operation is valid against the caller's view. */
4
+ export type VisibleTools = (view: View) => readonly OperationTool[];
5
+ /**
6
+ * Filters the tools by view, once per view: without `can` every caller
7
+ * shares one view, so the list is computed once; with `can` once per request.
8
+ */
9
+ export declare function createVisibleTools(tools: readonly OperationTool[]): VisibleTools;
10
+ //# sourceMappingURL=visible.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"visible.d.ts","sourceRoot":"","sources":["../../src/operations/visible.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,kGAAkG;AAClG,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,aAAa,EAAE,CAAC;AAEpE;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,SAAS,aAAa,EAAE,GAC7B,YAAY,CAYd"}
@@ -0,0 +1,116 @@
1
+ import type { Graxia, ServerContextArg } from '@graxia/core';
2
+ import type { Can } from '@graxia/core/agent';
3
+ import type { McpAuthInfo, McpAuthOptions } from './auth/types.js';
4
+ import type { McpOperationsOptions } from './operations/types.js';
5
+ /** Options of {@link createMcp}. */
6
+ export interface McpOptions<HostCtx extends object = Record<never, never>> {
7
+ /** The MCP server name, sent to clients as `serverInfo.name`. */
8
+ name: string;
9
+ /** The MCP server version, sent as `serverInfo.version`. Default `'0.0.0'`. */
10
+ version?: string;
11
+ /** Server instructions the client shows to the model: what this API is for. */
12
+ instructions?: string;
13
+ /**
14
+ * A factory, called once per request: it returns the permission check
15
+ * (`Can`) for that caller, from the request (a token, a session), the
16
+ * `serverContext` you passed to `fetch` and the verified token when `auth`
17
+ * is set (`auth` is undefined otherwise). It may be async. Absent: every
18
+ * field is visible.
19
+ *
20
+ * @example
21
+ * can: async (request) => {
22
+ * const roles = await rolesOf(request);
23
+ * return (permission) => roles.has(permission);
24
+ * },
25
+ */
26
+ can?: (request: Request, serverContext: HostCtx, auth?: McpAuthInfo) => Can | Promise<Can>;
27
+ /**
28
+ * Turn the endpoint into an OAuth 2.1 resource server: every request needs
29
+ * a bearer token your `verifyToken` accepts, issued for `resource`, with
30
+ * the read scope (`mcp:read`); `graphql_mutate` and the typed tools of
31
+ * mutations also need the write scope (`mcp:write`): without it they are
32
+ * not listed, and a call answers a 403 naming the tool. With `mutations`
33
+ * off they do not exist (`Tool … not found`).
34
+ * Serve `mcp.metadata` at `mcp.metadataPath`. Absent: no authentication
35
+ * here, put the endpoint behind your own.
36
+ */
37
+ auth?: McpAuthOptions;
38
+ /**
39
+ * List `graphql_mutate` and the typed tools of mutations. Default `false`:
40
+ * an agent that connects can read, not write.
41
+ */
42
+ mutations?: boolean;
43
+ /**
44
+ * Persisted operations as typed tools: each named operation of
45
+ * `operations.documents` is one tool (`BookById` is `book_by_id`) whose
46
+ * input schema comes from its variables and output schema from its
47
+ * selection set. An operation needs a description (its own, or
48
+ * `operations.descriptions`). A problem is a `GraxiaConfigError` at boot.
49
+ *
50
+ * @example
51
+ * createMcp(graxia, { name: 'library', operations: { documents: manifest } });
52
+ */
53
+ operations?: McpOperationsOptions;
54
+ /**
55
+ * List `graphql_query` and `graphql_mutate`. Default `true`. `false` keeps
56
+ * `graphql_schema` and the typed tools only, so an agent runs nothing but
57
+ * the operations you persisted; it needs `operations`. When graxia runs
58
+ * trusted documents in `strict` mode the two are never listed and a call
59
+ * is refused (`PERSISTED_QUERY_ONLY`), whatever this says.
60
+ */
61
+ genericTools?: boolean;
62
+ /**
63
+ * Browser origins (`https://app.example`) allowed to call the endpoint:
64
+ * their preflight is answered and their responses carry
65
+ * `Access-Control-Allow-Origin`. A request with no `Origin` header (a
66
+ * server, a CLI) is always allowed; a request with another origin is
67
+ * refused with a 403.
68
+ */
69
+ allowedOrigins?: readonly string[];
70
+ /**
71
+ * Hostnames (no port) a same-origin browser request may name in its `Host`
72
+ * header: the DNS-rebinding guard. Default `['localhost', '127.0.0.1',
73
+ * '[::1]']`. Set the public hostname(s) when the endpoint is not local.
74
+ */
75
+ allowedHosts?: readonly string[];
76
+ /**
77
+ * Receives an unexpected failure (a throwing `can`, a failing transport)
78
+ * with its cause; the agent only sees a generic message. Default
79
+ * `console.error`; `false` silences it.
80
+ */
81
+ onError?: ((error: unknown) => void) | false;
82
+ }
83
+ /** What {@link createMcp} returns. */
84
+ export interface Mcp<HostCtx extends object = Record<never, never>> {
85
+ /**
86
+ * Handles one MCP request (Streamable HTTP, stateless): a Web `Request` in,
87
+ * a `Response` out. Mount it in your own `Bun.serve` routes.
88
+ * `serverContext` goes to the `context` builder of every operation, like
89
+ * `graxia.fetch`'s; it is required when `HostCtx` has required keys.
90
+ * Never rejects.
91
+ */
92
+ fetch(request: Request, ...serverContext: ServerContextArg<HostCtx>): Promise<Response>;
93
+ /**
94
+ * Where to serve {@link Mcp.metadata}: `/.well-known/oauth-protected-resource`
95
+ * plus the path of `auth.resource` (RFC 9728). `undefined` without `auth`;
96
+ * `createMcp` types it `string` when it is given `auth`.
97
+ */
98
+ metadataPath: string | undefined;
99
+ /**
100
+ * The protected resource metadata (RFC 9728) as a route handler: GET answers
101
+ * the JSON document (CORS `*`, cached an hour), another method 405. Without
102
+ * `auth` it answers 404.
103
+ */
104
+ metadata(request: Request): Response;
105
+ /** Stops the handler: in-flight requests are aborted (like `graxia.dispose()`). */
106
+ dispose(): Promise<void>;
107
+ }
108
+ /**
109
+ * The graxia instance a server is built over: it runs the operations
110
+ * (`execute`), and gives the schema it serves, the limits it enforces and
111
+ * its trusted documents mode. A hand-made host must pass
112
+ * `trustedDocuments: graxia.trustedDocuments`: leaving it out would let
113
+ * strict trusted documents be switched off without a sign.
114
+ */
115
+ export type McpHost<HostCtx extends object> = Pick<Graxia<HostCtx>, 'execute' | 'schema' | 'limits' | 'trustedDocuments'>;
116
+ //# sourceMappingURL=options.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,oCAAoC;AACpC,MAAM,WAAW,UAAU,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC;IACxE,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,EAAE,CACL,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,OAAO,EACtB,IAAI,CAAC,EAAE,WAAW,KACd,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACxB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC;CAC7C;AAED,sCAAsC;AACtC,MAAM,WAAW,GAAG,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC;IACjE;;;;;;OAMG;IACH,KAAK,CACJ,OAAO,EAAE,OAAO,EAChB,GAAG,aAAa,EAAE,gBAAgB,CAAC,OAAO,CAAC,GACzC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACrB;;;;OAIG;IACH,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC;IACrC,mFAAmF;IACnF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,CAAC,OAAO,SAAS,MAAM,IAAI,IAAI,CACjD,MAAM,CAAC,OAAO,CAAC,EACf,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,kBAAkB,CACpD,CAAC"}
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Checks `allowedHosts` and `allowedOrigins` once, at `createMcp`: an entry
3
+ * the request check could never match (a host with a port, a scheme or a
4
+ * path; an origin with a trailing slash or a path) would only show up as a
5
+ * 403 on every browser call.
6
+ * @throws {GraxiaConfigError} naming the entry and the corrected value.
7
+ */
8
+ export declare function checkOriginOptions(allowedHosts: readonly string[] | undefined, allowedOrigins: readonly string[] | undefined): void;
9
+ //# sourceMappingURL=origin-options.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"origin-options.d.ts","sourceRoot":"","sources":["../src/origin-options.ts"],"names":[],"mappings":"AA4BA;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CACjC,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAC3C,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAC3C,IAAI,CAmBN"}
@@ -0,0 +1,18 @@
1
+ /** The allow-lists of the DNS-rebinding guard. */
2
+ export interface OriginPolicy {
3
+ allowedOrigins: readonly string[];
4
+ /** Hostnames without port; IPv6 in brackets. */
5
+ allowedHosts: readonly string[];
6
+ }
7
+ /** The hostnames allowed by default: the local ones. */
8
+ export declare const defaultHosts: () => string[];
9
+ /**
10
+ * The DNS-rebinding guard of the MCP spec. A request that carries an
11
+ * `Origin` passes only if the origin is in `allowedOrigins`, or it is the
12
+ * endpoint's own origin and the `Host` header names an `allowedHosts`
13
+ * hostname (an attacker's rebound domain is same-origin with itself, and
14
+ * fails there). No `Origin` (a server, a CLI) passes. Returns the refusal,
15
+ * or `undefined`.
16
+ */
17
+ export declare function checkOrigin(request: Request, policy: OriginPolicy): Response | undefined;
18
+ //# sourceMappingURL=origin.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"origin.d.ts","sourceRoot":"","sources":["../src/origin.ts"],"names":[],"mappings":"AAMA,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC5B,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,gDAAgD;IAChD,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,wDAAwD;AACxD,eAAO,MAAM,YAAY,QAAO,MAAM,EAAiC,CAAC;AAExE;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAC1B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,YAAY,GAClB,QAAQ,GAAG,SAAS,CAmBtB"}
@@ -0,0 +1,16 @@
1
+ import { type OriginPolicy } from './origin.js';
2
+ /** What the HTTP checks need. */
3
+ export interface PipelineSettings extends OriginPolicy {
4
+ maxBody: number;
5
+ }
6
+ /**
7
+ * The HTTP checks before the MCP handler, in order: origin and host (403),
8
+ * CORS preflight, method (405), the optional `gate` (authentication, before
9
+ * the body is read), content type (415) and body size (413). Resolves the
10
+ * refusal, or a copy of the request whose body is read with the gate's result.
11
+ */
12
+ export declare function admit<T = undefined>(request: Request, settings: PipelineSettings, gate?: (request: Request) => Promise<T | Response>): Promise<Response | {
13
+ request: Request;
14
+ gated: T | undefined;
15
+ }>;
16
+ //# sourceMappingURL=pipeline.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAG1D,iCAAiC;AACjC,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACrD,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,KAAK,CAAC,CAAC,GAAG,SAAS,EACxC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,GAAG,QAAQ,CAAC,GAChD,OAAO,CAAC,QAAQ,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,SAAS,CAAA;CAAE,CAAC,CAoBhE"}
@@ -0,0 +1,4 @@
1
+ import type { McpErrorCode } from './codes.js';
2
+ /** A JSON-RPC error response with a `fix`: what an MCP client gets when the request never reaches a tool. */
3
+ export declare function refusal(status: number, message: string, fix: string, headers?: HeadersInit, code?: McpErrorCode): Response;
4
+ //# sourceMappingURL=refusal.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"refusal.d.ts","sourceRoot":"","sources":["../src/refusal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,6GAA6G;AAC7G,wBAAgB,OAAO,CACtB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,WAAgB,EACzB,IAAI,CAAC,EAAE,YAAY,GACjB,QAAQ,CAaV"}
@@ -0,0 +1,28 @@
1
+ import { type McpServerFactory } from '@modelcontextprotocol/server';
2
+ import type { ResolvedAuth } from './auth/types.js';
3
+ import type { ContextCarrier } from './context.js';
4
+ import type { McpHost, McpOptions } from './options.js';
5
+ import type { ExecuteContext } from './tools/execute.js';
6
+ import type { Toolset } from './toolset.js';
7
+ /** The per-request pieces a tool call needs, once the request is known. */
8
+ export type RequestContext = Pick<ExecuteContext, 'graxia' | 'view' | 'serverContext' | 'headers' | 'signal' | 'writeScope' | 'onError'>;
9
+ /** The headers `graxia.execute` sees: the caller's (an `Authorization`, a session cookie), minus the transport's. */
10
+ export declare function forwardedHeaders(request: Request): Headers;
11
+ /** What {@link serverFactory} builds every request's server from. */
12
+ export interface ServerSettings {
13
+ graxia: McpHost<any>;
14
+ options: McpOptions<any>;
15
+ auth: ResolvedAuth | undefined;
16
+ carrier: ContextCarrier;
17
+ toolset: Toolset;
18
+ onError: (error: unknown) => void;
19
+ }
20
+ /**
21
+ * The SDK's per-request factory: the stateless server of one caller, from
22
+ * the state and the principal `fetch` put in their stores. `graphql_mutate`
23
+ * and the typed tools of mutations are registered when `mutations` is on
24
+ * and, with `auth`, the token has the write scope. A typed tool is
25
+ * registered only when the caller's view allows its operation.
26
+ */
27
+ export declare function serverFactory(settings: ServerSettings): McpServerFactory;
28
+ //# sourceMappingURL=server.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGhF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAgB,MAAM,WAAW,CAAC;AAM9D,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GAAG,IAAI,CAChC,cAAc,EACZ,QAAQ,GACR,MAAM,GACN,eAAe,GACf,SAAS,GACT,QAAQ,GACR,YAAY,GACZ,SAAS,CACX,CAAC;AAMF,qHAAqH;AACrH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAK1D;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACrB,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;IACzB,IAAI,EAAE,YAAY,GAAG,SAAS,CAAC;IAC/B,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAClC;AAiCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,gBAAgB,CAmCxE"}
@@ -0,0 +1,32 @@
1
+ import type { CallToolResult } from '@modelcontextprotocol/server';
2
+ import type { McpHost } from '../options.js';
3
+ import type { View } from '../view.js';
4
+ import { type Allowed } from './operation.js';
5
+ /** The input of `graphql_query` and `graphql_mutate`. */
6
+ export interface OperationInput {
7
+ query: string;
8
+ variables?: Record<string, unknown> | undefined;
9
+ operationName?: string | undefined;
10
+ }
11
+ /** What one call runs against. */
12
+ export interface ExecuteContext {
13
+ graxia: McpHost<any>;
14
+ /** The caller's view, built on first use. */
15
+ view: () => Promise<View>;
16
+ serverContext: object;
17
+ headers: Headers;
18
+ signal?: AbortSignal | undefined;
19
+ /** The scope `graphql_mutate` needs, when `auth` is on: named in the fix of a mutation sent to `graphql_query`. */
20
+ writeScope?: string | undefined;
21
+ /** Receives an unexpected failure with its cause. */
22
+ onError: (error: unknown) => void;
23
+ }
24
+ /** Runs one operation of the tool's `kind` through `graxia.execute`, after checking it against the caller's view. */
25
+ export declare function runOperation(kind: Allowed, input: OperationInput, context: ExecuteContext): Promise<CallToolResult>;
26
+ /** Runs a document through `graxia.execute` with the caller's headers and `serverContext`; graxia's refusals keep their code and fix. */
27
+ export declare function execute(context: ExecuteContext, operation: {
28
+ document: string;
29
+ variables?: Record<string, unknown> | undefined;
30
+ operationName?: string | undefined;
31
+ }): Promise<CallToolResult>;
32
+ //# sourceMappingURL=execute.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/tools/execute.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EACN,KAAK,OAAO,EAKZ,MAAM,aAAa,CAAC;AAGrB,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAChD,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACrB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC,mHAAmH;IACnH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,qDAAqD;IACrD,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAClC;AAsBD,qHAAqH;AACrH,wBAAsB,YAAY,CACjC,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,GACrB,OAAO,CAAC,cAAc,CAAC,CAsCzB;AAED,yIAAyI;AACzI,wBAAsB,OAAO,CAC5B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAChD,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC,GACC,OAAO,CAAC,cAAc,CAAC,CAiBzB"}
@@ -0,0 +1,8 @@
1
+ import type { CallToolResult } from '@modelcontextprotocol/server';
2
+ /** What an agent reads when the server failed: nothing about the server leaks. */
3
+ export declare const failed: () => CallToolResult;
4
+ /** An unexpected failure goes to `onError` with its cause; the agent gets a generic message, nothing about the server leaks. */
5
+ export declare function guarded(context: {
6
+ onError: (error: unknown) => void;
7
+ }, run: () => Promise<CallToolResult>): Promise<CallToolResult>;
8
+ //# sourceMappingURL=guard.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/tools/guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAGnE,kFAAkF;AAClF,eAAO,MAAM,MAAM,QAAO,cACoD,CAAC;AAE/E,gIAAgI;AAChI,wBAAsB,OAAO,CAC5B,OAAO,EAAE;IAAE,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAAE,EAC9C,GAAG,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,GAChC,OAAO,CAAC,cAAc,CAAC,CAOzB"}
@@ -0,0 +1,17 @@
1
+ import type { McpServer } from '@modelcontextprotocol/server';
2
+ import type { GenericTools } from '../toolset.js';
3
+ import { type ExecuteContext } from './execute.js';
4
+ /** What the tools need for one request. */
5
+ export interface ToolsInput {
6
+ context: ExecuteContext;
7
+ mutations: boolean;
8
+ /** How `graphql_query` and `graphql_mutate` stand. */
9
+ generic: GenericTools;
10
+ /** The request lists the tools: what is registered is what is advertised. */
11
+ listing: boolean;
12
+ /** The names of the typed tools this caller is offered, for the overview. */
13
+ typed: readonly string[];
14
+ }
15
+ /** Registers the generic tools on a per-request server. */
16
+ export declare function registerTools(server: McpServer, input: ToolsInput): void;
17
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,KAAK,cAAc,EAAgB,MAAM,WAAW,CAAC;AA6B9D,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IAC1B,OAAO,EAAE,cAAc,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,sDAAsD;IACtD,OAAO,EAAE,YAAY,CAAC;IACtB,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACzB;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAgDxE"}
@@ -0,0 +1,35 @@
1
+ import { type DocumentNode, FieldsOnCorrectTypeRule, KnownArgumentNamesRule, KnownTypeNamesRule, NoSchemaIntrospectionCustomRule, PossibleFragmentSpreadsRule } from 'graphql';
2
+ export type Allowed = 'query' | 'mutation';
3
+ /** The first `@defer` or `@stream` the document uses, without the `@`. */
4
+ export declare function incrementalDirective(document: DocumentNode): string | undefined;
5
+ /** A reason the document may not run here, as the message, code and fix an agent reads. */
6
+ export interface Refusal {
7
+ message: string;
8
+ code: string;
9
+ fix: string;
10
+ }
11
+ /**
12
+ * The validation rules MCP applies to the caller's view: only the ones that
13
+ * decide what the caller may see. Limits, cost and the rest of validation are
14
+ * graxia's, when the operation runs.
15
+ */
16
+ export declare const VIEW_RULES: readonly [typeof FieldsOnCorrectTypeRule, typeof KnownTypeNamesRule, typeof KnownArgumentNamesRule, typeof PossibleFragmentSpreadsRule, typeof NoSchemaIntrospectionCustomRule];
17
+ /** The fix of an introspection refusal: the view is read through `graphql_schema`. */
18
+ export declare const INTROSPECTION_FIX = "Use graphql_schema to read the schema.";
19
+ /**
20
+ * Parses `query` under graxia's token limit. A document that does not parse
21
+ * is refused here (fail closed): `graxia.execute` is never reached, so a
22
+ * lenient plugin parser cannot run what the MCP checks have not seen.
23
+ */
24
+ export declare function parseOperation(query: string, tokens: number | false): {
25
+ document: DocumentNode;
26
+ } | {
27
+ refusal: Refusal;
28
+ };
29
+ /**
30
+ * Refuses what MCP does not run: the selected operation when it is another
31
+ * kind than the tool's, and `@defer` / `@stream` (the result is one JSON value).
32
+ * `writeScope` is the scope `graphql_mutate` needs when `auth` is on, for the fix.
33
+ */
34
+ export declare function checkOperations(document: DocumentNode, allowed: Allowed, operationName?: string, writeScope?: string): Refusal | undefined;
35
+ //# sourceMappingURL=operation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"operation.d.ts","sourceRoot":"","sources":["../../src/tools/operation.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,YAAY,EACjB,uBAAuB,EAEvB,sBAAsB,EACtB,kBAAkB,EAClB,+BAA+B,EAE/B,2BAA2B,EAG3B,MAAM,SAAS,CAAC;AAEjB,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,UAAU,CAAC;AAE3C,0EAA0E;AAC1E,wBAAgB,oBAAoB,CACnC,QAAQ,EAAE,YAAY,GACpB,MAAM,GAAG,SAAS,CASpB;AAED,2FAA2F;AAC3F,MAAM,WAAW,OAAO;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,iLAMb,CAAC;AAEX,sFAAsF;AACtF,eAAO,MAAM,iBAAiB,2CAA2C,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,KAAK,GACpB;IAAE,QAAQ,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAkBnD;AAqCD;;;;GAIG;AACH,wBAAgB,eAAe,CAC9B,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,MAAM,EACtB,UAAU,CAAC,EAAE,MAAM,GACjB,OAAO,GAAG,SAAS,CAYrB"}
@@ -0,0 +1,13 @@
1
+ import type { CallToolResult } from '@modelcontextprotocol/server';
2
+ /** A GraphQL-shaped result, as plain JSON. */
3
+ export interface JsonResult {
4
+ data?: unknown;
5
+ errors?: readonly Record<string, unknown>[];
6
+ }
7
+ /** A tool result carrying a GraphQL result: `structuredContent` and its JSON as text; an error when there is no `data`. */
8
+ export declare function resultOf(result: JsonResult): CallToolResult;
9
+ /** A refused call, shaped like a GraphQL error (`extensions.code` and `extensions.fix`) so agents read it the same way. */
10
+ export declare function refused(message: string, code: string, fix: string): CallToolResult;
11
+ /** A plain text answer (the schema tool). */
12
+ export declare const textResult: (text: string, isError?: boolean) => CallToolResult;
13
+ //# sourceMappingURL=result.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/tools/result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CAC5C;AAED,2HAA2H;AAC3H,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAM3D;AAED,2HAA2H;AAC3H,wBAAgB,OAAO,CACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACT,cAAc,CAEhB;AAED,6CAA6C;AAC7C,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,EAAE,iBAAe,KAAG,cAGzD,CAAC"}