tunc-mcp 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TUNC LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -45,6 +45,45 @@ npm install tunc-mcp
 Node 18 or newer. No dependencies. Get an API key at
 <https://tunchub.com/account/keys/new> — you can scope it read-only.
 
+## Options
+
+Every helper takes an object. Only the key is required, and it falls back to `TUNC_API_KEY`.
+
+```js
+import { orb, art, doc, connect, SERVERS } from 'tunc-mcp';
+
+const memory = orb({
+  apiKey: process.env.TUNC_API_KEY,
+  endpoint: 'https://mcp.tuncorb.com/mcp', // override: staging, a proxy, or a local mock
+});
+```
+
+- `apiKey` — defaults to `TUNC_API_KEY`. It is checked when the client is constructed, so a missing key fails immediately rather than on the first call.
+- `endpoint` — replaces the built-in URL for that service. This is what you use to point the client at a test server.
+- `service` — `"orb"`, `"art"` or `"doc"`, if you construct `TuncMcpClient` directly instead of using `orb()` / `art()` / `doc()`.
+
+`SERVERS` is the map of default endpoints. `connect(key)` returns all three clients at once.
+
+## What comes back
+
+`callTool()` returns the server's MCP result unchanged:
+
+```js
+{ content: [{ type: "text", text: "<json string>" }], structuredContent: { /* … */ }, isError: false }
+```
+
+Confusingly, the same payload often appears twice — as `structuredContent` and again serialised into `content[0].text`. Use `structuredContent` when it is there. When you only want the text, `callText()` unwraps it for you:
+
+```js
+const text = await memory.callText('data_read', { name: 'contacts/ada' });
+```
+
+Tool names come from the server, not from this package. Call `listTools()` to see what a service actually offers before writing against it — the list is not hard-coded here and changes as the servers change.
+
+## ESM only
+
+This package is ESM. In a CommonJS project, either set `"type": "module"` in `package.json` or import it from an `.mjs` file. Otherwise Node fails with `SyntaxError: Cannot use import statement outside a module`.
+
 ## Use
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunc-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP client for Tunc Orb (agent memory database), Tunc Art (artifact storage and private file sharing) and Tunc Doc (documents, spreadsheets, decks).",
   "keywords": [
     "mcp",

package/src/client.js

@@ -99,16 +99,21 @@ export class TuncMcpClient {
     if (session) this.#sessionId = session;
 
     const text = await response.text();
+    const body = parseBody(response.headers.get('content-type'), text);
 
     if (response.status === 401) {
+      // The server knows why it refused: missing key, revoked, or wrong scope.
+      // Keep its words and add ours, rather than replacing a specific answer
+      // with a generic one.
+      const server = body?.error?.message;
       throw new TuncMcpError(
-        'Unauthorized. The API key is missing, revoked, or not scoped for this service.',
-        { status: 401, body: text },
+        server
+          ? `${server} (the API key is missing, revoked, or not scoped for this service)`
+          : 'Unauthorized. The API key is missing, revoked, or not scoped for this service.',
+        { status: 401, code: body?.error?.code, body },
       );
     }
 
-    const body = parseBody(response.headers.get('content-type'), text);
-
     if (!response.ok) {
       throw new TuncMcpError(body?.error?.message ?? `HTTP ${response.status}`, {
         status: response.status,