@mnemahq/mcp 0.1.0 → 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/README.md +27 -5
- package/dist/index.cjs +39 -35
- package/dist/index.d.cts +5 -4
- package/dist/index.d.ts +5 -4
- package/dist/index.js +39 -35
- package/package.json +2 -3
package/README.md
CHANGED
|
@@ -120,13 +120,13 @@ await mnema.call("complete_task", {
|
|
|
120
120
|
|
|
121
121
|
```ts
|
|
122
122
|
import {
|
|
123
|
-
MnemaUnauthorizedError, //
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
MnemaToolError, // the tool ran and refused — an answer, not an outage
|
|
123
|
+
MnemaUnauthorizedError, // key wrong or revoked, or no longer a member — reconnect, do not retry
|
|
124
|
+
MnemaSubscriptionError, // subscription halted or workspace suspended; .billingUrl when halted
|
|
125
|
+
MnemaToolError, // the tool could not run — unknown tool, bad arguments, missing scope, a tool that errored
|
|
127
126
|
MnemaTransportError, // no answer — safe to retry a READ
|
|
128
|
-
MnemaToolMissingError, // .missing lists the tools this workspace lacks
|
|
127
|
+
MnemaToolMissingError, // .missing lists the tools this workspace lacks (from assertTools)
|
|
129
128
|
MnemaProposalExpiredError,
|
|
129
|
+
MnemaForbiddenError, // .requiredScope — see the note below
|
|
130
130
|
} from "@mnemahq/mcp";
|
|
131
131
|
```
|
|
132
132
|
|
|
@@ -134,6 +134,28 @@ The split between `MnemaToolError` and `MnemaTransportError` is the one that mat
|
|
|
134
134
|
second is ever safe to retry, and only reads at that. **A retried create without an
|
|
135
135
|
`idempotency_key` is a duplicate.**
|
|
136
136
|
|
|
137
|
+
### ⚠️ Not every refusal throws
|
|
138
|
+
|
|
139
|
+
Many Mnema tools report a refusal **as data**, not as an error. `call()` resolves with it, and
|
|
140
|
+
nothing is thrown:
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
const res = await mnema.call<{ error?: string }>("move_task", { taskId, status: "done" });
|
|
144
|
+
if (typeof res?.error === "string") {
|
|
145
|
+
// a refusal: "task_not_found", "not_found", "invalid_args", "dev_mode_required", …
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
If you rely on `try/catch` alone, a refused call looks like a success. Check for an `error`
|
|
150
|
+
string on any tool whose result you act on.
|
|
151
|
+
|
|
152
|
+
### ⚠️ A missing scope is a `MnemaToolError`, not a `MnemaForbiddenError`
|
|
153
|
+
|
|
154
|
+
When a key lacks the scope a tool needs, the server answers inside the tool result, so it
|
|
155
|
+
arrives as a `MnemaToolError` whose message names the scope — for example
|
|
156
|
+
`MCP forbidden: missing scope docs:read`. `MnemaForbiddenError` (with `.requiredScope`) is only
|
|
157
|
+
thrown for a top-level `-32002`, which the server does not currently send for tool calls.
|
|
158
|
+
|
|
137
159
|
## Typed tool payloads
|
|
138
160
|
|
|
139
161
|
`call()` returns `unknown` today. That is deliberate — it is not a confident lie.
|
package/dist/index.cjs
CHANGED
|
@@ -105,7 +105,16 @@ var str = (v) => typeof v === "string" ? v : void 0;
|
|
|
105
105
|
|
|
106
106
|
// src/transport.ts
|
|
107
107
|
var nextId = 1;
|
|
108
|
-
|
|
108
|
+
function jsonRpcError(text) {
|
|
109
|
+
try {
|
|
110
|
+
const body = JSON.parse(text);
|
|
111
|
+
const err = body?.error;
|
|
112
|
+
if (err && typeof err.code === "number") return { code: err.code, message: err.message, data: err.data };
|
|
113
|
+
} catch {
|
|
114
|
+
}
|
|
115
|
+
return null;
|
|
116
|
+
}
|
|
117
|
+
async function rpcRequest(opts, method, params, label) {
|
|
109
118
|
const doFetch = opts.fetch ?? globalThis.fetch;
|
|
110
119
|
const url = `${opts.baseUrl.replace(/\/+$/, "")}${opts.path ?? "/mcp"}`;
|
|
111
120
|
let res;
|
|
@@ -118,35 +127,41 @@ async function rpcCall(opts, tool, args) {
|
|
|
118
127
|
Accept: "application/json, text/event-stream",
|
|
119
128
|
Authorization: `Bearer ${opts.apiKey}`
|
|
120
129
|
},
|
|
121
|
-
body: JSON.stringify({
|
|
122
|
-
jsonrpc: "2.0",
|
|
123
|
-
id: nextId++,
|
|
124
|
-
method: "tools/call",
|
|
125
|
-
params: { name: tool, arguments: args }
|
|
126
|
-
}),
|
|
130
|
+
body: JSON.stringify({ jsonrpc: "2.0", id: nextId++, method, params }),
|
|
127
131
|
signal: AbortSignal.timeout(opts.timeoutMs ?? 2e4)
|
|
128
132
|
});
|
|
129
133
|
} catch (err) {
|
|
130
134
|
throw new MnemaTransportError(
|
|
131
135
|
err instanceof Error ? err.message : String(err),
|
|
132
136
|
void 0,
|
|
133
|
-
|
|
134
|
-
);
|
|
135
|
-
}
|
|
136
|
-
if (res.status === 401 || res.status === 403) {
|
|
137
|
-
throw new MnemaUnauthorizedError(
|
|
138
|
-
`Mnema refused the token (${res.status}). Check MNEMA_API_KEY, or reconnect.`,
|
|
139
|
-
tool
|
|
137
|
+
label
|
|
140
138
|
);
|
|
141
139
|
}
|
|
142
140
|
if (!res.ok) {
|
|
143
|
-
const
|
|
144
|
-
|
|
141
|
+
const text = await res.text().catch(() => "");
|
|
142
|
+
const rpcError = jsonRpcError(text);
|
|
143
|
+
if (rpcError) {
|
|
144
|
+
if (rpcError.code === MNEMA_ERROR_CODES.unauthorized && /^\s*unauthorized\.?\s*$/i.test(rpcError.message ?? "")) {
|
|
145
|
+
const reason = typeof rpcError.data?.reason === "string" ? `: ${rpcError.data.reason}` : "";
|
|
146
|
+
rpcError.message = `Mnema refused the token (${res.status}${reason}). Check MNEMA_API_KEY, or reconnect.`;
|
|
147
|
+
}
|
|
148
|
+
throw errorFromRpc(rpcError, label);
|
|
149
|
+
}
|
|
150
|
+
if (res.status === 401 || res.status === 403) {
|
|
151
|
+
throw new MnemaUnauthorizedError(
|
|
152
|
+
`Mnema refused the token (${res.status}). Check MNEMA_API_KEY, or reconnect.`,
|
|
153
|
+
label
|
|
154
|
+
);
|
|
155
|
+
}
|
|
156
|
+
throw new MnemaTransportError(`Mnema HTTP ${res.status}: ${text.slice(0, 300)}`, res.status, label);
|
|
145
157
|
}
|
|
146
158
|
const body = await res.json().catch(() => null);
|
|
147
|
-
if (!body) throw new MnemaTransportError("Mnema returned a body that is not JSON", res.status,
|
|
148
|
-
if (body.error) throw errorFromRpc(body.error,
|
|
149
|
-
|
|
159
|
+
if (!body) throw new MnemaTransportError("Mnema returned a body that is not JSON", res.status, label);
|
|
160
|
+
if (body.error) throw errorFromRpc(body.error, label);
|
|
161
|
+
return body.result ?? {};
|
|
162
|
+
}
|
|
163
|
+
async function rpcCall(opts, tool, args) {
|
|
164
|
+
const result = await rpcRequest(opts, "tools/call", { name: tool, arguments: args }, tool);
|
|
150
165
|
if (result.isError) {
|
|
151
166
|
const text2 = (result.content ?? []).map((c) => c.text ?? "").join(" ").trim();
|
|
152
167
|
throw new MnemaToolError(text2 || `${tool} failed and said nothing`, tool);
|
|
@@ -161,23 +176,12 @@ async function rpcCall(opts, tool, args) {
|
|
|
161
176
|
}
|
|
162
177
|
}
|
|
163
178
|
async function rpcListTools(opts) {
|
|
164
|
-
const
|
|
165
|
-
const
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
headers: {
|
|
169
|
-
"Content-Type": "application/json",
|
|
170
|
-
Accept: "application/json, text/event-stream",
|
|
171
|
-
Authorization: `Bearer ${opts.apiKey}`
|
|
172
|
-
},
|
|
173
|
-
body: JSON.stringify({ jsonrpc: "2.0", id: nextId++, method: "tools/list", params: {} }),
|
|
174
|
-
signal: AbortSignal.timeout(opts.timeoutMs ?? 2e4)
|
|
175
|
-
});
|
|
176
|
-
if (!res.ok) {
|
|
177
|
-
throw new MnemaTransportError(`tools/list failed: HTTP ${res.status}`, res.status);
|
|
179
|
+
const result = await rpcRequest(opts, "tools/list", {}, "tools/list");
|
|
180
|
+
const tools = result.tools;
|
|
181
|
+
if (!Array.isArray(tools)) {
|
|
182
|
+
throw new MnemaTransportError("tools/list answered without a tools array", void 0, "tools/list");
|
|
178
183
|
}
|
|
179
|
-
|
|
180
|
-
return (body.result?.tools ?? []).map((t) => t.name);
|
|
184
|
+
return tools.map((t) => t.name);
|
|
181
185
|
}
|
|
182
186
|
|
|
183
187
|
// src/protocols.ts
|
package/dist/index.d.cts
CHANGED
|
@@ -199,10 +199,11 @@ interface MnemaClient {
|
|
|
199
199
|
* Call any tool by name.
|
|
200
200
|
*
|
|
201
201
|
* ⚠️ UNTYPED BY DESIGN, FOR NOW. 92 of the tools advertise an output schema in
|
|
202
|
-
* `tools/list`, so typed bindings are generatable —
|
|
203
|
-
*
|
|
204
|
-
* confident lie, which is the same rule the server's
|
|
205
|
-
* unresolved type is an error, never a fallback to
|
|
202
|
+
* `tools/list`, so typed bindings are generatable — but no generator ships in this
|
|
203
|
+
* version. Pass the shape you expect as `T` (`call<{ results: Hit[] }>(…)`); until then
|
|
204
|
+
* this returns `unknown` rather than a confident lie, which is the same rule the server's
|
|
205
|
+
* own schema generator follows: an unresolved type is an error, never a fallback to
|
|
206
|
+
* `string`.
|
|
206
207
|
*/
|
|
207
208
|
call: MnemaCall;
|
|
208
209
|
/** The tool names this key can see. */
|
package/dist/index.d.ts
CHANGED
|
@@ -199,10 +199,11 @@ interface MnemaClient {
|
|
|
199
199
|
* Call any tool by name.
|
|
200
200
|
*
|
|
201
201
|
* ⚠️ UNTYPED BY DESIGN, FOR NOW. 92 of the tools advertise an output schema in
|
|
202
|
-
* `tools/list`, so typed bindings are generatable —
|
|
203
|
-
*
|
|
204
|
-
* confident lie, which is the same rule the server's
|
|
205
|
-
* unresolved type is an error, never a fallback to
|
|
202
|
+
* `tools/list`, so typed bindings are generatable — but no generator ships in this
|
|
203
|
+
* version. Pass the shape you expect as `T` (`call<{ results: Hit[] }>(…)`); until then
|
|
204
|
+
* this returns `unknown` rather than a confident lie, which is the same rule the server's
|
|
205
|
+
* own schema generator follows: an unresolved type is an error, never a fallback to
|
|
206
|
+
* `string`.
|
|
206
207
|
*/
|
|
207
208
|
call: MnemaCall;
|
|
208
209
|
/** The tool names this key can see. */
|
package/dist/index.js
CHANGED
|
@@ -68,7 +68,16 @@ var str = (v) => typeof v === "string" ? v : void 0;
|
|
|
68
68
|
|
|
69
69
|
// src/transport.ts
|
|
70
70
|
var nextId = 1;
|
|
71
|
-
|
|
71
|
+
function jsonRpcError(text) {
|
|
72
|
+
try {
|
|
73
|
+
const body = JSON.parse(text);
|
|
74
|
+
const err = body?.error;
|
|
75
|
+
if (err && typeof err.code === "number") return { code: err.code, message: err.message, data: err.data };
|
|
76
|
+
} catch {
|
|
77
|
+
}
|
|
78
|
+
return null;
|
|
79
|
+
}
|
|
80
|
+
async function rpcRequest(opts, method, params, label) {
|
|
72
81
|
const doFetch = opts.fetch ?? globalThis.fetch;
|
|
73
82
|
const url = `${opts.baseUrl.replace(/\/+$/, "")}${opts.path ?? "/mcp"}`;
|
|
74
83
|
let res;
|
|
@@ -81,35 +90,41 @@ async function rpcCall(opts, tool, args) {
|
|
|
81
90
|
Accept: "application/json, text/event-stream",
|
|
82
91
|
Authorization: `Bearer ${opts.apiKey}`
|
|
83
92
|
},
|
|
84
|
-
body: JSON.stringify({
|
|
85
|
-
jsonrpc: "2.0",
|
|
86
|
-
id: nextId++,
|
|
87
|
-
method: "tools/call",
|
|
88
|
-
params: { name: tool, arguments: args }
|
|
89
|
-
}),
|
|
93
|
+
body: JSON.stringify({ jsonrpc: "2.0", id: nextId++, method, params }),
|
|
90
94
|
signal: AbortSignal.timeout(opts.timeoutMs ?? 2e4)
|
|
91
95
|
});
|
|
92
96
|
} catch (err) {
|
|
93
97
|
throw new MnemaTransportError(
|
|
94
98
|
err instanceof Error ? err.message : String(err),
|
|
95
99
|
void 0,
|
|
96
|
-
|
|
97
|
-
);
|
|
98
|
-
}
|
|
99
|
-
if (res.status === 401 || res.status === 403) {
|
|
100
|
-
throw new MnemaUnauthorizedError(
|
|
101
|
-
`Mnema refused the token (${res.status}). Check MNEMA_API_KEY, or reconnect.`,
|
|
102
|
-
tool
|
|
100
|
+
label
|
|
103
101
|
);
|
|
104
102
|
}
|
|
105
103
|
if (!res.ok) {
|
|
106
|
-
const
|
|
107
|
-
|
|
104
|
+
const text = await res.text().catch(() => "");
|
|
105
|
+
const rpcError = jsonRpcError(text);
|
|
106
|
+
if (rpcError) {
|
|
107
|
+
if (rpcError.code === MNEMA_ERROR_CODES.unauthorized && /^\s*unauthorized\.?\s*$/i.test(rpcError.message ?? "")) {
|
|
108
|
+
const reason = typeof rpcError.data?.reason === "string" ? `: ${rpcError.data.reason}` : "";
|
|
109
|
+
rpcError.message = `Mnema refused the token (${res.status}${reason}). Check MNEMA_API_KEY, or reconnect.`;
|
|
110
|
+
}
|
|
111
|
+
throw errorFromRpc(rpcError, label);
|
|
112
|
+
}
|
|
113
|
+
if (res.status === 401 || res.status === 403) {
|
|
114
|
+
throw new MnemaUnauthorizedError(
|
|
115
|
+
`Mnema refused the token (${res.status}). Check MNEMA_API_KEY, or reconnect.`,
|
|
116
|
+
label
|
|
117
|
+
);
|
|
118
|
+
}
|
|
119
|
+
throw new MnemaTransportError(`Mnema HTTP ${res.status}: ${text.slice(0, 300)}`, res.status, label);
|
|
108
120
|
}
|
|
109
121
|
const body = await res.json().catch(() => null);
|
|
110
|
-
if (!body) throw new MnemaTransportError("Mnema returned a body that is not JSON", res.status,
|
|
111
|
-
if (body.error) throw errorFromRpc(body.error,
|
|
112
|
-
|
|
122
|
+
if (!body) throw new MnemaTransportError("Mnema returned a body that is not JSON", res.status, label);
|
|
123
|
+
if (body.error) throw errorFromRpc(body.error, label);
|
|
124
|
+
return body.result ?? {};
|
|
125
|
+
}
|
|
126
|
+
async function rpcCall(opts, tool, args) {
|
|
127
|
+
const result = await rpcRequest(opts, "tools/call", { name: tool, arguments: args }, tool);
|
|
113
128
|
if (result.isError) {
|
|
114
129
|
const text2 = (result.content ?? []).map((c) => c.text ?? "").join(" ").trim();
|
|
115
130
|
throw new MnemaToolError(text2 || `${tool} failed and said nothing`, tool);
|
|
@@ -124,23 +139,12 @@ async function rpcCall(opts, tool, args) {
|
|
|
124
139
|
}
|
|
125
140
|
}
|
|
126
141
|
async function rpcListTools(opts) {
|
|
127
|
-
const
|
|
128
|
-
const
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
headers: {
|
|
132
|
-
"Content-Type": "application/json",
|
|
133
|
-
Accept: "application/json, text/event-stream",
|
|
134
|
-
Authorization: `Bearer ${opts.apiKey}`
|
|
135
|
-
},
|
|
136
|
-
body: JSON.stringify({ jsonrpc: "2.0", id: nextId++, method: "tools/list", params: {} }),
|
|
137
|
-
signal: AbortSignal.timeout(opts.timeoutMs ?? 2e4)
|
|
138
|
-
});
|
|
139
|
-
if (!res.ok) {
|
|
140
|
-
throw new MnemaTransportError(`tools/list failed: HTTP ${res.status}`, res.status);
|
|
142
|
+
const result = await rpcRequest(opts, "tools/list", {}, "tools/list");
|
|
143
|
+
const tools = result.tools;
|
|
144
|
+
if (!Array.isArray(tools)) {
|
|
145
|
+
throw new MnemaTransportError("tools/list answered without a tools array", void 0, "tools/list");
|
|
141
146
|
}
|
|
142
|
-
|
|
143
|
-
return (body.result?.tools ?? []).map((t) => t.name);
|
|
147
|
+
return tools.map((t) => t.name);
|
|
144
148
|
}
|
|
145
149
|
|
|
146
150
|
// src/protocols.ts
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mnemahq/mcp",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Call Mnema's MCP tools from an app — transport, typed errors, and the two-phase protocols (propose/confirm, request/approve, usage deltas).",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"type": "module",
|
|
@@ -26,7 +26,6 @@
|
|
|
26
26
|
},
|
|
27
27
|
"files": [
|
|
28
28
|
"dist",
|
|
29
|
-
"scripts",
|
|
30
29
|
"README.md"
|
|
31
30
|
],
|
|
32
31
|
"keywords": [
|
|
@@ -45,7 +44,7 @@
|
|
|
45
44
|
"@types/node": "^22.0.0"
|
|
46
45
|
},
|
|
47
46
|
"mnema": {
|
|
48
|
-
"released":
|
|
47
|
+
"released": true
|
|
49
48
|
},
|
|
50
49
|
"scripts": {
|
|
51
50
|
"build": "tsup src/index.ts --format esm,cjs --dts --clean",
|