@graxia/mcp 0.0.0-stage → 0.1.1

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
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Softistx
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,170 @@
1
- # Temporary Holding Version
1
+ # @graxia/mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A Model Context Protocol server for a [graxia](https://github.com/softistx/graxia) API. An agent
4
+ (Claude, an IDE, any MCP client) connects over Streamable HTTP, reads the schema it is allowed to
5
+ see, and runs GraphQL operations through your server, with every graxia protection on: limits,
6
+ cost, trusted documents, error masking and rate limits.
7
+
8
+ > Without `auth` there is no authentication here: put the endpoint behind your own, or set `auth`
9
+ > to make it an OAuth resource server ([guide](./docs/guide/auth.md)). `can` decides which fields
10
+ > a caller sees. See [security](./docs/guide/security.md).
11
+
12
+ ## Install
13
+
14
+ ```sh
15
+ bun add @graxia/mcp @graxia/core graphql
16
+ ```
17
+
18
+ Requires Bun 1.4.4 or later and `@graxia/core` 0.5 or later.
19
+
20
+ The packages are ESM, built for Bun, and resolve with `"moduleResolution": "bundler"` in your
21
+ `tsconfig.json`. `nodenext` is not supported.
22
+
23
+ ## Mount it
24
+
25
+ ```ts
26
+ import { createGraxia } from '@graxia/core';
27
+ import { createMcp } from '@graxia/mcp';
28
+
29
+ // `schema` is the one from the core quick start
30
+ const graxia = createGraxia({ schema });
31
+ const mcp = createMcp(graxia, {
32
+ name: 'library',
33
+ instructions: 'Books and loans.',
34
+ });
35
+
36
+ Bun.serve({
37
+ routes: { '/mcp': (request, server) => mcp.fetch(request, { server }) },
38
+ fetch: graxia.fetch,
39
+ });
40
+ ```
41
+
42
+ Point an MCP client at `http://localhost:3000/mcp`. The server is stateless: no session id, `POST`
43
+ only (`GET` and `DELETE` answer 405).
44
+
45
+ ## Tools
46
+
47
+ | tool | listed | what it does |
48
+ | ---------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
49
+ | `graphql_schema` | always | operations and type names; `{ types }` gives SDL, `{ search }` finds types by a word |
50
+ | `graphql_query` | always (not in strict trusted-documents mode) | runs a query; mutations, subscriptions, introspection, `@defer` and `@stream` are refused |
51
+ | `graphql_mutate` | `mutations: true` (not in strict trusted-documents mode) | runs a mutation; a query is refused |
52
+
53
+ With `operations`, each persisted operation is one more tool (`book_by_id`), with typed arguments:
54
+ see [typed tools](#typed-tools).
55
+
56
+ Every tool answers with the GraphQL result as `structuredContent` (and its JSON as text); every
57
+ error carries `extensions.code` and `extensions.fix`. Details: [the tools guide](./docs/guide/tools.md).
58
+
59
+ ## Options
60
+
61
+ ```ts
62
+ createMcp(graxia, {
63
+ name: 'library', // serverInfo.name (required)
64
+ version: '1.0.0', // serverInfo.version, default '0.0.0'
65
+ instructions: 'Books and loans.', // shown to the model
66
+ can: async (request, serverContext, auth) => (permission) =>
67
+ permissions.has(permission), // auth: the verified token, with `auth` set
68
+ auth: {
69
+ // an OAuth resource server: see the auth guide
70
+ resource: 'https://mcp.example.com/mcp',
71
+ authorizationServers: ['https://auth.example.com'],
72
+ scopes: { read: 'mcp:read', write: 'mcp:write' }, // default
73
+ resourceName: 'Library', // shown by the metadata
74
+ documentation: 'https://docs.example.com/mcp', // `resource_documentation`
75
+ verifyToken: async (token, request) => verify(token), // McpAuthInfo | Response | undefined
76
+ audience: 'resource', // default: the info's audience must contain `resource`
77
+ },
78
+ mutations: true, // list graphql_mutate and the mutation typed tools, default false
79
+ operations: {
80
+ // persisted operations as typed tools: see the operations guide
81
+ documents: manifest, // core's TrustedManifest: codegen or Relay object, Apollo manifest, Map
82
+ include: (operation) => operation.kind === 'query', // { name, kind, id } => boolean
83
+ descriptions: { BookById: 'Find a book by its id.' }, // by operation name; wins over the document's
84
+ },
85
+ genericTools: false, // only graphql_schema and the typed tools, default true
86
+ allowedOrigins: ['https://app.example'], // browser origins: CORS and the origin check
87
+ allowedHosts: ['mcp.example.com'], // hostnames of the endpoint, default localhost
88
+ onError: (error) => logger.error(error), // default console.error
89
+ });
90
+ ```
91
+
92
+ ## Typed tools
93
+
94
+ ```ts
95
+ import { createGraxia } from '@graxia/core';
96
+ import { createMcp } from '@graxia/mcp';
97
+ import manifest from './persisted-documents.json';
98
+
99
+ // In the manifest: """Find a book by its id.""" query BookById($id: ID!) { book(id: $id) { id title } }
100
+ const graxia = createGraxia({ schema, trustedDocuments: { manifest } });
101
+ const mcp = createMcp(graxia, {
102
+ name: 'library',
103
+ operations: { documents: manifest },
104
+ });
105
+ ```
106
+
107
+ Each named query of the manifest is a tool (`BookById` → `book_by_id`; mutations with
108
+ `mutations: true`; subscriptions are skipped) whose input schema comes from the operation's
109
+ variables (types, defaults, `@constraint`) and whose output schema comes from its selection set. The
110
+ agent sends arguments, not GraphQL. With trusted documents in `strict` mode these are the only tools
111
+ that run operations: `graphql_query` and `graphql_mutate` are not listed and refuse a call. Every
112
+ operation needs a description (`"""…"""` above it, or `descriptions`); `createMcp` throws one error
113
+ listing every problem of the manifest, each with its fix. See
114
+ [the operations guide](./docs/guide/operations.md).
115
+
116
+ ## OAuth
117
+
118
+ ```ts
119
+ import { createGraxia } from '@graxia/core';
120
+ import { createMcp, mcpAuth } from '@graxia/mcp';
121
+
122
+ // `schema` is the one from the core quick start. `verifyJwt` is your token check (signature and
123
+ // issuer): it resolves the claims, and must resolve undefined for a bad token, not throw
124
+ // (a throw is an outage: a 503 the client retries).
125
+ const graxia = createGraxia({
126
+ schema,
127
+ context: () => ({ userId: mcpAuth()?.subject }), // the verified token, in a tool call
128
+ });
129
+ const mcp = createMcp(graxia, {
130
+ name: 'library',
131
+ mutations: true,
132
+ auth: {
133
+ resource: 'https://api.example.com/mcp', // the public URL of the endpoint
134
+ authorizationServers: ['https://auth.example.com'],
135
+ verifyToken: async (token) => {
136
+ const claims = await verifyJwt(token);
137
+ if (!claims) return undefined; // a 401
138
+ return {
139
+ subject: claims.sub,
140
+ scopes: claims.scope.split(' '),
141
+ expiresAt: claims.exp, // seconds
142
+ audience: claims.aud, // must contain `resource`
143
+ };
144
+ },
145
+ },
146
+ });
147
+
148
+ Bun.serve({
149
+ routes: {
150
+ [mcp.metadataPath]: mcp.metadata, // RFC 9728 metadata
151
+ '/mcp': (request, server) => mcp.fetch(request, { server }),
152
+ },
153
+ fetch: graxia.fetch,
154
+ });
155
+ ```
156
+
157
+ A request without a valid bearer token with `mcp:read` is a 401 with a `WWW-Authenticate`
158
+ challenge pointing at the metadata; `graphql_mutate` and the mutation typed tools need `mcp:write`. The token's audience is
159
+ checked against `resource` unless `audience: 'verifier'` says your verifier did it; a verifier
160
+ that throws is a 503, and it may resolve its own `Response`. Bearer only, no DPoP. See
161
+ [the auth guide](./docs/guide/auth.md).
162
+
163
+ ## Documentation
164
+
165
+ See [`docs/`](./docs): [getting started](./docs/guide/getting-started.md), [auth](./docs/guide/auth.md), [tools](./docs/guide/tools.md),
166
+ [typed tools](./docs/guide/operations.md),
167
+ [security](./docs/guide/security.md), [troubleshooting](./docs/troubleshooting.md)
168
+ ([auth errors](./docs/troubleshooting-auth.md)) and the
169
+ [roadmap](./docs/roadmap.md). The schema and the body limit come from the graxia instance
170
+ (`graxia.schema`, `graxia.limits`, core 0.5).
@@ -0,0 +1,17 @@
1
+ import type { McpAuthInfo, ResolvedAuth } from './types.js';
2
+ /** `WWW-Authenticate: Bearer ...` with the metadata URL, per RFC 6750 and 9728. */
3
+ export declare function challenge(auth: ResolvedAuth, params: {
4
+ error?: string;
5
+ description?: string;
6
+ scope?: string;
7
+ }): string;
8
+ /**
9
+ * The bearer gate: resolves the verified token's info, or the answer to send
10
+ * instead (400 token in the query string, 401 missing or invalid token, 403
11
+ * missing read scope, 503 failing verifier, or the verifier's own `Response`).
12
+ * Runs before the body is read.
13
+ */
14
+ export declare function authenticate(request: Request, auth: ResolvedAuth, onError: (error: unknown) => void): Promise<McpAuthInfo | Response>;
15
+ /** The 403 `insufficient_scope` answer, naming the full scope set the token needs. */
16
+ export declare function insufficient(auth: ResolvedAuth, scopes: readonly string[], description: string): Response;
17
+ //# sourceMappingURL=bearer.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bearer.d.ts","sourceRoot":"","sources":["../../src/auth/bearer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEzD,mFAAmF;AACnF,wBAAgB,SAAS,CACxB,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9D,MAAM,CAQR;AA0GD;;;;;GAKG;AACH,wBAAsB,YAAY,CACjC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAC/B,OAAO,CAAC,WAAW,GAAG,QAAQ,CAAC,CAiCjC;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAC3B,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,WAAW,EAAE,MAAM,GACjB,QAAQ,CAeV"}
@@ -0,0 +1,8 @@
1
+ import type { ResolvedAuth } from './types.js';
2
+ /**
3
+ * The RFC 9728 protected resource metadata handler: GET only, CORS `*`,
4
+ * cached an hour. The write scope is published only when `mutations` is on:
5
+ * without it no tool needs that scope.
6
+ */
7
+ export declare function metadataHandler(auth: ResolvedAuth | undefined, mutations: boolean): (request: Request) => Response;
8
+ //# sourceMappingURL=metadata.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/auth/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI5C;;;;GAIG;AACH,wBAAgB,eAAe,CAC9B,IAAI,EAAE,YAAY,GAAG,SAAS,EAC9B,SAAS,EAAE,OAAO,GAChB,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,CAsChC"}
@@ -0,0 +1,17 @@
1
+ import type { McpAuthInfo } from './types.js';
2
+ /**
3
+ * Runs `fn` with `info` as the verified principal (`mcpAuth()` reads it).
4
+ * `undefined` is stored too, so an instance without `auth` called from inside
5
+ * another instance's tool call does not see that one's principal.
6
+ */
7
+ export declare function runAs<T>(info: McpAuthInfo | undefined, fn: () => T): T;
8
+ /**
9
+ * The verified token of the MCP request being handled, for graxia's `context`
10
+ * builder and resolvers: the verification already happened, do not repeat it.
11
+ * `undefined` outside a tool call, and when `createMcp` has no `auth`.
12
+ *
13
+ * @example
14
+ * createGraxia({ schema, context: () => ({ user: mcpAuth()?.subject }) });
15
+ */
16
+ export declare function mcpAuth(): McpAuthInfo | undefined;
17
+ //# sourceMappingURL=principal.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"principal.d.ts","sourceRoot":"","sources":["../../src/auth/principal.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtE;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,IAAI,WAAW,GAAG,SAAS,CAEjD"}
@@ -0,0 +1,4 @@
1
+ import type { McpAuthOptions, ResolvedAuth } from './types.js';
2
+ /** Validates `auth` once, at `createMcp`, and derives what every request needs. */
3
+ export declare function resolveAuth(options: McpAuthOptions): ResolvedAuth;
4
+ //# sourceMappingURL=resolve.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/auth/resolve.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5D,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY,CA8BjE"}
@@ -0,0 +1,14 @@
1
+ import type { McpAuthInfo, ResolvedAuth } from './types.js';
2
+ /** Whether the token may call the tools that write (`graphql_mutate`, a mutation's typed tool). */
3
+ export declare const canWrite: (auth: ResolvedAuth, info: McpAuthInfo) => boolean;
4
+ /**
5
+ * Step-up: a read-only token that calls a tool that writes (`graphql_mutate`
6
+ * or a mutation's typed tool, from a stale tool list) gets the 403
7
+ * `insufficient_scope` naming `read write`, so a client can re-authorize.
8
+ * `writes` says whether the write scope would open the tool to this caller:
9
+ * a tool the caller's view hides gets no 403, so it answers like an unknown
10
+ * one. Only when the server has mutations on: otherwise no scope would help,
11
+ * and the call gets the SDK's tool-not-found.
12
+ */
13
+ export declare function writeStepUp(auth: ResolvedAuth, info: McpAuthInfo, called: readonly string[], writes: (name: string) => Promise<boolean>): Promise<Response | undefined>;
14
+ //# sourceMappingURL=scopes.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/auth/scopes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEzD,mGAAmG;AACnG,eAAO,MAAM,QAAQ,GAAI,MAAM,YAAY,EAAE,MAAM,WAAW,KAAG,OAChC,CAAC;AAElC;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAChC,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GACxC,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAU/B"}
@@ -0,0 +1,70 @@
1
+ /** What a verified access token says about its caller. */
2
+ export interface McpAuthInfo {
3
+ /** Who the token is for (`sub`). */
4
+ subject?: string | undefined;
5
+ /** The OAuth client the token was issued to. */
6
+ clientId?: string | undefined;
7
+ /** The scopes the token carries. */
8
+ scopes: readonly string[];
9
+ /**
10
+ * When the token expires, in seconds since the epoch (the `exp` claim, not
11
+ * `Date.now()`). A past value is refused, and so is one that is not a finite
12
+ * number or looks like milliseconds.
13
+ */
14
+ expiresAt?: number | undefined;
15
+ /**
16
+ * The resource(s) the token was issued for (`aud`, RFC 8707). It must contain
17
+ * `auth.resource`; a token without it is refused, unless `auth.audience` is
18
+ * `'verifier'`.
19
+ */
20
+ audience?: string | readonly string[] | undefined;
21
+ /** Anything else your verifier wants to hand to `can` and `mcpAuth()` (roles, a tenant...). */
22
+ extra?: Readonly<Record<string, unknown>> | undefined;
23
+ }
24
+ /** The scopes the server asks for: `read` for every call, `write` for `graphql_mutate`. */
25
+ export interface McpScopes {
26
+ /** Default `mcp:read`. */
27
+ read?: string;
28
+ /** Default `mcp:write`. */
29
+ write?: string;
30
+ }
31
+ /** The OAuth resource server settings of {@link McpOptions.auth}. */
32
+ export interface McpAuthOptions {
33
+ /** The canonical URI of this MCP server (RFC 8707 / 9728): what tokens are issued for, e.g. `https://api.example.com/mcp`. */
34
+ resource: string;
35
+ /** Issuer URLs of the authorization servers that issue tokens for this resource; published in the metadata. */
36
+ authorizationServers: readonly string[];
37
+ /**
38
+ * Verifies a bearer token (a JWT signature, an introspection call, a
39
+ * lookup). Resolve the token's {@link McpAuthInfo}, or `undefined` for an
40
+ * invalid token (a 401), or a `Response` to answer as is (a verifier that
41
+ * builds its own refusals). A throw is an outage, not a bad token: it is a
42
+ * 503 with `Retry-After: 5` and reaches `onError`. Read the headers of
43
+ * `request` only, never its body.
44
+ */
45
+ verifyToken: (token: string, request: Request) => McpAuthInfo | Response | undefined | Promise<McpAuthInfo | Response | undefined>;
46
+ /**
47
+ * Who checks the token's audience. Default `'resource'`: `verifyToken` must
48
+ * return `audience`, and it must contain `resource`. `'verifier'`: your
49
+ * verifier already refused a token issued for another resource, so nothing
50
+ * is checked here.
51
+ */
52
+ audience?: 'resource' | 'verifier';
53
+ /** The scopes to require; default `{ read: 'mcp:read', write: 'mcp:write' }`. */
54
+ scopes?: McpScopes;
55
+ /** `resource_name` of the metadata. */
56
+ resourceName?: string;
57
+ /** `resource_documentation` of the metadata (a URL). */
58
+ documentation?: string;
59
+ }
60
+ /** {@link McpAuthOptions} with defaults applied and the metadata URL computed. */
61
+ export interface ResolvedAuth {
62
+ options: McpAuthOptions;
63
+ read: string;
64
+ write: string;
65
+ /** The absolute URL of the protected resource metadata (RFC 9728). */
66
+ metadataUrl: string;
67
+ /** Its path, for the route. */
68
+ metadataPath: string;
69
+ }
70
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC3B,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,oCAAoC;IACpC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAClD,+FAA+F;IAC/F,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;CACtD;AAED,2FAA2F;AAC3F,MAAM,WAAW,SAAS;IACzB,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC9B,8HAA8H;IAC9H,QAAQ,EAAE,MAAM,CAAC;IACjB,+GAA+G;IAC/G,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;;;OAOG;IACH,WAAW,EAAE,CACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,KAEd,WAAW,GACX,QAAQ,GACR,SAAS,GACT,OAAO,CAAC,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAC;IAC/C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACnC,iFAAiF;IACjF,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,cAAc,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;CACrB"}
package/dist/body.d.ts ADDED
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Reads a POST body under `max` bytes. Returns a copy of the request whose
3
+ * body is already in memory, or the 413 / 415 refusal.
4
+ */
5
+ export declare function boundedRequest(request: Request, max: number): Promise<Request | Response>;
6
+ //# sourceMappingURL=body.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"body.d.ts","sourceRoot":"","sources":["../src/body.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,wBAAsB,cAAc,CACnC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GACT,OAAO,CAAC,OAAO,GAAG,QAAQ,CAAC,CA+B7B"}
@@ -0,0 +1,14 @@
1
+ /** What the JSON-RPC body of a request asks of the tools. */
2
+ export interface ToolCalls {
3
+ /** It holds a `tools/list`. */
4
+ list: boolean;
5
+ /** The names of its `tools/call` messages. */
6
+ called: readonly string[];
7
+ }
8
+ /**
9
+ * Reads what a request asks of the tools (a message or a batch), from a copy
10
+ * of its body: call it on the admitted request, whose body is in memory. A
11
+ * body that is not JSON asks nothing; the SDK refuses it.
12
+ */
13
+ export declare function toolCallsOf(request: Request): Promise<ToolCalls>;
14
+ //# sourceMappingURL=calls.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"calls.d.ts","sourceRoot":"","sources":["../src/calls.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,MAAM,WAAW,SAAS;IACzB,+BAA+B;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,8CAA8C;IAC9C,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAoBtE"}
@@ -0,0 +1,21 @@
1
+ /** The error codes of `@graxia/mcp`; the rest of what an agent reads comes from `@graxia/core`. */
2
+ export declare const MCP_ERROR_CODES: readonly ["MCP_OPERATION_NOT_ALLOWED", "MCP_EXECUTION_REFUSED", "MCP_UNKNOWN_ARGUMENT", "MCP_UNAUTHORIZED", "MCP_INSUFFICIENT_SCOPE", "MCP_TOKEN_IN_URL"];
3
+ /** A code only `@graxia/mcp` emits. */
4
+ export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
5
+ declare module '@graxia/core' {
6
+ interface GraxiaErrorCodes {
7
+ /** Emitted by @graxia/mcp: the tool runs another kind of operation than the one sent (a mutation in `graphql_query`, a query in `graphql_mutate`). */
8
+ MCP_OPERATION_NOT_ALLOWED: true;
9
+ /** Emitted by @graxia/mcp: `graxia.execute` ended without a GraphQL result and its response carried no error to relay (a plugin's bare `respond`, a shutdown). */
10
+ MCP_EXECUTION_REFUSED: true;
11
+ /** Emitted by @graxia/mcp: a typed tool was called with an argument its input schema does not have. */
12
+ MCP_UNKNOWN_ARGUMENT: true;
13
+ /** Emitted by @graxia/mcp: a 401, the request has no valid bearer token (`auth` is set). */
14
+ MCP_UNAUTHORIZED: true;
15
+ /** Emitted by @graxia/mcp: a 403, the token lacks the read scope, or the write scope `graphql_mutate` and the typed tools of mutations need. */
16
+ MCP_INSUFFICIENT_SCOPE: true;
17
+ /** Emitted by @graxia/mcp: a 400, the access token was sent in the query string. */
18
+ MCP_TOKEN_IN_URL: true;
19
+ }
20
+ }
21
+ //# sourceMappingURL=codes.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../src/codes.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,eAAO,MAAM,eAAe,2JAOlB,CAAC;AAEX,uCAAuC;AACvC,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,OAAO,QAAQ,cAAc,CAAC;IAC7B,UAAU,gBAAgB;QACzB,sJAAsJ;QACtJ,yBAAyB,EAAE,IAAI,CAAC;QAChC,kKAAkK;QAClK,qBAAqB,EAAE,IAAI,CAAC;QAC5B,uGAAuG;QACvG,oBAAoB,EAAE,IAAI,CAAC;QAC3B,4FAA4F;QAC5F,gBAAgB,EAAE,IAAI,CAAC;QACvB,gJAAgJ;QAChJ,sBAAsB,EAAE,IAAI,CAAC;QAC7B,oFAAoF;QACpF,gBAAgB,EAAE,IAAI,CAAC;KACvB;CACD"}
@@ -0,0 +1,20 @@
1
+ import type { ToolCalls } from './calls.js';
2
+ import type { View } from './view.js';
3
+ /** What `fetch` knows about one request, for the SDK's per-request factory. */
4
+ export interface RequestState {
5
+ /** The `serverContext` given to `fetch`. */
6
+ serverContext: object;
7
+ /** What the body asks of the tools. */
8
+ calls: ToolCalls;
9
+ /** The caller's view, built on first use and once. */
10
+ view: () => Promise<View>;
11
+ }
12
+ /** Carries a request's state from `fetch` to the SDK's per-request factory. */
13
+ export interface ContextCarrier {
14
+ /** Runs `fn` with `state` as the current one. */
15
+ run<T>(state: RequestState, fn: () => T): T;
16
+ /** The state of the request being handled; throws outside `run`. */
17
+ current(): RequestState;
18
+ }
19
+ export declare function createContextCarrier(): ContextCarrier;
20
+ //# sourceMappingURL=context.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEnC,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC5B,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,KAAK,EAAE,SAAS,CAAC;IACjB,sDAAsD;IACtD,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC9B,iDAAiD;IACjD,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5C,oEAAoE;IACpE,OAAO,IAAI,YAAY,CAAC;CACxB;AAED,wBAAgB,oBAAoB,IAAI,cAAc,CAarD"}
package/dist/cors.d.ts ADDED
@@ -0,0 +1,7 @@
1
+ /** The origin to echo in `Access-Control-Allow-Origin`: the request's, when `allowed` lists it. */
2
+ export declare function corsOrigin(request: Request, allowed: readonly string[]): string | undefined;
3
+ /** The answer to a preflight from an allowed origin. */
4
+ export declare function preflight(origin: string, requested?: string | null): Response;
5
+ /** `response` with the CORS headers of an allowed origin (unchanged when `origin` is undefined). */
6
+ export declare function withCors(response: Response, origin: string | undefined): Response;
7
+ //# sourceMappingURL=cors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AAGA,mGAAmG;AACnG,wBAAgB,UAAU,CACzB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,SAAS,MAAM,EAAE,GACxB,MAAM,GAAG,SAAS,CAGpB;AAED,wDAAwD;AACxD,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ,CAa7E;AAED,oGAAoG;AACpG,wBAAgB,QAAQ,CACvB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,GAAG,SAAS,GACxB,QAAQ,CAkBV"}
@@ -0,0 +1,29 @@
1
+ import type { McpAuthOptions } from './auth/types.js';
2
+ import type { Mcp, McpHost, McpOptions } from './options.js';
3
+ /** The error sink: the option, `console.error` by default, never throwing. */
4
+ export declare function sinkOf(option: McpOptions['onError']): (error: unknown) => void;
5
+ /**
6
+ * Creates an MCP server over a graxia instance: Streamable HTTP, stateless,
7
+ * with the generic tools `graphql_schema`, `graphql_query` and (with
8
+ * `mutations: true`) `graphql_mutate`. Every operation runs through
9
+ * `graxia.execute`, so limits, cost, trusted documents, masking and rate
10
+ * limits apply; the schema and the body limit come from `graxia`. With
11
+ * `operations`, each persisted operation is also a typed tool. When graxia
12
+ * runs trusted documents in `strict` mode, `graphql_query` and
13
+ * `graphql_mutate` are not offered: only the typed tools run. Without
14
+ * `auth` there is no authentication here: put the endpoint behind your own,
15
+ * and use `can` for permissions. With `auth` it is an OAuth resource server
16
+ * (bearer tokens, scopes, protected resource metadata), and `metadataPath`
17
+ * is a string.
18
+ *
19
+ * @example
20
+ * const mcp = createMcp(graxia, { name: 'library' });
21
+ * Bun.serve({ routes: { '/mcp': (req, server) => mcp.fetch(req, { server }) }, fetch: graxia.fetch });
22
+ */
23
+ export declare function createMcp<HostCtx extends object = Record<never, never>>(graxia: McpHost<HostCtx>, options: McpOptions<HostCtx> & {
24
+ auth: McpAuthOptions;
25
+ }): Mcp<HostCtx> & {
26
+ metadataPath: string;
27
+ };
28
+ export declare function createMcp<HostCtx extends object = Record<never, never>>(graxia: McpHost<HostCtx>, options: McpOptions<HostCtx>): Mcp<HostCtx>;
29
+ //# sourceMappingURL=create.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAInD,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAS1D,8EAA8E;AAC9E,wBAAgB,MAAM,CACrB,MAAM,EAAE,UAAU,CAAC,SAAS,CAAC,GAC3B,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAe1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACtE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EACxB,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACrD,GAAG,CAAC,OAAO,CAAC,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAC3C,wBAAgB,SAAS,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACtE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EACxB,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,GAC1B,GAAG,CAAC,OAAO,CAAC,CAAC"}
@@ -0,0 +1,8 @@
1
+ export type { Can } from '@graxia/core/agent';
2
+ export { mcpAuth } from './auth/principal.js';
3
+ export type { McpAuthInfo, McpAuthOptions, McpScopes } from './auth/types.js';
4
+ export type { McpErrorCode } from './codes.js';
5
+ export { createMcp } from './create.js';
6
+ export type { McpOperationInfo, McpOperationsOptions, } from './operations/types.js';
7
+ export type { Mcp, McpHost, McpOptions } from './options.js';
8
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC3E,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,YAAY,EACX,gBAAgB,EAChB,oBAAoB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}