@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 CHANGED
@@ -120,13 +120,13 @@ await mnema.call("complete_task", {
120
120
 
121
121
  ```ts
122
122
  import {
123
- MnemaUnauthorizedError, // token rejected — reconnect, do not retry
124
- MnemaForbiddenError, // .requiredScope names the missing scope
125
- MnemaSubscriptionError, // .billingUrl is where the person fixes it
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
- async function rpcCall(opts, tool, args) {
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
- tool
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 body2 = await res.text().catch(() => "");
144
- throw new MnemaTransportError(`Mnema HTTP ${res.status}: ${body2.slice(0, 300)}`, res.status, tool);
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, tool);
148
- if (body.error) throw errorFromRpc(body.error, tool);
149
- const result = body.result ?? {};
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 doFetch = opts.fetch ?? globalThis.fetch;
165
- const url = `${opts.baseUrl.replace(/\/+$/, "")}${opts.path ?? "/mcp"}`;
166
- const res = await doFetch(url, {
167
- method: "POST",
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
- const body = await res.json();
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 — run `scripts/gen-types.mjs` against a
203
- * workspace and import the result. Until then this returns `unknown` rather than a
204
- * confident lie, which is the same rule the server's own schema generator follows: an
205
- * unresolved type is an error, never a fallback to `string`.
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 — run `scripts/gen-types.mjs` against a
203
- * workspace and import the result. Until then this returns `unknown` rather than a
204
- * confident lie, which is the same rule the server's own schema generator follows: an
205
- * unresolved type is an error, never a fallback to `string`.
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
- async function rpcCall(opts, tool, args) {
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
- tool
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 body2 = await res.text().catch(() => "");
107
- throw new MnemaTransportError(`Mnema HTTP ${res.status}: ${body2.slice(0, 300)}`, res.status, tool);
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, tool);
111
- if (body.error) throw errorFromRpc(body.error, tool);
112
- const result = body.result ?? {};
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 doFetch = opts.fetch ?? globalThis.fetch;
128
- const url = `${opts.baseUrl.replace(/\/+$/, "")}${opts.path ?? "/mcp"}`;
129
- const res = await doFetch(url, {
130
- method: "POST",
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
- const body = await res.json();
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.0",
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": false
47
+ "released": true
49
48
  },
50
49
  "scripts": {
51
50
  "build": "tsup src/index.ts --format esm,cjs --dts --clean",