@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.
- package/LICENSE +21 -0
- package/README.md +169 -2
- package/dist/auth/bearer.d.ts +17 -0
- package/dist/auth/bearer.d.ts.map +1 -0
- package/dist/auth/metadata.d.ts +8 -0
- package/dist/auth/metadata.d.ts.map +1 -0
- package/dist/auth/principal.d.ts +17 -0
- package/dist/auth/principal.d.ts.map +1 -0
- package/dist/auth/resolve.d.ts +4 -0
- package/dist/auth/resolve.d.ts.map +1 -0
- package/dist/auth/scopes.d.ts +14 -0
- package/dist/auth/scopes.d.ts.map +1 -0
- package/dist/auth/types.d.ts +70 -0
- package/dist/auth/types.d.ts.map +1 -0
- package/dist/body.d.ts +6 -0
- package/dist/body.d.ts.map +1 -0
- package/dist/calls.d.ts +14 -0
- package/dist/calls.d.ts.map +1 -0
- package/dist/codes.d.ts +21 -0
- package/dist/codes.d.ts.map +1 -0
- package/dist/context.d.ts +20 -0
- package/dist/context.d.ts.map +1 -0
- package/dist/cors.d.ts +7 -0
- package/dist/cors.d.ts.map +1 -0
- package/dist/create.d.ts +29 -0
- package/dist/create.d.ts.map +1 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +1533 -0
- package/dist/index.js.map +45 -0
- package/dist/operations/build.d.ts +10 -0
- package/dist/operations/build.d.ts.map +1 -0
- package/dist/operations/constraint.d.ts +16 -0
- package/dist/operations/constraint.d.ts.map +1 -0
- package/dist/operations/documents.d.ts +13 -0
- package/dist/operations/documents.d.ts.map +1 -0
- package/dist/operations/input-schema.d.ts +12 -0
- package/dist/operations/input-schema.d.ts.map +1 -0
- package/dist/operations/input-type.d.ts +18 -0
- package/dist/operations/input-type.d.ts.map +1 -0
- package/dist/operations/naming.d.ts +5 -0
- package/dist/operations/naming.d.ts.map +1 -0
- package/dist/operations/output-schema.d.ts +11 -0
- package/dist/operations/output-schema.d.ts.map +1 -0
- package/dist/operations/problems.d.ts +27 -0
- package/dist/operations/problems.d.ts.map +1 -0
- package/dist/operations/register.d.ts +20 -0
- package/dist/operations/register.d.ts.map +1 -0
- package/dist/operations/types.d.ts +49 -0
- package/dist/operations/types.d.ts.map +1 -0
- package/dist/operations/variable-usage.d.ts +16 -0
- package/dist/operations/variable-usage.d.ts.map +1 -0
- package/dist/operations/visible.d.ts +10 -0
- package/dist/operations/visible.d.ts.map +1 -0
- package/dist/options.d.ts +116 -0
- package/dist/options.d.ts.map +1 -0
- package/dist/origin-options.d.ts +9 -0
- package/dist/origin-options.d.ts.map +1 -0
- package/dist/origin.d.ts +18 -0
- package/dist/origin.d.ts.map +1 -0
- package/dist/pipeline.d.ts +16 -0
- package/dist/pipeline.d.ts.map +1 -0
- package/dist/refusal.d.ts +4 -0
- package/dist/refusal.d.ts.map +1 -0
- package/dist/server.d.ts +28 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/tools/execute.d.ts +32 -0
- package/dist/tools/execute.d.ts.map +1 -0
- package/dist/tools/guard.d.ts +8 -0
- package/dist/tools/guard.d.ts.map +1 -0
- package/dist/tools/index.d.ts +17 -0
- package/dist/tools/index.d.ts.map +1 -0
- package/dist/tools/operation.d.ts +35 -0
- package/dist/tools/operation.d.ts.map +1 -0
- package/dist/tools/result.d.ts +13 -0
- package/dist/tools/result.d.ts.map +1 -0
- package/dist/tools/schema.d.ts +319 -0
- package/dist/tools/schema.d.ts.map +1 -0
- package/dist/tools/strict.d.ts +12 -0
- package/dist/tools/strict.d.ts.map +1 -0
- package/dist/toolset.d.ts +30 -0
- package/dist/toolset.d.ts.map +1 -0
- package/dist/view-cache.d.ts +13 -0
- package/dist/view-cache.d.ts.map +1 -0
- package/dist/view.d.ts +16 -0
- package/dist/view.d.ts.map +1 -0
- package/docs/README.md +9 -0
- package/docs/guide/auth.md +247 -0
- package/docs/guide/getting-started.md +82 -0
- package/docs/guide/operations.md +221 -0
- package/docs/guide/security.md +122 -0
- package/docs/guide/tools.md +102 -0
- package/docs/roadmap.md +32 -0
- package/docs/troubleshooting-auth.md +101 -0
- package/docs/troubleshooting.md +205 -0
- 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
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
+
}
|