tunc-mcp 0.0.0-stage → 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

@@ -1,3 +1,209 @@
-# Temporary Holding Version
+# tunc-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Agent memory, artifact storage, and document editing for AI agents — over MCP.**
+
+A small, dependency-free MCP (Model Context Protocol) client for three hosted
+services that AI agents and multi-agent systems actually need:
+
+| Service | What it is | MCP endpoint |
+|---|---|---|
+| **Tunc Orb** | **Agent memory database** — durable records, logs and structured state shared by every agent you run | `https://mcp.tuncorb.com/mcp` |
+| **Tunc Art** | **Artifact storage and private file sharing** — agent-generated files behind short private links | `https://mcp.tuncart.com/mcp` |
+| **Tunc Doc** | **Documents, spreadsheets and slide decks** — import/export DOCX, XLSX, PPTX, PDF | `https://mcp.tuncdoc.com/mcp` |
+
+All three are also reachable over **A2A** (agent-to-agent) and plain **REST**, so
+the same account works whether your agent speaks MCP, A2A, or HTTP.
+
+## Why this exists
+
+Most agent stacks lose state the moment a context window rolls over. Writes from
+two agents at once silently clobber each other. Artifacts end up as files on
+someone's laptop. This gives an agent three boring, reliable primitives instead:
+
+- **Memory that survives the conversation.** Records persist across sessions,
+  across agents, across models. `data_read` / `data_write` / `data_update` /
+  `data_delete`, with revision-guarded writes.
+- **Artifacts with links you can send.** Upload a file, get a short private URL
+  back. No bucket configuration.
+- **Documents an agent can actually produce.** Real DOCX, XLSX and PPTX, not
+  markdown pretending to be a report.
+
+### Concurrency is the interesting part
+
+`data_update` accepts `if_revision`. Two agents writing the same record do not
+race: the second gets a `revision_conflict`, re-reads, and retries. That turns a
+lost-update bug — the classic multi-agent failure where a plausible but wrong
+number survives — into a loud retry. If you run agent swarms that share state,
+use it.
+
+## Install
+
+```bash
+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
+import { orb, art, doc } from 'tunc-mcp';
+
+const memory = orb(); // reads TUNC_API_KEY
+
+// Agent memory: durable records, revision-guarded
+await memory.callTool('data_write', {
+  name: 'contacts/ada',
+  about: 'Primary contact, Example Ltd',
+  value: { email: 'ada@example.com', timezone: 'Europe/London' },
+});
+
+// Artifacts: store a file, get a private link
+const files = art();
+await files.callTool('art_write', {
+  title: 'quarterly-report.pdf',
+  mime_type: 'application/pdf',
+  content_base64: base64Bytes,
+});
+
+// Documents: build something a human can open and edit
+const docs = doc();
+await docs.callTool('doc_create', {
+  title: 'Q4 summary',
+  markdown: '# Q4\n\nRevenue up 12%.',
+});
+```
+
+Discover what any service offers:
+
+```js
+const tools = await orb().listTools();
+console.log(tools.map((t) => t.name).join(', '));
+```
+
+## CLI
+
+```bash
+export TUNC_API_KEY=tunc_...
+
+npx tunc-mcp services
+npx tunc-mcp tools --service orb
+npx tunc-mcp call data_read '{"name":"contacts/ada"}' --service orb
+```
+
+## Wire it into an MCP client
+
+Any MCP-capable host works — Claude Desktop, Cursor, Claude Code, Codex, a custom
+orchestrator. Point it at the endpoint and pass the key as a bearer header:
+
+```json
+{
+  "mcpServers": {
+    "tunc-orb": {
+      "type": "http",
+      "url": "https://mcp.tuncorb.com/mcp",
+      "headers": { "Authorization": "Bearer ${TUNC_API_KEY}" }
+    }
+  }
+}
+```
+
+## Agent-to-agent
+
+Every service publishes an A2A agent card, so agents that speak A2A can discover
+and call them without a human in the loop:
+
+- <https://tuncorb.com/.well-known/agent-card.json>
+- <https://tuncart.com/.well-known/agent-card.json>
+- <https://tuncdoc.com/.well-known/agent-card.json>
+
+## What this package does not do
+
+It is a client. It does not host anything, and it does not bundle an agent
+runtime. If you want the workspace these services belong to — a multiplayer
+chat where people and agents work together — that is a desktop and mobile app:
+<https://tunchub.com>.
+
+## Errors
+
+Everything throws `TuncMcpError` with a `status`, a `code` and the server's
+message. A `401` means the key is missing, revoked, or not scoped for that
+service; the message says which.
+
+## 中文
+
+**面向 AI 智能体的记忆数据库、制品存储与文档编辑 —— 通过 MCP 接入。**
+
+`tunc-mcp` 是一个零依赖的 MCP 客户端，连接三个托管服务，解决多智能体系统里最常见的问题：
+
+| 服务 | 用途 | 接入点 |
+|---|---|---|
+| **Tunc Orb** | **智能体记忆数据库** —— 持久保存记录、日志与结构化状态，可在所有智能体之间共享 | `https://mcp.tuncorb.com/mcp` |
+| **Tunc Art** | **制品存储与文件分享** —— 保存智能体生成的文件，返回私密短链接 | `https://mcp.tuncart.com/mcp` |
+| **Tunc Doc** | **文档、表格与幻灯片** —— 可导入导出 DOCX、XLSX、PPTX、PDF | `https://mcp.tuncdoc.com/mcp` |
+
+三个服务同时支持 **MCP**、**A2A**（智能体间通信）与 **REST**，同一个账号即可通用。
+
+### 为什么需要它
+
+多数智能体框架在上下文窗口滚动之后就会丢失状态；两个智能体同时写入会互相覆盖；生成的制品散落在本地磁盘上。这里提供三个朴素可靠的基础能力：
+
+- **能跨越对话的记忆。** 记录跨会话、跨智能体、跨模型持久保存，写入支持 `if_revision` 乐观并发控制。
+- **可分享的制品链接。** 上传文件即得到私密短链接，无需配置对象存储。
+- **智能体能够真正产出的文档。** 真实的 DOCX、XLSX 与 PPTX，而不是伪装成报告的 Markdown。
+
+### 并发写入
+
+`data_update` 接受 `if_revision`。两个智能体写同一条记录时不会互相覆盖：后到的写入收到 `revision_conflict`，重新读取后重试。这把多智能体最常见的“静默丢更新”故障，变成一个可以被发现的错误。
+
+```bash
+npm install tunc-mcp
+```
+
+API 密钥：<https://tunchub.com/account/keys/new>（可设为只读）。
+
+完整的多人协作工作空间（人与多个智能体共享同一实时对话）见 <https://tunchub.com>。
+
+## License
+
+MIT © TUNC LLC

package/bin/cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// tunc-mcp — inspect and call the Tunc MCP servers from a terminal.
+//
+//   export TUNC_API_KEY=tunc_...
+//   npx tunc-mcp tools --service orb
+//   npx tunc-mcp call data_read '{"name":"contacts/ada"}'
+
+import { SERVERS, TuncMcpClient, TuncMcpError } from '../src/client.js';
+
+const USAGE = `tunc-mcp — MCP client for Tunc Orb, Tunc Art and Tunc Doc
+
+Usage:
+  tunc-mcp services
+  tunc-mcp tools   [--service orb|art|doc] [--json]
+  tunc-mcp call <tool> [json-args] [--service orb|art|doc]
+
+Environment:
+  TUNC_API_KEY   required. Create one at https://tunchub.com/account/keys/new
+`;
+
+function parseArgs(argv) {
+  const args = { _: [], service: 'orb', json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--service') args.service = argv[++i];
+    else if (arg === '--json') args.json = true;
+    else if (arg === '--help' || arg === '-h') args.help = true;
+    else args._.push(arg);
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const [command, ...rest] = args._;
+
+  if (args.help || !command || command === 'services') {
+    if (command === 'services') {
+      console.log(JSON.stringify(SERVERS, null, 2));
+      return;
+    }
+    console.log(USAGE);
+    return;
+  }
+
+  const client = new TuncMcpClient({ service: args.service });
+
+  if (command === 'tools') {
+    const tools = await client.listTools();
+    if (args.json) {
+      console.log(JSON.stringify(tools, null, 2));
+      return;
+    }
+    console.log(`${tools.length} tools on ${args.service} (${client.endpoint})\n`);
+    for (const tool of tools) {
+      console.log(`  ${tool.name}${tool.description ? ` — ${tool.description.split('.')[0]}` : ''}`);
+    }
+    return;
+  }
+
+  if (command === 'call') {
+    const [name, rawArgs] = rest;
+    if (!name) {
+      console.error('call needs a tool name. Run: tunc-mcp tools');
+      process.exitCode = 1;
+      return;
+    }
+    let parsed = {};
+    if (rawArgs) {
+      try {
+        parsed = JSON.parse(rawArgs);
+      } catch {
+        console.error('That is not valid JSON. Quote it, e.g. \'{"name":"x"}\'');
+        process.exitCode = 1;
+        return;
+      }
+    }
+    const result = await client.callTool(name, parsed);
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.error(`Unknown command: ${command}\n`);
+  console.log(USAGE);
+  process.exitCode = 1;
+}
+
+main().catch((error) => {
+  if (error instanceof TuncMcpError) {
+    console.error(`tunc-mcp: ${error.message}`);
+    if (error.status) console.error(`  HTTP ${error.status}`);
+  } else {
+    console.error(`tunc-mcp: ${error.message}`);
+  }
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "tunc-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+    "model-context-protocol",
+    "agent-memory",
+    "agent-database",
+    "memory",
+    "agent",
+    "agents",
+    "multi-agent",
+    "multi-agent-orchestration",
+    "artifact",
+    "artifacts",
+    "artifact-storage",
+    "file-sharing",
+    "private-links",
+    "storage",
+    "database",
+    "records",
+    "documents",
+    "spreadsheets",
+    "slide-decks",
+    "a2a",
+    "agent-to-agent",
+    "ai-agents",
+    "llm",
+    "tunc"
+  ],
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js"
+  },
+  "bin": {
+    "tunc-mcp": "./bin/cli.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "license": "MIT",
+  "homepage": "https://tuncorb.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TUNC-AI/tunc-mcp.git"
+  }
+}

package/src/client.js

@@ -0,0 +1,182 @@
+// Minimal MCP (Model Context Protocol) client over streamable HTTP.
+//
+// It speaks just enough of the protocol to talk to the Tunc servers: initialize,
+// tools/list and tools/call, with JSON-RPC 2.0 envelopes and event-stream
+// responses. No dependencies; Node 18+ fetch only.
+//
+// Servers:
+//   Tunc Orb  https://mcp.tuncorb.com/mcp   agent memory database
+//   Tunc Art  https://mcp.tuncart.com/mcp   artifact storage, private links
+//   Tunc Doc  https://mcp.tuncdoc.com/mcp   documents, spreadsheets, decks
+
+export const SERVERS = Object.freeze({
+  orb: 'https://mcp.tuncorb.com/mcp',
+  art: 'https://mcp.tuncart.com/mcp',
+  doc: 'https://mcp.tuncdoc.com/mcp',
+});
+
+export class TuncMcpError extends Error {
+  constructor(message, { code, status, body } = {}) {
+    super(message);
+    this.name = 'TuncMcpError';
+    this.code = code;
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/**
+ * Pull the JSON-RPC payload out of an event-stream body, or a plain JSON body.
+ * Streamable HTTP lets a server answer either way; Tunc answers JSON, other
+ * MCP servers may answer text/event-stream, so both are handled.
+ */
+export function parseBody(contentType, text) {
+  if (!text) return null;
+  if (!/text\/event-stream/i.test(contentType ?? '')) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  }
+
+  let last = null;
+  for (const block of text.split(/\r?\n\r?\n/)) {
+    const data = block
+      .split(/\r?\n/)
+      .filter((line) => line.startsWith('data:'))
+      .map((line) => line.slice(5).trimStart())
+      .join('\n');
+    if (!data) continue;
+    try {
+      last = JSON.parse(data);
+    } catch {
+      // A partial frame: keep the previous complete one.
+    }
+  }
+  return last;
+}
+
+export class TuncMcpClient {
+  #endpoint;
+  #apiKey;
+  #sessionId = null;
+  #nextId = 1;
+  #initialized = false;
+
+  constructor({ service = 'orb', endpoint, apiKey }) {
+    this.#endpoint = endpoint ?? SERVERS[service];
+    if (!this.#endpoint) {
+      throw new TuncMcpError(`Unknown service "${service}". Use orb, art or doc, or pass an endpoint.`);
+    }
+    this.#apiKey = apiKey ?? process.env.TUNC_API_KEY;
+    if (!this.#apiKey) {
+      throw new TuncMcpError(
+        'No API key. Pass apiKey or set TUNC_API_KEY. Create one at https://tunchub.com/account/keys/new',
+      );
+    }
+  }
+
+  get endpoint() {
+    return this.#endpoint;
+  }
+
+  async #post(payload) {
+    const headers = {
+      'content-type': 'application/json',
+      accept: 'application/json, text/event-stream',
+      authorization: `Bearer ${this.#apiKey}`,
+    };
+    if (this.#sessionId) headers['mcp-session-id'] = this.#sessionId;
+
+    const response = await fetch(this.#endpoint, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(payload),
+    });
+
+    const session = response.headers.get('mcp-session-id');
+    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(
+        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 },
+      );
+    }
+
+    if (!response.ok) {
+      throw new TuncMcpError(body?.error?.message ?? `HTTP ${response.status}`, {
+        status: response.status,
+        code: body?.error?.code,
+        body,
+      });
+    }
+
+    if (body?.error) {
+      throw new TuncMcpError(body.error.message ?? 'JSON-RPC error', {
+        code: body.error.code,
+        status: response.status,
+        body,
+      });
+    }
+
+    return body?.result;
+  }
+
+  async #rpc(method, params) {
+    return this.#post({ jsonrpc: '2.0', id: this.#nextId++, method, params });
+  }
+
+  async initialize() {
+    if (this.#initialized) return this;
+    const result = await this.#rpc('initialize', {
+      protocolVersion: '2025-06-18',
+      capabilities: {},
+      clientInfo: { name: 'tunc-mcp', version: '0.1.0' },
+    });
+    // Notifications carry no id and expect no body.
+    await fetch(this.#endpoint, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json, text/event-stream',
+        authorization: `Bearer ${this.#apiKey}`,
+        ...(this.#sessionId ? { 'mcp-session-id': this.#sessionId } : {}),
+      },
+      body: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }),
+    }).catch(() => {});
+    this.serverInfo = result?.serverInfo ?? null;
+    this.capabilities = result?.capabilities ?? null;
+    this.#initialized = true;
+    return this;
+  }
+
+  async listTools() {
+    await this.initialize();
+    const result = await this.#rpc('tools/list', {});
+    return result?.tools ?? [];
+  }
+
+  async callTool(name, args = {}) {
+    await this.initialize();
+    return this.#rpc('tools/call', { name, arguments: args });
+  }
+
+  /** Convenience: the text content of a tool result, joined. */
+  async callText(name, args = {}) {
+    const result = await this.callTool(name, args);
+    const parts = Array.isArray(result?.content) ? result.content : [];
+    const text = parts.filter((p) => p?.type === 'text').map((p) => p.text).join('\n');
+    return text || result;
+  }
+}

package/src/index.js

@@ -0,0 +1,33 @@
+// Convenience layer over the three Tunc MCP servers.
+//
+// Tunc Orb — agent memory database: durable records and logs for agents and
+//            agent swarms, revision-guarded so concurrent writers cannot clobber.
+// Tunc Art — artifact storage and private file sharing: agent-generated files
+//            with short private links.
+// Tunc Doc — documents, spreadsheets and slide decks, import/export DOCX,
+//            XLSX, PPTX and PDF.
+
+import { SERVERS, TuncMcpClient, TuncMcpError, parseBody } from './client.js';
+
+export { SERVERS, TuncMcpClient, TuncMcpError, parseBody };
+
+export function orb(options = {}) {
+  return new TuncMcpClient({ service: 'orb', ...options });
+}
+
+export function art(options = {}) {
+  return new TuncMcpClient({ service: 'art', ...options });
+}
+
+export function doc(options = {}) {
+  return new TuncMcpClient({ service: 'doc', ...options });
+}
+
+/** All three clients from one key. */
+export function connect(apiKey = process.env.TUNC_API_KEY) {
+  return {
+    orb: orb({ apiKey }),
+    art: art({ apiKey }),
+    doc: doc({ apiKey }),
+  };
+}