@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
@@ -0,0 +1,205 @@
1
+ # Troubleshooting
2
+
3
+ Each entry is headed by the message or code you see. The 401, 403 and 503 answers of `auth` and its
4
+ boot errors are in [troubleshooting auth](./troubleshooting-auth.md).
5
+
6
+ ## 403 `Origin https://… is not allowed.`
7
+
8
+ A browser client sent an `Origin` that is not in `allowedOrigins` and is not the endpoint's own.
9
+
10
+ ```ts
11
+ createMcp(graxia, { name: 'library', allowedOrigins: ['https://app.example'] });
12
+ ```
13
+
14
+ A CLI or server client sends no `Origin` and is not affected.
15
+
16
+ ## 403 `Host … is not allowed.`
17
+
18
+ The request is same-origin but its `Host` header names a hostname outside `allowedHosts` (default
19
+ `localhost`, `127.0.0.1`, `[::1]`): the DNS-rebinding guard. Set the endpoint's public hostname,
20
+ without port. Behind a proxy, list the hostname the browser uses.
21
+
22
+ ```ts
23
+ createMcp(graxia, { name: 'library', allowedHosts: ['mcp.example.com'] });
24
+ ```
25
+
26
+ ## 405 `GET is not supported: this endpoint is stateless.`
27
+
28
+ Also `DELETE is not supported: this endpoint is stateless.` (and any other method but `POST`). The
29
+ endpoint has no server-to-client stream and no sessions. Clients send `POST`; a client that probes
30
+ with `GET` or `DELETE` and goes on after the 405 is working as intended.
31
+
32
+ ## 413 `The request body is larger than … bytes.`
33
+
34
+ The body is over `limits.bodyBytes` of the graxia instance, which the MCP endpoint reads from
35
+ `graxia.limits`. Send a smaller request or raise it on `createGraxia`; both endpoints follow.
36
+
37
+ ## 415 `The request body must be application/json.`
38
+
39
+ Send `Content-Type: application/json`.
40
+
41
+ ## 500 `The MCP server failed to handle the request.`
42
+
43
+ The transport failed (a broken body stream, a bug). The cause is not sent; it went to `onError`
44
+ (default `console.error`). Pass your own to log it:
45
+
46
+ ```ts
47
+ createMcp(graxia, { name: 'library', onError: (error) => logger.error(error) });
48
+ ```
49
+
50
+ ## `createMcp: no serverContext for this request; the MCP handler ran outside fetch.`
51
+
52
+ The handler was called without going through `mcp.fetch`. Always mount `mcp.fetch`.
53
+
54
+ ## `Cannot query field "x" on type "Y"` for a field that exists
55
+
56
+ Reported with `extensions.code` `GRAPHQL_VALIDATION_FAILED`.
57
+
58
+ The field is behind `@needs` and `can` says the caller lacks the permission, or `can` is not what
59
+ you meant: the view is built from `can`'s answer. Check it with `graphql_schema` as that caller.
60
+
61
+ ## `graphql_mutate` is missing from the list with `mutations: true`
62
+
63
+ With `auth`, it is listed only for a token with the write scope (`mcp:write` by default). When
64
+ graxia runs trusted documents in `strict` mode it is never listed, like `graphql_query`.
65
+
66
+ ## `GraphQL introspection has been disabled…` / `Use graphql_schema to read the schema.`
67
+
68
+ `__schema` and `__type` are refused over MCP: they would show fields `@needs` hides. Call
69
+ `graphql_schema` (no input, `types` or `search`). `__typename` is allowed.
70
+
71
+ ## `No type matches "x".` (or `Empty search.`)
72
+
73
+ `graphql_schema` with `search` found no type or field of that name in the caller's view (a hidden
74
+ type is not found either); `Empty search.` means `search` was blank. Call `graphql_schema` with
75
+ no input for the type names, then search a word of one of them.
76
+
77
+ ## `# Unknown type X. Fix: call graphql_schema with no input to list the type names you can use.`
78
+
79
+ `graphql_schema` was asked for a type the caller cannot see or that does not exist. The `Mutation`
80
+ root is also unknown unless `mutations: true`. Call it with no input for the list.
81
+
82
+ ## `A mutation cannot run in graphql_query.`
83
+
84
+ Use `graphql_mutate` (listed only with `mutations: true`). The reverse, `A query cannot run in
85
+ graphql_mutate.`, means use `graphql_query`. Code `MCP_OPERATION_NOT_ALLOWED`. In a document with
86
+ several operations, `operationName` picks the one checked.
87
+
88
+ ## `Subscriptions are not available over MCP.`
89
+
90
+ Code `SUBSCRIPTION_NOT_SUPPORTED`. Send a query, or poll the same query again.
91
+
92
+ ## `@defer is not available over MCP.` (or `@stream`)
93
+
94
+ Code `INCREMENTAL_NOT_SUPPORTED`. Remove the directive: the tool returns one complete JSON result.
95
+
96
+ ## A parse failure (`Syntax Error: …`, `Document contains more than N tokens.`)
97
+
98
+ Code `GRAPHQL_PARSE_FAILED`, raised by the MCP server before `graxia.execute`: correct the syntax at the position the error gives, or
99
+ raise `limits.tokens` on `createGraxia` for a very large document.
100
+
101
+ ## `Tool graphql_mutate not found`
102
+
103
+ It is listed only with `mutations: true` (and, with `auth`, for a token with the write scope).
104
+ `Tool graphql_query not found`: `genericTools` is `false`; call a typed tool.
105
+
106
+ ## `Tool book_by_id not found` for an operation of the manifest
107
+
108
+ The tool is not offered to this caller: its operation uses a field `can` hides from them, it is a
109
+ mutation without `mutations: true`, `include` left it out, or it is a subscription. The answer is
110
+ the same as for a tool that does not exist. Call `graphql_schema` for the typed tools you have.
111
+
112
+ ## `createMcp: operations has 1 problem:` (or `N problems:`)
113
+
114
+ One error lists every problem of `operations`, one per line, each ending with its fix:
115
+
116
+ - `document "a1" holds an anonymous operation: a tool needs a name.` Name it and regenerate.
117
+ - `BookById (document "a1") has no description: …` Write `"""…"""` above the operation, or set
118
+ `operations.descriptions.BookById`. A toolchain that drops descriptions needs the option.
119
+ - `operations.descriptions.bookById matches no operation of operations.documents (there is
120
+ BookById: names are case-sensitive).` Rename or remove the key.
121
+ - `BookById (document "a1") and Book_by_id (document "a2") both give the tool name book_by_id.`
122
+ Rename one, or leave one out with `include`.
123
+ - `GraphqlQuery (document "a1") gives the tool name graphql_query, and graphql_* names are the
124
+ generic tools'.` Rename the operation, or leave it out.
125
+ - `… gives a tool name of 140 characters, and MCP allows 128.` Rename the operation.
126
+ - `document "a1" does not parse: Syntax Error: …` Regenerate the manifest.
127
+ - `BookById (document "a1") is not valid against the schema: Cannot query field …` The manifest is
128
+ older than the schema (or belongs to another server): regenerate it.
129
+ - `Types (document "a1") selects __schema or __type: introspection is not offered over MCP, …`
130
+ Leave the operation out with `include`: an agent reads the schema with `graphql_schema`.
131
+ - `BookById (document "a1") uses @defer, which is not available over MCP: …` (or `@stream`).
132
+ - `document "a1" is not a GraphQL source string.` Map every id to the text of its document.
133
+ - `operations.documents is not a manifest.` Pass a `Map`, an object of id to source, or an Apollo
134
+ persisted query manifest.
135
+ - `genericTools is false and operations gives no tool: …` Without the generic tools an agent needs
136
+ at least one typed tool: check `documents` and `include` (mutations need `mutations: true`).
137
+
138
+ An operation `include` leaves out, a subscription, and a mutation without `mutations: true` is not
139
+ validated and needs no description; every document must still parse and name its operations.
140
+
141
+ ## ``createMcp: graxia runs trusted documents in strict mode and `operations` gives no tool: …``
142
+
143
+ Reported once through `onError` at boot (not thrown: the same code boots in development). graxia's
144
+ `trustedDocuments` is `strict` (the default under `NODE_ENV=production`), so `graphql_query` and
145
+ `graphql_mutate` are not listed, and with no `operations` there is no typed tool: agents read the
146
+ schema and run nothing. Fix: pass the persisted documents.
147
+
148
+ ```ts
149
+ createMcp(graxia, { name: 'library', operations: { documents: manifest } });
150
+ ```
151
+
152
+ ## `createMcp: allowedHosts entry "…" can never match` / `allowedOrigins entry "…" can never match`
153
+
154
+ Thrown at startup. `allowedHosts` takes hostnames only (`mcp.example.com`, `[::1]`), without
155
+ scheme, port or path; `allowedOrigins` takes exactly `scheme://host[:port]`, with no path and no
156
+ trailing slash. The message gives the corrected value.
157
+
158
+ ```ts
159
+ createMcp(graxia, {
160
+ name: 'library',
161
+ allowedHosts: ['mcp.example.com'], // not 'mcp.example.com:3000'
162
+ allowedOrigins: ['https://app.example'], // not 'https://app.example/'
163
+ });
164
+ ```
165
+
166
+ ## `createMcp: genericTools is false and there is no operations: …`
167
+
168
+ Pass `operations: { documents: manifest }`, or remove `genericTools: false`.
169
+
170
+ ## `book_by_id does not take the argument extra.` (`MCP_UNKNOWN_ARGUMENT`)
171
+
172
+ A typed tool was called with an argument that is not a variable of its operation. The fix names
173
+ the arguments it accepts; they are the `properties` of its `inputSchema` in `tools/list`.
174
+
175
+ ## A typed tool answers `Variable "$id" …` (`BAD_USER_INPUT`)
176
+
177
+ An argument is missing or has the wrong type: graxia checks the arguments as the operation's
178
+ variables. The fix is `Correct the arguments: see the tool's input schema.`
179
+
180
+ ## `Forbidden: rename_book needs the scope mcp:write.` (`MCP_INSUFFICIENT_SCOPE`)
181
+
182
+ A 403 `insufficient_scope`: a mutation typed tool was called with a read-only token, the same
183
+ step-up as `graphql_mutate` ([auth troubleshooting](./troubleshooting-auth.md)).
184
+
185
+ ## `Only persisted documents are allowed.` (`PERSISTED_QUERY_ONLY`) from `graphql_query`
186
+
187
+ graxia's `trustedDocuments` is `strict` (the default under `NODE_ENV=production`), so the server
188
+ runs no document an agent writes: `graphql_query` and `graphql_mutate` are not listed and a call
189
+ answers this refusal, whose fix names the typed tools the caller has. Give the agent
190
+ [typed tools](./guide/operations.md) (`operations`); without them only `graphql_schema` is there.
191
+
192
+ ## `graxia.execute: the request ended with an HTTP … response instead of a result; see error.response.`
193
+
194
+ Code `MCP_EXECUTION_REFUSED`, with the fix `Retry later; if it persists, the server is shutting
195
+ down or a plugin refused the request.` A plugin answered with its own response whose body has no
196
+ `errors`, or the server is shutting down. A plugin response with `errors` reaches the agent as
197
+ they are (its code and fix, e.g. `UNAUTHENTICATED`), so shape your plugin's refusal as
198
+ `{ errors: [{ message, extensions: { code, fix } }] }`.
199
+
200
+ ## `The server failed to run the operation. Fix: retry later.`
201
+
202
+ An unexpected failure inside the tool (a throwing `can`, a bug); its cause is not sent. It went to
203
+ `onError` and, for the operation itself, to graxia's `onUnexpected`. When `can` throws,
204
+ `tools/list` also answers without the typed tools, and a call to one gets this answer: the cause
205
+ is in `onError`.
package/package.json CHANGED
@@ -1,6 +1,72 @@
1
1
  {
2
- "name": "@graxia/mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "@graxia/mcp",
3
+ "version": "0.1.1",
4
+ "description": "Model Context Protocol server over graxia: stateless Streamable HTTP with graphql_schema, graphql_query and graphql_mutate tools, and persisted operations as typed tools",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "files": [
10
+ "dist",
11
+ "docs",
12
+ "README.md",
13
+ "package.json",
14
+ "LICENSE"
15
+ ],
16
+ "exports": {
17
+ ".": {
18
+ "types": "./dist/index.d.ts",
19
+ "import": "./dist/index.js",
20
+ "default": "./dist/index.js"
21
+ },
22
+ "./package.json": "./package.json"
23
+ },
24
+ "keywords": [
25
+ "graphql",
26
+ "mcp",
27
+ "ai",
28
+ "bun"
29
+ ],
30
+ "repository": {
31
+ "type": "git",
32
+ "url": "git+https://github.com/softistx/graxia.git",
33
+ "directory": "packages/mcp"
34
+ },
35
+ "publishConfig": {
36
+ "access": "public"
37
+ },
38
+ "scripts": {
39
+ "build": "bun run ../../build.ts",
40
+ "test": "bun test --pass-with-no-tests src",
41
+ "typecheck": "bun check"
42
+ },
43
+ "nxgt": {
44
+ "entrypoints": [
45
+ "src/index.ts"
46
+ ]
47
+ },
48
+ "devDependencies": {
49
+ "@types/bun": "^1.4.4",
50
+ "@graxia/core": "^0.6.0",
51
+ "@modelcontextprotocol/client": "~2.4.0",
52
+ "graphql": "^17.1.0"
53
+ },
54
+ "peerDependencies": {
55
+ "@graxia/core": "^0.6.0",
56
+ "typescript": "^6.0.3 || ^7.0.0",
57
+ "graphql": "^17.1.0"
58
+ },
59
+ "dependencies": {
60
+ "@modelcontextprotocol/server": "~2.4.0",
61
+ "zod": "^4.2.0"
62
+ },
63
+ "sideEffects": false,
64
+ "peerDependenciesMeta": {
65
+ "typescript": {
66
+ "optional": true
67
+ }
68
+ },
69
+ "engines": {
70
+ "bun": ">=1.4.4"
71
+ }
72
+ }