tunc-mcp 0.1.0 → 0.1.2

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
@@ -52,13 +91,43 @@ import { orb, art, doc } from 'tunc-mcp';
 
 const memory = orb(); // reads TUNC_API_KEY
 
+// Every tool takes an `operation` that picks what it does. Ask for a shape the
+// server does not have and you get invalid_arguments back, so call listTools()
+// once and read the real schemas rather than trusting an example.
+//
+// data_write  operation: create | append
+// data_read   operation: shelves | list | get | log | search | status
+// data_update operation: replace | patch        (needs if_revision)
+// data_delete operation: record | entries | log (needs if_revision)
+
 // Agent memory: durable records, revision-guarded
 await memory.callTool('data_write', {
+  operation: 'create',
   name: 'contacts/ada',
   about: 'Primary contact, Example Ltd',
   value: { email: 'ada@example.com', timezone: 'Europe/London' },
 });
 
+const record = await memory.callTool('data_read', {
+  operation: 'get',
+  name: 'contacts/ada',
+});
+const revision = JSON.parse(record.content[0].text).revision;
+
+// Change it only if nobody else has, and delete it the same way
+await memory.callTool('data_update', {
+  operation: 'patch',
+  name: 'contacts/ada',
+  if_revision: revision,
+  patch: [{ op: 'replace', path: '/timezone', value: 'Europe/Paris' }],
+});
+
+await memory.callTool('data_delete', {
+  operation: 'record',
+  name: 'contacts/ada',
+  if_revision: revision,
+});
+
 // Artifacts: store a file, get a private link
 const files = art();
 await files.callTool('art_write', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunc-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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,