tunc-mcp 0.1.0__tar.gz

tunc_mcp-0.1.0/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.

tunc_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: tunc-mcp
+Version: 0.1.0
+Summary: MCP client for Tunc Orb (agent memory database), Tunc Art (artifact storage and private file sharing) and Tunc Doc (documents, spreadsheets, decks).
+Author-email: TUNC LLC <hello@tunc.ai>
+License: MIT
+Project-URL: Homepage, https://tuncorb.com
+Project-URL: Repository, https://github.com/TUNC-AI/tunc-mcp-python
+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
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# tunc-mcp
+
+**Agent memory, artifact storage, and document editing for AI agents — over MCP.**
+
+A small, dependency-free MCP (Model Context Protocol) client in Python 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, 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` takes `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.
+
+## Install
+
+```bash
+pip install tunc-mcp
+```
+
+Python 3.9 or newer. No dependencies. Get an API key at
+<https://tunchub.com/account/keys/new> — you can scope it read-only.
+
+## Use
+
+```python
+from tunc_mcp import orb, art, doc
+
+memory = orb()          # reads TUNC_API_KEY
+
+# Every tool takes an `operation` that picks what it does. Call list_tools()
+# 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)
+
+memory.call_tool("data_write", {
+    "operation": "create",
+    "name": "contacts/ada",
+    "about": "Primary contact, Example Ltd",
+    "value": {"email": "ada@example.com", "timezone": "Europe/London"},
+})
+
+record = memory.call_tool("data_read", {"operation": "get", "name": "contacts/ada"})
+revision = record["structuredContent"]["revision"]
+
+memory.call_tool("data_update", {
+    "operation": "patch",
+    "name": "contacts/ada",
+    "if_revision": revision,
+    "patch": [{"op": "replace", "path": "/timezone", "value": "Europe/Paris"}],
+})
+
+memory.call_tool("data_delete", {"operation": "record", "name": "contacts/ada", "if_revision": revision})
+```
+
+Artifacts — `art_write` takes `operation: create` and a `name`, and the result
+keys the artifact by `id`:
+
+```python
+files = art()
+stored = files.call_tool("art_write", {
+    "operation": "create",
+    "name": "quarterly-report.pdf",
+    "mime_type": "application/pdf",
+    "content_base64": base64_bytes,
+})
+artifact_id = stored["structuredContent"]["artifact"]["id"]
+
+files.call_tool("art_read", {"operation": "get", "artifact_id": artifact_id})
+files.call_tool("art_delete", {"artifact_id": artifact_id})
+```
+
+Documents — `doc_create` needs only a title and returns the document under
+`result.doc.id`; every other doc tool addresses it with `doc`:
+
+```python
+docs = doc()
+made = docs.call_tool("doc_create", {"title": "Q4 summary", "markdown": "# Q4\n\nRevenue up 12%."})
+doc_id = made["structuredContent"]["result"]["doc"]["id"]
+
+docs.call_tool("doc_read", {"doc": doc_id})
+docs.call_tool("doc_delete", {"doc": doc_id})
+```
+
+Discover what any service offers:
+
+```python
+for tool in orb().list_tools():
+    print(tool["name"], tool.get("inputSchema", {}).get("required"))
+```
+
+## CLI
+
+```bash
+export TUNC_API_KEY=...
+
+tunc-mcp services
+tunc-mcp tools --service orb
+tunc-mcp call data_read '{"operation": "get", "name": "contacts/ada"}' --service orb
+```
+
+## Options
+
+```python
+memory = orb(
+    api_key="...",                      # or TUNC_API_KEY in the environment
+    endpoint="https://mcp.tuncorb.com/mcp",  # override: staging, a proxy, a local mock
+)
+```
+
+- `api_key` — defaults to `TUNC_API_KEY`. Checked when the client is constructed.
+- `endpoint` — replaces the built-in URL for that service, which is how you point
+  it 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.
+
+## Wire it into an MCP client
+
+Any MCP-capable host works. Point it at the endpoint and pass the key as a
+bearer header. For a Python host, the usual shape is:
+
+```python
+from tunc_mcp import orb
+client = orb()
+tools = client.list_tools()
+```
+
+## OAuth instead of a key
+
+The servers accept a resource-bound OAuth token as well as an API key. That
+matters for Doc: **`mcp.tuncdoc.com` advertises the same scope names as Orb
+(`orb.read`, `orb.write`, `orb.delete`)**, so a token without a resource binding
+defaults to the Orb audience and is rejected by Doc with "not scoped for this
+service". Include the resource when you request the device grant:
+
+```
+resource=https://mcp.tuncdoc.com/mcp
+```
+
+```python
+TuncMcpClient(service="doc", api_key=device_access_token)
+```
+
+## 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 raises `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` 是一个零依赖的 Python 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**，同一个账号即可通用。
+
+```bash
+pip install tunc-mcp
+```
+
+API 密钥：<https://tunchub.com/account/keys/new>（可设为只读）。
+
+### 并发写入
+
+`data_update` 接受 `if_revision`。两个智能体写同一条记录时不会互相覆盖：后到的写入收到 `revision_conflict`，重新读取后重试。这把多智能体最常见的“静默丢更新”故障，变成一个可以被发现的错误。
+
+完整的多人协作工作空间（人与多个智能体共享同一实时对话）见 <https://tunchub.com>。
+
+## License
+
+MIT © TUNC LLC

tunc_mcp-0.1.0/README.md

@@ -0,0 +1,222 @@
+# tunc-mcp
+
+**Agent memory, artifact storage, and document editing for AI agents — over MCP.**
+
+A small, dependency-free MCP (Model Context Protocol) client in Python 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, 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` takes `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.
+
+## Install
+
+```bash
+pip install tunc-mcp
+```
+
+Python 3.9 or newer. No dependencies. Get an API key at
+<https://tunchub.com/account/keys/new> — you can scope it read-only.
+
+## Use
+
+```python
+from tunc_mcp import orb, art, doc
+
+memory = orb()          # reads TUNC_API_KEY
+
+# Every tool takes an `operation` that picks what it does. Call list_tools()
+# 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)
+
+memory.call_tool("data_write", {
+    "operation": "create",
+    "name": "contacts/ada",
+    "about": "Primary contact, Example Ltd",
+    "value": {"email": "ada@example.com", "timezone": "Europe/London"},
+})
+
+record = memory.call_tool("data_read", {"operation": "get", "name": "contacts/ada"})
+revision = record["structuredContent"]["revision"]
+
+memory.call_tool("data_update", {
+    "operation": "patch",
+    "name": "contacts/ada",
+    "if_revision": revision,
+    "patch": [{"op": "replace", "path": "/timezone", "value": "Europe/Paris"}],
+})
+
+memory.call_tool("data_delete", {"operation": "record", "name": "contacts/ada", "if_revision": revision})
+```
+
+Artifacts — `art_write` takes `operation: create` and a `name`, and the result
+keys the artifact by `id`:
+
+```python
+files = art()
+stored = files.call_tool("art_write", {
+    "operation": "create",
+    "name": "quarterly-report.pdf",
+    "mime_type": "application/pdf",
+    "content_base64": base64_bytes,
+})
+artifact_id = stored["structuredContent"]["artifact"]["id"]
+
+files.call_tool("art_read", {"operation": "get", "artifact_id": artifact_id})
+files.call_tool("art_delete", {"artifact_id": artifact_id})
+```
+
+Documents — `doc_create` needs only a title and returns the document under
+`result.doc.id`; every other doc tool addresses it with `doc`:
+
+```python
+docs = doc()
+made = docs.call_tool("doc_create", {"title": "Q4 summary", "markdown": "# Q4\n\nRevenue up 12%."})
+doc_id = made["structuredContent"]["result"]["doc"]["id"]
+
+docs.call_tool("doc_read", {"doc": doc_id})
+docs.call_tool("doc_delete", {"doc": doc_id})
+```
+
+Discover what any service offers:
+
+```python
+for tool in orb().list_tools():
+    print(tool["name"], tool.get("inputSchema", {}).get("required"))
+```
+
+## CLI
+
+```bash
+export TUNC_API_KEY=...
+
+tunc-mcp services
+tunc-mcp tools --service orb
+tunc-mcp call data_read '{"operation": "get", "name": "contacts/ada"}' --service orb
+```
+
+## Options
+
+```python
+memory = orb(
+    api_key="...",                      # or TUNC_API_KEY in the environment
+    endpoint="https://mcp.tuncorb.com/mcp",  # override: staging, a proxy, a local mock
+)
+```
+
+- `api_key` — defaults to `TUNC_API_KEY`. Checked when the client is constructed.
+- `endpoint` — replaces the built-in URL for that service, which is how you point
+  it 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.
+
+## Wire it into an MCP client
+
+Any MCP-capable host works. Point it at the endpoint and pass the key as a
+bearer header. For a Python host, the usual shape is:
+
+```python
+from tunc_mcp import orb
+client = orb()
+tools = client.list_tools()
+```
+
+## OAuth instead of a key
+
+The servers accept a resource-bound OAuth token as well as an API key. That
+matters for Doc: **`mcp.tuncdoc.com` advertises the same scope names as Orb
+(`orb.read`, `orb.write`, `orb.delete`)**, so a token without a resource binding
+defaults to the Orb audience and is rejected by Doc with "not scoped for this
+service". Include the resource when you request the device grant:
+
+```
+resource=https://mcp.tuncdoc.com/mcp
+```
+
+```python
+TuncMcpClient(service="doc", api_key=device_access_token)
+```
+
+## 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 raises `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` 是一个零依赖的 Python 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**，同一个账号即可通用。
+
+```bash
+pip install tunc-mcp
+```
+
+API 密钥：<https://tunchub.com/account/keys/new>（可设为只读）。
+
+### 并发写入
+
+`data_update` 接受 `if_revision`。两个智能体写同一条记录时不会互相覆盖：后到的写入收到 `revision_conflict`，重新读取后重试。这把多智能体最常见的“静默丢更新”故障，变成一个可以被发现的错误。
+
+完整的多人协作工作空间（人与多个智能体共享同一实时对话）见 <https://tunchub.com>。
+
+## License
+
+MIT © TUNC LLC

tunc_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tunc-mcp"
+version = "0.1.0"
+description = "MCP client for Tunc Orb (agent memory database), Tunc Art (artifact storage and private file sharing) and Tunc Doc (documents, spreadsheets, decks)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "TUNC LLC", email = "hello@tunc.ai" }]
+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",
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.optional-dependencies]
+# The protocol work here is a few hundred lines against three fixed endpoints,
+# so the package stays dependency-free; this extra is only for running tests.
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://tuncorb.com"
+Repository = "https://github.com/TUNC-AI/tunc-mcp-python"
+
+[project.scripts]
+tunc-mcp = "tunc_mcp.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

tunc_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tunc_mcp-0.1.0/src/tunc_mcp/__init__.py

@@ -0,0 +1,27 @@
+"""tunc-mcp — MCP client for Tunc Orb, Tunc Art and Tunc Doc."""
+
+from .client import (
+    PROTOCOL_VERSION,
+    SERVERS,
+    TuncMcpClient,
+    TuncMcpError,
+    art,
+    connect,
+    doc,
+    orb,
+    parse_body,
+)
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "SERVERS",
+    "TuncMcpClient",
+    "TuncMcpError",
+    "art",
+    "connect",
+    "doc",
+    "orb",
+    "parse_body",
+]
+
+__version__ = "0.1.0"

tunc_mcp-0.1.0/src/tunc_mcp/cli.py

@@ -0,0 +1,86 @@
+"""Command line: inspect and call the Tunc MCP servers.
+
+    export TUNC_API_KEY=...
+    tunc-mcp services
+    tunc-mcp tools --service orb
+    tunc-mcp call data_read '{"operation": "get", "name": "contacts/ada"}'
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import List, Optional
+
+from .client import SERVERS, TuncMcpClient, TuncMcpError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="tunc-mcp", description="MCP client for Tunc Orb, Tunc Art and Tunc Doc.")
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("services", help="print the built-in endpoints")
+
+    tools = sub.add_parser("tools", help="list the tools a service offers")
+    tools.add_argument("--service", default="orb", choices=sorted(SERVERS))
+    tools.add_argument("--json", action="store_true", help="print the raw schema JSON")
+
+    call = sub.add_parser("call", help="call one tool")
+    call.add_argument("tool")
+    call.add_argument("arguments", nargs="?", default="{}", help="JSON object")
+    call.add_argument("--service", default="orb", choices=sorted(SERVERS))
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "services":
+        print(json.dumps(SERVERS, indent=2))
+        return 0
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    try:
+        client = TuncMcpClient(service=args.service)
+    except TuncMcpError as error:
+        print(f"tunc-mcp: {error}", file=sys.stderr)
+        return 1
+
+    try:
+        if args.command == "tools":
+            tools = client.list_tools()
+            if args.json:
+                print(json.dumps(tools, indent=2))
+                return 0
+            print(f"{len(tools)} tools on {args.service} ({client.endpoint})\n")
+            for tool in tools:
+                summary = (tool.get("description") or "").split(".")[0]
+                print(f"  {tool.get('name')}" + (f" — {summary}" if summary else ""))
+            return 0
+
+        if args.command == "call":
+            try:
+                arguments = json.loads(args.arguments)
+            except ValueError:
+                print("tunc-mcp: arguments must be a JSON object", file=sys.stderr)
+                return 1
+            print(json.dumps(client.call_tool(args.tool, arguments), indent=2))
+            return 0
+    except TuncMcpError as error:
+        print(f"tunc-mcp: {error}", file=sys.stderr)
+        if error.status:
+            print(f"  HTTP {error.status}", file=sys.stderr)
+        return 1
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tunc_mcp-0.1.0/src/tunc_mcp/client.py

@@ -0,0 +1,198 @@
+"""Minimal MCP (Model Context Protocol) client over streamable HTTP.
+
+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. Standard library 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
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+import uuid
+from typing import Any, Dict, List, Optional
+
+SERVERS = {
+    "orb": "https://mcp.tuncorb.com/mcp",
+    "art": "https://mcp.tuncart.com/mcp",
+    "doc": "https://mcp.tuncdoc.com/mcp",
+}
+
+PROTOCOL_VERSION = "2025-06-18"
+
+
+class TuncMcpError(Exception):
+    """An MCP or HTTP failure, carrying what the server actually said."""
+
+    def __init__(self, message: str, status: Optional[int] = None, code: Any = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.body = body
+
+
+def parse_body(content_type: str, text: str) -> Optional[dict]:
+    """Return the JSON-RPC payload from an event-stream or 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.
+    """
+    if not text:
+        return None
+    if "text/event-stream" not in (content_type or ""):
+        try:
+            return json.loads(text)
+        except ValueError:
+            return None
+
+    last = None
+    for block in text.replace("\r\n", "\n").split("\n\n"):
+        data = "\n".join(
+            line[5:].lstrip() for line in block.split("\n") if line.startswith("data:")
+        )
+        if not data:
+            continue
+        try:
+            last = json.loads(data)
+        except ValueError:
+            # A partial frame: keep the previous complete one.
+            continue
+    return last
+
+
+class TuncMcpClient:
+    def __init__(self, service: str = "orb", endpoint: Optional[str] = None, api_key: Optional[str] = None):
+        self.endpoint = endpoint or SERVERS.get(service)
+        if not self.endpoint:
+            raise TuncMcpError(f'Unknown service "{service}". Use orb, art or doc, or pass an endpoint.')
+        self.api_key = api_key or os.environ.get("TUNC_API_KEY")
+        if not self.api_key:
+            raise TuncMcpError(
+                "No API key. Pass api_key or set TUNC_API_KEY. "
+                "Create one at https://tunchub.com/account/keys/new"
+            )
+        self.session_id: Optional[str] = None
+        self._next_id = 1
+        self._initialized = False
+        self.server_info: Optional[dict] = None
+        self.capabilities: Optional[dict] = None
+
+    # -- transport ---------------------------------------------------------
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {
+            "content-type": "application/json",
+            "accept": "application/json, text/event-stream",
+            "authorization": f"Bearer {self.api_key}",
+            # Cloudflare in front of the Tunc endpoints rejects urllib's default
+            # "Python-urllib/3.x" agent with a 403, which looks like an auth
+            # failure but is not. Always send a real agent.
+            "user-agent": "tunc-mcp-python/0.1.0",
+        }
+        if self.session_id:
+            headers["mcp-session-id"] = self.session_id
+        return headers
+
+    def _post(self, payload: dict) -> Any:
+        data = json.dumps(payload).encode("utf-8")
+        request = urllib.request.Request(self.endpoint, data=data, headers=self._headers(), method="POST")
+        try:
+            with urllib.request.urlopen(request, timeout=60) as response:
+                session = response.headers.get("mcp-session-id")
+                if session:
+                    self.session_id = session
+                text = response.read().decode("utf-8", "replace")
+                content_type = response.headers.get("content-type", "")
+        except urllib.error.HTTPError as error:
+            text = error.read().decode("utf-8", "replace")
+            body = parse_body(error.headers.get("content-type", ""), text)
+            server_message = (body or {}).get("error", {}).get("message")
+            if error.code == 401:
+                raise TuncMcpError(
+                    f"{server_message} (the API key is missing, revoked, or not scoped for this service)"
+                    if server_message
+                    else "Unauthorized. The API key is missing, revoked, or not scoped for this service.",
+                    status=401,
+                    code=(body or {}).get("error", {}).get("code"),
+                    body=body,
+                ) from None
+            raise TuncMcpError(
+                server_message or f"HTTP {error.code}", status=error.code, body=body
+            ) from None
+
+        body = parse_body(content_type, text)
+        if body and body.get("error"):
+            raise TuncMcpError(
+                body["error"].get("message", "JSON-RPC error"), code=body["error"].get("code"), body=body
+            )
+        return (body or {}).get("result")
+
+    def _rpc(self, method: str, params: Optional[dict] = None) -> Any:
+        payload = {"jsonrpc": "2.0", "id": self._next_id, "method": method}
+        if params is not None:
+            payload["params"] = params
+        self._next_id += 1
+        return self._post(payload)
+
+    # -- protocol ----------------------------------------------------------
+
+    def initialize(self) -> "TuncMcpClient":
+        if self._initialized:
+            return self
+        result = self._rpc(
+            "initialize",
+            {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {},
+                "clientInfo": {"name": "tunc-mcp-python", "version": "0.1.0"},
+            },
+        )
+        # A notification carries no id and expects no body.
+        try:
+            self._post({"jsonrpc": "2.0", "method": "notifications/initialized"})
+        except TuncMcpError:
+            pass
+        self.server_info = (result or {}).get("serverInfo")
+        self.capabilities = (result or {}).get("capabilities")
+        self._initialized = True
+        return self
+
+    def list_tools(self) -> List[dict]:
+        self.initialize()
+        return (self._rpc("tools/list", {}) or {}).get("tools", [])
+
+    def call_tool(self, name: str, arguments: Optional[dict] = None) -> Any:
+        self.initialize()
+        return self._rpc("tools/call", {"name": name, "arguments": arguments or {}})
+
+    def call_text(self, name: str, arguments: Optional[dict] = None) -> str:
+        """The text content of a tool result, joined."""
+        result = self.call_tool(name, arguments)
+        parts = result.get("content", []) if isinstance(result, dict) else []
+        text = "\n".join(p.get("text", "") for p in parts if isinstance(p, dict) and p.get("type") == "text")
+        return text or json.dumps(result)
+
+
+def orb(**kwargs: Any) -> TuncMcpClient:
+    return TuncMcpClient(service="orb", **kwargs)
+
+
+def art(**kwargs: Any) -> TuncMcpClient:
+    return TuncMcpClient(service="art", **kwargs)
+
+
+def doc(**kwargs: Any) -> TuncMcpClient:
+    return TuncMcpClient(service="doc", **kwargs)
+
+
+def connect(api_key: Optional[str] = None) -> Dict[str, TuncMcpClient]:
+    """All three clients from one key."""
+    key = api_key or os.environ.get("TUNC_API_KEY")
+    return {"orb": orb(api_key=key), "art": art(api_key=key), "doc": doc(api_key=key)}

tunc_mcp-0.1.0/src/tunc_mcp.egg-info/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: tunc-mcp
+Version: 0.1.0
+Summary: MCP client for Tunc Orb (agent memory database), Tunc Art (artifact storage and private file sharing) and Tunc Doc (documents, spreadsheets, decks).
+Author-email: TUNC LLC <hello@tunc.ai>
+License: MIT
+Project-URL: Homepage, https://tuncorb.com
+Project-URL: Repository, https://github.com/TUNC-AI/tunc-mcp-python
+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
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# tunc-mcp
+
+**Agent memory, artifact storage, and document editing for AI agents — over MCP.**
+
+A small, dependency-free MCP (Model Context Protocol) client in Python 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, 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` takes `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.
+
+## Install
+
+```bash
+pip install tunc-mcp
+```
+
+Python 3.9 or newer. No dependencies. Get an API key at
+<https://tunchub.com/account/keys/new> — you can scope it read-only.
+
+## Use
+
+```python
+from tunc_mcp import orb, art, doc
+
+memory = orb()          # reads TUNC_API_KEY
+
+# Every tool takes an `operation` that picks what it does. Call list_tools()
+# 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)
+
+memory.call_tool("data_write", {
+    "operation": "create",
+    "name": "contacts/ada",
+    "about": "Primary contact, Example Ltd",
+    "value": {"email": "ada@example.com", "timezone": "Europe/London"},
+})
+
+record = memory.call_tool("data_read", {"operation": "get", "name": "contacts/ada"})
+revision = record["structuredContent"]["revision"]
+
+memory.call_tool("data_update", {
+    "operation": "patch",
+    "name": "contacts/ada",
+    "if_revision": revision,
+    "patch": [{"op": "replace", "path": "/timezone", "value": "Europe/Paris"}],
+})
+
+memory.call_tool("data_delete", {"operation": "record", "name": "contacts/ada", "if_revision": revision})
+```
+
+Artifacts — `art_write` takes `operation: create` and a `name`, and the result
+keys the artifact by `id`:
+
+```python
+files = art()
+stored = files.call_tool("art_write", {
+    "operation": "create",
+    "name": "quarterly-report.pdf",
+    "mime_type": "application/pdf",
+    "content_base64": base64_bytes,
+})
+artifact_id = stored["structuredContent"]["artifact"]["id"]
+
+files.call_tool("art_read", {"operation": "get", "artifact_id": artifact_id})
+files.call_tool("art_delete", {"artifact_id": artifact_id})
+```
+
+Documents — `doc_create` needs only a title and returns the document under
+`result.doc.id`; every other doc tool addresses it with `doc`:
+
+```python
+docs = doc()
+made = docs.call_tool("doc_create", {"title": "Q4 summary", "markdown": "# Q4\n\nRevenue up 12%."})
+doc_id = made["structuredContent"]["result"]["doc"]["id"]
+
+docs.call_tool("doc_read", {"doc": doc_id})
+docs.call_tool("doc_delete", {"doc": doc_id})
+```
+
+Discover what any service offers:
+
+```python
+for tool in orb().list_tools():
+    print(tool["name"], tool.get("inputSchema", {}).get("required"))
+```
+
+## CLI
+
+```bash
+export TUNC_API_KEY=...
+
+tunc-mcp services
+tunc-mcp tools --service orb
+tunc-mcp call data_read '{"operation": "get", "name": "contacts/ada"}' --service orb
+```
+
+## Options
+
+```python
+memory = orb(
+    api_key="...",                      # or TUNC_API_KEY in the environment
+    endpoint="https://mcp.tuncorb.com/mcp",  # override: staging, a proxy, a local mock
+)
+```
+
+- `api_key` — defaults to `TUNC_API_KEY`. Checked when the client is constructed.
+- `endpoint` — replaces the built-in URL for that service, which is how you point
+  it 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.
+
+## Wire it into an MCP client
+
+Any MCP-capable host works. Point it at the endpoint and pass the key as a
+bearer header. For a Python host, the usual shape is:
+
+```python
+from tunc_mcp import orb
+client = orb()
+tools = client.list_tools()
+```
+
+## OAuth instead of a key
+
+The servers accept a resource-bound OAuth token as well as an API key. That
+matters for Doc: **`mcp.tuncdoc.com` advertises the same scope names as Orb
+(`orb.read`, `orb.write`, `orb.delete`)**, so a token without a resource binding
+defaults to the Orb audience and is rejected by Doc with "not scoped for this
+service". Include the resource when you request the device grant:
+
+```
+resource=https://mcp.tuncdoc.com/mcp
+```
+
+```python
+TuncMcpClient(service="doc", api_key=device_access_token)
+```
+
+## 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 raises `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` 是一个零依赖的 Python 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**，同一个账号即可通用。
+
+```bash
+pip install tunc-mcp
+```
+
+API 密钥：<https://tunchub.com/account/keys/new>（可设为只读）。
+
+### 并发写入
+
+`data_update` 接受 `if_revision`。两个智能体写同一条记录时不会互相覆盖：后到的写入收到 `revision_conflict`，重新读取后重试。这把多智能体最常见的“静默丢更新”故障，变成一个可以被发现的错误。
+
+完整的多人协作工作空间（人与多个智能体共享同一实时对话）见 <https://tunchub.com>。
+
+## License
+
+MIT © TUNC LLC

tunc_mcp-0.1.0/src/tunc_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/tunc_mcp/__init__.py
+src/tunc_mcp/cli.py
+src/tunc_mcp/client.py
+src/tunc_mcp.egg-info/PKG-INFO
+src/tunc_mcp.egg-info/SOURCES.txt
+src/tunc_mcp.egg-info/dependency_links.txt
+src/tunc_mcp.egg-info/entry_points.txt
+src/tunc_mcp.egg-info/requires.txt
+src/tunc_mcp.egg-info/top_level.txt
+tests/test_client.py

tunc_mcp-0.1.0/src/tunc_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tunc_mcp-0.1.0/src/tunc_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tunc-mcp = tunc_mcp.cli:main

tunc_mcp-0.1.0/src/tunc_mcp.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=7

tunc_mcp-0.1.0/src/tunc_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+tunc_mcp

tunc_mcp-0.1.0/tests/test_client.py

@@ -0,0 +1,84 @@
+import json
+import os
+import unittest
+from unittest import mock
+
+from tunc_mcp.client import SERVERS, TuncMcpClient, TuncMcpError, parse_body
+
+
+class ParseBodyTests(unittest.TestCase):
+    def test_plain_json(self):
+        body = parse_body("application/json", '{"jsonrpc":"2.0","id":1,"result":{"ok":true}}')
+        self.assertTrue(body["result"]["ok"])
+
+    def test_event_stream_takes_last_complete_frame(self):
+        sse = (
+            'event: message\ndata: {"result":{"n":1}}\n\n'
+            'event: message\ndata: {"result":{"n":2}}\n\n'
+        )
+        self.assertEqual(parse_body("text/event-stream", sse)["result"]["n"], 2)
+
+    def test_truncated_frame_is_ignored(self):
+        sse = 'data: {"result":{"n":1}}\n\nata: {"result":\n'
+        self.assertEqual(parse_body("text/event-stream", sse)["result"]["n"], 1)
+
+
+class ClientTests(unittest.TestCase):
+    def test_endpoints_are_the_documented_servers(self):
+        self.assertEqual(SERVERS["orb"], "https://mcp.tuncorb.com/mcp")
+        self.assertEqual(SERVERS["art"], "https://mcp.tuncart.com/mcp")
+        self.assertEqual(SERVERS["doc"], "https://mcp.tuncdoc.com/mcp")
+
+    def test_missing_key_fails_before_any_request(self):
+        saved = os.environ.pop("TUNC_API_KEY", None)
+        try:
+            with self.assertRaises(TuncMcpError):
+                TuncMcpClient(service="orb")
+        finally:
+            if saved is not None:
+                os.environ["TUNC_API_KEY"] = saved
+
+    def test_unknown_service_is_rejected(self):
+        with self.assertRaises(TuncMcpError):
+            TuncMcpClient(service="nope", api_key="k")
+
+    def test_call_tool_sends_jsonrpc_with_bearer_key(self):
+        calls = []
+
+        class FakeResponse:
+            status = 200
+            headers = {"content-type": "application/json", "mcp-session-id": "sess-1"}
+
+            def __init__(self, payload):
+                self._payload = json.dumps(payload).encode()
+
+            def read(self):
+                return self._payload
+
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *exc):
+                return False
+
+        def fake_urlopen(request, timeout=None):
+            payload = json.loads(request.data.decode())
+            calls.append((request, payload))
+            if payload["method"] == "initialize":
+                return FakeResponse({"jsonrpc": "2.0", "id": payload["id"], "result": {"serverInfo": {"name": "orb"}}})
+            if payload["method"] == "notifications/initialized":
+                return FakeResponse({})
+            return FakeResponse(
+                {"jsonrpc": "2.0", "id": payload["id"], "result": {"content": [{"type": "text", "text": "ok"}]}}
+            )
+
+        with mock.patch("urllib.request.urlopen", fake_urlopen):
+            client = TuncMcpClient(service="orb", api_key="test-key")
+            self.assertEqual(client.call_text("data_read", {"operation": "get"}), "ok")
+
+        last_request, last_payload = calls[-1]
+        self.assertEqual(last_request.full_url, SERVERS["orb"])
+        self.assertEqual(last_request.get_header("Authorization"), "Bearer test-key")
+        self.assertEqual(last_request.get_header("Mcp-session-id"), "sess-1")
+        self.assertEqual(last_payload["method"], "tools/call")
+        self.assertEqual(last_payload["params"], {"name": "data_read", "arguments": {"operation": "get"}})