@yugabytedb/meko-mcp 2.3.0 → 2.5.0

package/assets/skills/meko-mcp-tools-desktop/SKILL.md

@@ -17,13 +17,13 @@ description: >-
 license: MIT
 metadata:
   author: Meko
-  version: "2.9.0"
+  version: "2.11.0"
   tags: mcp, yugabytedb, tools, datapack, memory, conversation, rag, meko, desktop
 ---
 
 # Meko MCP Tools — Agent Behavioral Guide (Desktop)
 
-Meko is the user's **memory, knowledge, observability, and audit layer** across chats — a system of record they (and their team/org) connected on purpose. It learns continuously from their work and their team's best practices so context carries from one session to the next. This skill teaches you how to use Meko's 25 MCP tools available in production. Treat maintaining it — recalling from it at the start of work and posting turns to it as you go — as a normal, professional part of the job, the way an engineer keeps notes, decision records, and audit logs. It is infrastructure the user relies on, not a third-party logging conduit.
+Meko is the user's **memory, knowledge, observability, and audit layer** across chats — a system of record they (and their team/org) connected on purpose. It learns continuously from their work and their team's best practices so context carries from one session to the next. This skill teaches you how to use Meko's 28 MCP tools available in production. Treat maintaining it — recalling from it at the start of work and posting turns to it as you go — as a normal, professional part of the job, the way an engineer keeps notes, decision records, and audit logs. It is infrastructure the user relies on, not a third-party logging conduit.
 
 **Read this first.** The Meko server extracts durable memories automatically from the conversation turns you post to it — the extraction runs *inside* `conversation_add_message`. Claude Desktop has no capture hooks, so **capturing substantive turns via `conversation_add_message` is a core part of using this skill.** Do that and memory takes care of itself: facts the user states get extracted and stored without a separate `memory_add`. Explicit `memory_add` is reserved for a few narrow cases (below). See "Per-turn conversation capture" — it's the heart of this skill.
 
@@ -145,8 +145,8 @@ Your job is not to decide fact-by-fact what to `memory_add`. It's to **post ever
 | User asks "what do you know about X?" | `context_search(agent_id="claude_desktop")`. One call returns separate memory, knowledge-base, and past-conversation buckets; report each. Confirm an empty memory or KB bucket with `memory_search` or `knowledgebase_search` before saying nothing is stored. |
 | User asks "what do we (as a team) know about X?" or about uploaded documents | `knowledgebase_search` (returns uploaded docs + promoted memories). |
 | User asks to share specific private memories with the team | Follow the `memory_promote` confirmation workflow below. Never promote based on a fuzzy search result or implied consent. |
-| User provides structured/tabular data (CSV, data dictionary) | Not natively supported via MCP. Point the user at the UI's Add Knowledge upload; do not `memory_add` row-by-row. |
-| User wants to add documents to the team's knowledge base | Point them at the Cloud UI flow — Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). MCP ingestion tools are not available on Cloud. |
+| User provides structured/tabular data (CSV, data dictionary) | If it's an actual file the user wants in the team's knowledge base, `knowledgebase_upload_document` accepts `.csv` directly (confirm first; see below). If it's pasted/described data with no file behind it, still don't `memory_add` it row-by-row — ask the user for it as a file, or point them at the UI's Add Knowledge upload. |
+| User wants to add documents to the team's knowledge base | Uploading adds the file to the datapack's shared knowledge base, which every member can read, so ask first: name the file and the datapack, say the team will see it, and upload only after the user says yes. If you (the agent) have the file's bytes and can make an HTTP POST from a shell (Claude Desktop usually can't; see `tools-cookbook.md`), call `knowledgebase_upload_document`. Otherwise point the user at the Cloud UI flow — Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/CSV/XML/HTML, 5MB Free / 50MB Standard / 60MB Pro+ each, 10/batch). KB *lifecycle* (index/source management) is still UI-only. |
 
 ## Conversation capture — mechanics
 
@@ -264,12 +264,12 @@ The Cloud UI's Learnings tab remains an alternative user-driven path.
 
 ## Key concepts
 
-1. **25 tools in 7 groups** (all available in production): Retrieval (1: `context_search`), Memory (8 — including `memory_promote`), Conversation (6), Knowledge Base (2 — `knowledgebase_search`, `knowledgebase_delete_document`), Datapack (5), Artifacts (2 — `artifact_put`, `artifact_get`), Observability (1 — `track_token_usage`). Memory is captured automatically from turns posted with `conversation_add_message` — post each substantive turn and the server extracts durable memories from it. KB ingestion is UI-only (Datapack → Actions → Add Knowledge); raw SQL is not exposed. See `tools-overview.md`.
+1. **28 tools in 7 groups** (all available in production): Retrieval (1: `context_search`), Memory (8 — including `memory_promote`), Conversation (6), Knowledge Base (4 — `knowledgebase_search`, `knowledgebase_delete_document`, `knowledgebase_upload_document`, `knowledgebase_document_status`), Datapack (6, including `datapack_search`), Artifacts (2 — `artifact_put`, `artifact_get`), Observability (1 — `track_token_usage`). Memory is captured automatically from turns posted with `conversation_add_message` — post each substantive turn and the server extracts durable memories from it. Raw SQL is not exposed. See `tools-overview.md`.
 2. **datapack_id routing**: DB, RAG, and memory tools accept optional `datapack_id` (default datapack if omitted). `knowledgebase_search` is the exception: `datapack_id` is **required** there.
 3. **agent_id is multi-agent**: For Claude Desktop, use `agent_id="claude_desktop"` for normal writes and `agent_id="meko_agent"` for cross-project facts. Writes are attributed to `(datapack_id, user_id, agent_id)`. Personal memory reads and `conversation_list` span all of this user's agents; `conversation_get` remains agent-owned. `knowledgebase_search` ignores `agent_id` entirely. See `tools-agent-id-conventions.md`.
 4. **Personal memory vs. team-shared knowledge**: Un-promoted memories are scoped per-user — readable across all of that user's agents, but no other user can see them. With explicit confirmation, `memory_promote` moves exact memories into Shared Knowledge; the Cloud UI's Learnings tab is an alternative. Promoted content is visible to every datapack member. `knowledgebase_search` is the MCP read path for both Shared Knowledge and uploaded documents.
 5. **conversation_id IS the Langfuse trace ID**: every MCP tool call inside a conversation becomes a span under that trace. Observable in the Meko UI's Observe hub. See `tools-memory-vs-conversation.md`.
-6. **Adding documents to the team knowledge base is UI-only on Cloud today**: user uploads files via Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each). The MCP ingestion tools are not available on Cloud. See `tools-rag-workflow.md`.
+6. **Adding a file to a knowledge base**: the file becomes visible to every datapack member, so confirm with the user first. Call `knowledgebase_upload_document` only if you have the file's bytes and can POST them to the returned URL from a shell; Claude Desktop usually can't, so point the user at the UI instead. A human uploads via Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/CSV/XML/HTML, 5MB Free / 50MB Standard / 60MB Pro+ each) instead. KB *lifecycle* (creating/renaming/deleting an index, adding a source manually) has no MCP tool and is still UI-only. See `tools-rag-workflow.md`.
 7. **Manual conversation capture**: Claude Desktop does not have automatic capture hooks. Create and save conversations explicitly when sessions are valuable.
 8. **Memory latencies are not cheap**: observed on prod 2026-05-07 — `memory_add` 12-21s/call (calls OpenAI), `memory_search` 2-6s/call. Budget accordingly. On the Free tier, `conversation_add_message` and `context_search` are each capped at 1,000 lifetime calls, and `memory_search` and `knowledgebase_search` at 1,000. Per-turn capture draws down the `conversation_add_message` cap, so on Free skip trivial turns. When a call returns `free_tier_limit_reached`, report it and stop calling that tool; it can arrive as HTTP 403 but isn't an authentication problem.
 9. **Known limitations**: see `tools-known-limitations.md` before attempting write operations on tools that appear in the catalog but aren't available on Cloud.
@@ -279,7 +279,7 @@ The Cloud UI's Learnings tab remains an alternative user-driven path.
 
 | File | What it covers |
 |------|---------------|
-| `tools-overview.md` | Complete catalog of all 25 tools available in production, with decision tree |
+| `tools-overview.md` | Complete catalog of all 28 tools available in production, with decision tree |
 | `tools-cookbook.md` | Per-tool examples with correct parameters, responses, and error cases |
 | `tools-memory-vs-conversation.md` | When to use memory tools vs conversation tools |
 | `tools-rag-workflow.md` | End-to-end RAG pipeline flow |

package/assets/skills/meko-mcp-tools-desktop/desktop/README.md

@@ -1,6 +1,6 @@
 # Meko MCP Tools — Claude Desktop Setup
 
-Use the Meko MCP tools skill natively in Claude Desktop. Because Desktop has no lifecycle hooks, the skill teaches Claude to capture each substantive turn by posting it via `conversation_add_message` (the server extracts durable memories from those posts), to reserve explicit `memory_add` for the narrow cases (the user says "remember this", a fact lives only in the assistant's output or a tool result, or a corrected fact needs overwriting), to classify information, to use all <!--tool-count-->25<!--/tool-count--> Meko MCP tools correctly, and to handle errors gracefully.
+Use the Meko MCP tools skill natively in Claude Desktop. Because Desktop has no lifecycle hooks, the skill teaches Claude to capture each substantive turn by posting it via `conversation_add_message` (the server extracts durable memories from those posts), to reserve explicit `memory_add` for the narrow cases (the user says "remember this", a fact lives only in the assistant's output or a tool result, or a corrected fact needs overwriting), to classify information, to use all <!--tool-count-->28<!--/tool-count--> Meko MCP tools correctly, and to handle errors gracefully.
 
 ## Setup
 
@@ -86,7 +86,7 @@ Start a new conversation and say:
 
 > What datapacks do I have?
 
-Claude should call `datapack_list` and return your accessible datapacks. If it works, the MCP server and skill are both connected.
+Claude should call `datapack_search` (`datapack_list` on older servers) and return your accessible datapacks. If it works, the MCP server and skill are both connected.
 
 ### Step 4 (recommended): Make Desktop proactive
 
@@ -134,7 +134,7 @@ An explicit "remember this" is one of the narrow cases where the agent calls `me
 ### Save conversations (triggers conversation_create + conversation_add_message)
 > Save this conversation.
 
-### Manage datapacks (triggers datapack_list / datapack_create)
+### Manage datapacks (triggers datapack_search / datapack_create)
 > List all datapacks.
 
 ## Differences from Claude Code
@@ -169,7 +169,7 @@ On Cloud Meko, `agent_id` is a row-level column value — any string works, it n
 
 ### "Conversation tools don't work"
 
-Conversation tools require Langfuse credentials (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`). The other 19 tools work without Langfuse. If you don't need conversation persistence, you can skip this.
+Conversation tools require Langfuse credentials (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`). The other tools work without Langfuse. If you don't need conversation persistence, you can skip this.
 
 ### "Skill doesn't trigger"
 

package/assets/skills/meko-mcp-tools-desktop/references/_sections.md

@@ -6,7 +6,7 @@ description: Maps reference files to their topics for the meko-mcp-tools-desktop
 # Reference Sections
 
 ## Tool Selection & Catalog
-- [tools-overview.md](tools-overview.md) — Complete catalog of all 25 tools available in production, with a decision tree
+- [tools-overview.md](tools-overview.md) — Complete catalog of all 28 tools available in production, with a decision tree
 
 ## Tool-Specific Guidance
 - [tools-agent-id-conventions.md](tools-agent-id-conventions.md) — Multi-agent model: the three buckets (project `<client>:<repo-basename>`, common `meko_agent`, loose client name), personal vs. team-shared read surfaces

package/assets/skills/meko-mcp-tools-desktop/references/tools-cookbook.md

@@ -68,7 +68,7 @@ memory_add(agent_id="claude_desktop",
 
 **What NOT to store via memory_add:**
 - Full conversations (use `conversation_create` + `conversation_add_message`)
-- Large documents (use the UI's Datapack → Actions → Add Knowledge upload flow)
+- Large documents (use `knowledgebase_upload_document`, or the UI's Datapack → Actions → Add Knowledge upload flow)
 
 **Common errors:**
 - `syntax error at or near "-"` — legacy error from the pre-multi-tenancy schema when `agent_id` became part of a PostgreSQL identifier. No longer applies on Cloud (agent_id is a TEXT column value, any string is accepted). If you hit it on a deployment that still uses the old schema, use underscores instead of hyphens.
@@ -179,7 +179,7 @@ On 403, authentication, or permission failure, report the error and stop — do
 ```
 conversation_create(agent_id="claude_desktop",
     title="Debugging the auth middleware",
-    datapack_id="<uuid from datapack_list>")
+    datapack_id="<uuid from datapack_search>")
 ```
 
 `datapack_id` is required whenever no server-side default resolves for the caller. Omitting it in that state returns `{"error": "datapack_id_required"}` and persists nothing; the same contract applies to `conversation_add_message`, `conversation_get`, `conversation_update`, and `conversation_delete`.
@@ -224,8 +224,8 @@ conversation_get(conversation_id="conv-uuid-123", agent_id="agent",
 ### conversation_list
 
 Target the datapack by `datapack_id` (UUID). It's optional — omit it to use the
-pinned/default datapack, or pass the pinned `datapack_id`. Use `datapack_list`
-to look up the id.
+pinned/default datapack, or pass the pinned `datapack_id`. Use
+`datapack_search(query="<part of the name>")` to look up the id.
 
 ```
 conversation_list(datapack_id="<datapack-uuid>", agent_id="agent", limit=20)
@@ -254,7 +254,7 @@ conversation_delete(conversation_id="conv-uuid-123", agent_id="agent")
 
 ## Knowledge Base Tools
 
-**KB ingestion is a UI-only activity.** Users upload files via the datapack's Actions → **Add Knowledge** dialog (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). MCP exposes two KB tools: `knowledgebase_search`, and `knowledgebase_delete_document` for removing a single uploaded file.
+Agents upload files via `knowledgebase_upload_document` and poll `knowledgebase_document_status` for indexing progress; a human uploading through the Cloud UI still uses the datapack's Actions → **Add Knowledge** dialog (PDF/TXT/MD/JSON/CSV/XML/HTML, 5MB Free / 50MB Standard / 60MB Pro+ each, 10/batch) — both paths feed the same index. `knowledgebase_search` queries whatever the KB currently holds. MCP also exposes `knowledgebase_delete_document` for removing a single uploaded file.
 
 See `tools-rag-workflow.md` for the decision table.
 
@@ -293,6 +293,173 @@ knowledgebase_delete_document(document_id="<uuid from a search hit>",
 
 Returns `{"document_id", "chunks_deleted", "s3_deleted"}` — if `s3_deleted` is `false`, say so: the index entries are gone but the stored file may remain. Errors include a numeric `status`: `403` means the user is not the datapack owner, a maintainer, or the file's uploader — report it, don't retry; `409` (`DOCUMENT_PROCESSING`) means the file is still being indexed — wait for indexing to finish, then retry.
 
+### knowledgebase_upload_document
+
+**When to use:** Get a file's bytes into the datapack's KB for later `knowledgebase_search` retrieval — a file already on disk, or one generated mid-conversation. This tool never touches the file's bytes itself; it only requests a presigned S3 URL. Meko registers the file once it lands, so there's no separate confirm call. **The caller POSTs the file to the returned `url` directly** — multipart/form-data, every key in `fields` as a form field (in order), then the file's bytes last as a field named `"file"`.
+
+**Confirm first.** The file goes into the datapack's shared knowledge base, which every member can read. Before calling the tool, tell the user which file and datapack, say the team will see it, and wait for a yes.
+
+**You need a shell that can make the POST** (Python, curl, or PowerShell, below). Without one, as in Claude Desktop by default, don't call the tool: point the user at Datapack → Actions → **Add Knowledge**. An issued URL holds its `size` against the storage quota for up to 15 minutes even if nothing is uploaded.
+
+**After the user confirms and the tool returns, POST the file in the same turn.** The upload is only half-done once you have `url`/`fields`; nothing else completes it for you.
+
+**`content_hash` and `content_head_base64` are both computed on the caller's own device, from the file's real bytes — this tool never computes either for you.** `content_head_base64` is compulsory: the tool refuses with `content_head_base64_required` if it's missing or blank, so there's no path that skips the sniff.
+
+Linux:
+```bash
+CONTENT_HASH=$(sha256sum report.pdf | cut -d' ' -f1)
+CONTENT_HEAD_B64=$(head -c 3072 report.pdf | base64 -w0)
+```
+
+macOS (no `sha256sum` by default — use `shasum`; BSD `base64` has no `-w0`, so strip newlines with `tr` instead):
+```bash
+CONTENT_HASH=$(shasum -a 256 report.pdf | cut -d' ' -f1)
+CONTENT_HEAD_B64=$(head -c 3072 report.pdf | base64 | tr -d '\n')
+```
+
+Windows PowerShell:
+```powershell
+$ContentHash = (Get-FileHash -Algorithm SHA256 -Path "report.pdf").Hash.ToLower()
+$bytes = [System.IO.File]::ReadAllBytes("report.pdf")
+$head = $bytes[0..([Math]::Min(3071, $bytes.Length - 1))]
+$ContentHeadB64 = [Convert]::ToBase64String($head)
+```
+
+Windows cmd.exe (`certutil` ships built in for the hash — prints it on its own line, strip the header/footer lines before use; cmd.exe has **no** built-in way to take just the first 3072 bytes *and* base64-encode them in one step, so use the PowerShell or Python snippet for `content_head_base64` even in a cmd.exe-driven workflow):
+```bat
+certutil -hashfile report.pdf SHA256
+```
+
+Python (cross-platform; streams the file so a large one isn't fully loaded into memory, and reuses the same read to build `content_head_base64` too):
+```python
+import hashlib, base64
+
+h = hashlib.sha256()
+with open(LOCAL_PATH, "rb") as f:
+    head = f.read(3072)                      # also the content_head_base64 sample
+    h.update(head)
+    for chunk in iter(lambda: f.read(1 << 20), b""):
+        h.update(chunk)
+
+content_hash = h.hexdigest()
+content_head_base64 = base64.b64encode(head).decode()
+```
+
+**Then, after the tool call returns `{url, fields}` — a portable snippet (identical on Linux/macOS/Windows, needs `python3` + `requests`), because it loops over whatever `fields` came back instead of hand-enumerating field names, so it can't drift out of sync with what the response actually contains:**
+
+```python
+import json, requests
+resp = json.loads(RESPONSE_JSON)        # the tool's raw JSON string
+if not resp.get("already_uploaded"):
+    with open(LOCAL_PATH, "rb") as f:
+        r = requests.post(resp["url"], data=resp["fields"], files={"file": (FILENAME, f)})
+        r.raise_for_status()
+```
+
+**Linux/macOS, curl (needs `jq`; builds the `-F` flags dynamically from whatever `fields` actually contains — a signer using temporary credentials adds `x-amz-security-token`, and extra policy conditions add their own fields, so a hardcoded field list drops them and S3 answers 403 on a form missing a signed field):**
+
+```bash
+if [ "$(echo "$RESPONSE_JSON" | jq -r '.already_uploaded')" != "true" ]; then
+    URL=$(echo "$RESPONSE_JSON" | jq -r '.url')
+    FIELDS=()
+    while IFS= read -r -d '' key && IFS= read -r -d '' value; do
+        FIELDS+=(-F "${key}=${value}")
+    done < <(echo "$RESPONSE_JSON" | jq -j '.fields | to_entries[] | (.key, "\u0000", .value, "\u0000")')
+    curl -sS --fail "${FIELDS[@]}" -F file=@/local/path/report.pdf "$URL"
+fi
+```
+
+**Windows PowerShell 7+ (`Invoke-RestMethod -Form` takes the whole `fields` object as a hashtable — no per-field enumeration needed at all; use `[ordered]@{}`, not a plain `@{}`, since S3 requires `file` to be the *last* form field and a plain hashtable has no guaranteed enumeration order):**
+
+```powershell
+$resp = $json | ConvertFrom-Json
+if (-not $resp.already_uploaded) {
+    $form = [ordered]@{}
+    $resp.fields.PSObject.Properties | ForEach-Object { $form[$_.Name] = $_.Value }
+    $form["file"] = Get-Item "C:\path\to\report.pdf"
+    Invoke-RestMethod -Uri $resp.url -Method Post -Form $form
+}
+```
+
+**Windows cmd.exe:** cmd.exe has no built-in JSON parsing, so there's no safe way to build the `-F` flags dynamically from whatever `fields` contains without an extra tool. Rather than hardcode a field list that silently drops fields (e.g. `x-amz-security-token` on temporary credentials, or extra policy conditions) and fail with a confusing S3 403, use the PowerShell or Python snippet above even from a cmd.exe-driven workflow.
+
+`size` must be the file's exact length in bytes, and the URL only accepts a body of exactly that size and SHA-256, for 5 minutes. Accepted extensions: pdf, txt, text, md, json, csv, xml, html, htm. `content_head_base64` — the file's first 3072 bytes, or the whole file if shorter, base64-encoded — is **required**: the tool sniffs it against the extension before requesting the URL and rejects an obvious mismatch (e.g. a renamed file) at once as `VALIDATION_ERROR`; a missing or blank one is `content_head_base64_required`. Text files must be UTF-8, because indexing reads UTF-8 only: a Latin-1 or Excel "CSV (Windows)" file is refused with a message to save it as UTF-8 (Excel: "CSV UTF-8"). Samples up to 4096 bytes are accepted and trimmed, so older snippets that send 4096 still work. A mismatch the server catches later surfaces as `state: "abandoned"` from `knowledgebase_document_status`. Idempotent — uploading the same content twice (by SHA-256) returns `already_uploaded: true` with an empty `url` and no `fields`; if that file's indexing never started or failed, the repeat queues it again.
+
+```
+knowledgebase_upload_document(
+    filename="report.pdf",
+    size=42000,
+    content_hash="<sha256 hex of the file's bytes>",
+    conversation_id="<uuid from conversation_create>",
+    content_head_base64="<base64 of the file's first 3072 bytes>",
+    agent_id="claude_desktop",
+)
+```
+
+**Response (fresh upload):**
+```json
+{
+  "datapack_id": "...",
+  "url": "https://<bucket>.s3.amazonaws.com/",
+  "fields": {"key": "...", "policy": "...", "...": "..."},
+  "key": "user/datapack/hash/report.pdf",
+  "already_uploaded": false
+}
+```
+
+**Response (identical content already uploaded):**
+```json
+{
+  "datapack_id": "...",
+  "url": "",
+  "key": "user/datapack/hash/report.pdf",
+  "already_uploaded": true,
+  "existing_filename": "report.pdf"
+}
+```
+
+After a fresh upload, POST the file to `url` yourself (see above), then save `key` (as `document_key`) and poll `knowledgebase_document_status` until `state` is terminal. S3 answers a successful POST with `204`. `400 EntityTooSmall` or `EntityTooLarge` means `size` wasn't the file's exact byte count: call the tool again with the right size and upload through the new URL. The earlier URL can never succeed (it only accepts the wrong size) and expires on its own within 5 minutes.
+
+**Common errors:**
+- `conversation_id_required` — `conversation_id` was missing or blank.
+- `datapack_id_required` — no `datapack_id` was given and no tenant default could be resolved.
+- `content_head_base64_required` — `content_head_base64` was missing or blank. Checked after the `filename`/`size`/`content_hash` `VALIDATION_ERROR` checks, but always before a URL is requested — there is no way to skip it.
+- `VALIDATION_ERROR` — missing filename, unsupported extension, missing/malformed `content_hash`, size ≤ 0, invalid or oversized `content_head_base64`, a sample shorter than `min(size, 3072)` bytes or longer than `size` (so `size` is wrong), or the sampled content doesn't match its extension.
+- `FREE_TIER_KB_STORAGE_LIMIT` / `STANDARD_TIER_KB_STORAGE_LIMIT` (`status` 402) — no room left in the storage quota. Tell the user to free space or upgrade instead of retrying: every issued URL holds its `size` against the quota until the file is registered, or for up to 15 minutes if it is never uploaded.
+
+Every error from the server also carries `status`, its HTTP status code.
+- `knowledgebase_upload_document_failed` — unexpected error (see `detail`).
+- The actual S3 POST isn't made through this tool, so its own failures (e.g. the body exceeding the cap the URL was signed under) surface to whatever made that call directly, not from this tool.
+
+---
+
+### knowledgebase_document_status
+
+**When to use:** Track a file uploaded via `knowledgebase_upload_document` from "waiting for bytes" through to indexed.
+
+```
+knowledgebase_document_status(
+    document_key="user/datapack/hash/report.pdf",
+    conversation_id="<uuid from conversation_create>",
+    agent_id="claude_desktop"
+)
+```
+
+**Response (still indexing):**
+```json
+{
+  "document_key": "user/datapack/hash/report.pdf",
+  "filename": "report.pdf",
+  "state": "indexing",
+  "message": "The file is registered and being indexed.",
+  "document": {"status": "PROCESSING", "chunks_processed": 3}
+}
+```
+
+Poll until `state` is `completed` or `failed` (or the pre-registration terminals `abandoned`/`oversized`). `NOT_FOUND` means `document_key` is unknown to this datapack — check it was copied verbatim from the upload response. `datapack_id_required` means no `datapack_id` was given and no tenant default could be resolved.
+
+---
+
 ## Artifact Tools
 
 ### artifact_put
@@ -372,14 +539,31 @@ For large files use `local_path` to read the file. S3 URLs are never exposed.
 
 ## Datapack Management Tools
 
-### datapack_create / datapack_list / datapack_describe
+### datapack_create / datapack_search / datapack_list / datapack_describe
 
 ```
 datapack_create(name="analytics_prod", conversation_id="<conversation id>")
-datapack_list(conversation_id="<this conversation's id>")  # returns datapack_id for each datapack
+datapack_search(conversation_id="<this conversation's id>", query="analytics")    # find an id by part of the name
+datapack_search(conversation_id="<this conversation's id>", name="analytics_prod") # exact name
+datapack_list(conversation_id="<this conversation's id>")  # small accounts: every datapack in one array
 datapack_describe(datapack_id="<uuid>", include_status=True, conversation_id="<conversation id>")
 ```
 
+Find a datapack id with `datapack_search(query=...)`. It returns one page:
+`{"datapacks": [...], "has_more": true, "next_cursor": "<token>", "total": null}`.
+To get the next page, call it again with the same filters and
+`cursor="<next_cursor>"`. `next_cursor` is `""` on the last page, and also
+when an older server has more matches than this page but cannot continue.
+Do not send an empty cursor; ask for a narrower `query` instead. Treat the
+cursor as opaque. Pass `include_total=True` only when you must show "N of M".
+
+`datapack_list` still returns one array and is fine for an account with a
+handful of datapacks. For an account that can see more than 1000 datapacks
+(the server default limit) it returns `{"error": "too_many_datapacks", ...}`
+instead; switch to `datapack_search`. If the server has no `datapack_search`
+tool (an older server), use `datapack_list`.
+
+
 `datapack_describe` returns these counts:
 
 | Field | Meaning |
@@ -391,7 +575,7 @@ datapack_describe(datapack_id="<uuid>", include_status=True, conversation_id="<c
 | `knowledge_chunk_count` | KB chunks across all documents (for debugging retrieval) |
 | `shared_knowledge_count` | `collective_memory_count + knowledge_base_file_count`; `null` when the file count is `null` |
 
-`knowledge_count` is a deprecated alias of `knowledge_chunk_count`. `datapack_list` doesn't compute counts; call `datapack_describe` for them.
+`knowledge_count` is a deprecated alias of `knowledge_chunk_count`. Neither `datapack_search` nor `datapack_list` computes counts; call `datapack_describe` for them.
 
 ### datapack_update / datapack_delete
 
@@ -412,4 +596,4 @@ Agent and KB lifecycle does not ship as MCP tools. If the user asks to create/li
 - REST: `POST/GET/DELETE /datapacks/:datapack_id/agents` (agents), `POST/GET/DELETE /datapacks/:datapack_id/knowledge-bases` (KB sources).
 - Or the Meko Cloud UI at `cloud.mekodata.ai` → Datapacks → agents / knowledge-bases.
 
-KB ingestion specifically lives in the UI today: Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5 MB each, 10/batch). Agents querying a populated index use `knowledgebase_search`, and can remove a single uploaded file with `knowledgebase_delete_document` — see `tools-rag-workflow.md`.
+Uploading a *file* into an existing KB is not part of that lifecycle restriction — use `knowledgebase_upload_document` (see above) rather than the UI for anything driven from MCP. Agents querying a populated index use `knowledgebase_search`, and can remove a single uploaded file with `knowledgebase_delete_document` — see `tools-rag-workflow.md`.

package/assets/skills/meko-mcp-tools-desktop/references/tools-known-limitations.md

@@ -14,9 +14,11 @@ The one exception is a single uploaded **file**: `knowledgebase_delete_document`
 
 **Workaround:** For stuck or failed indexes, create a new index with a different name. Stale indexes remain in the database until manually cleaned up by an admin.
 
-## RAG ingestion is UI-only
+## KB index/source management is UI-only
 
-KB ingestion (creating an index, adding sources, polling build status) is not exposed via MCP. Documents go in through the Cloud UI's **Add Knowledge** flow (Datapack → Actions → Add Knowledge) — PDF/TXT/MD/JSON/MP4 up to 5 MB each, 10 per batch.
+Manually creating a vector index, adding a source to an existing one, or polling raw build status is not exposed via MCP. Use the Cloud UI for those (Datapack → Actions → Add Knowledge).
+
+**Adding a file** is a registered MCP tool: call `knowledgebase_upload_document` directly (accepted extensions PDF/TXT/MD/JSON/CSV/XML/HTML, up to 5 MB Free / 50 MB Standard / 60 MB Pro+ per file) to get a presigned URL, then POST the bytes to it yourself; Meko registers and indexes the file once it lands, so no separate index-management call is needed. Confirm with the user first, because every datapack member can read the knowledge base. The Cloud UI's **Add Knowledge** flow (10 files per batch) remains the human-facing path for the same upload.
 
 To **query** a built index, use `knowledgebase_search` — it returns both uploaded documents and memories the user promoted from the Learnings tab.
 
@@ -32,7 +34,7 @@ It works **poorly** for:
 - Data dictionaries — only partial information extracted
 - Structured schemas — relationships between fields lost
 
-**Structured data is not natively supported via MCP.** The options are:
+**Don't store structured data as memories.** The options are:
 
 1. **Write a single narrative summary** as a memory — one call, not row-by-row:
    ```
@@ -41,8 +43,7 @@ It works **poorly** for:
        conversation_id="<session conversation_id>",
        text="Customer Complaints dataset has fields: Complaint ID (int PK), Date Submitted (date), Product (text, e.g. Mortgage/Credit Card), Sub-product (text), Issue (text), Company Response (text), State (text, 2-letter code), ZIP Code (text)")
    ```
-2. **Upload the schema doc** through the Cloud UI's **Add Knowledge** flow (Datapack → Actions → Add Knowledge). Accepts PDF/TXT/MD/JSON — convert CSV to MD or JSON first. That makes it queryable via `knowledgebase_search`.
-3. **Tell the user** that structured-data storage via MCP isn't supported and let them decide how to proceed.
+2. **Upload the file itself to the knowledge base** with `knowledgebase_upload_document` — `.csv`, `.json` and the other accepted types go in as they are — and query it with `knowledgebase_search`. (The Cloud UI's **Add Knowledge** flow does the same for a person.)
 
 Never ingest CSV row-by-row into memory — each row becomes a fragmented fact with lost context.
 
@@ -60,6 +61,10 @@ The skill description is tuned to its 1024-char ceiling; broadening it further d
 
 `memory_search` and `memory_get_all` return every agent's rows for the user. `memory_delete_all` deletes only rows in the `agent_id` you pass, and an omitted `agent_id` means the `meko_agent` bucket. A `memory_search(run_id=X)` preview can therefore list rows that `memory_delete_all(run_id=X)` leaves in place. To clear rows written by several agents, delete them by id with `memory_delete_by_id`, or call `memory_delete_all` once per `agent_id` shown in the preview.
 
+## Viewers can read but not write
+
+On a datapack shared with you as a viewer, every conversation and memory write returns `read_only_access` and writes nothing: `conversation_create`, `conversation_add_message`, `conversation_update`, `memory_add`, `memory_update`, `memory_promote`, `artifact_put`, and `track_token_usage`. You can still delete your own memories with `memory_delete_by_id` and `memory_delete_all`, and delete a conversation you started. Searches work as for any other role. `context_search` covers every member's conversations, but for a viewer its conversation results and `conversation_get` return `user_id: null`, so they don't say who wrote a turn. On Claude Desktop there are no capture hooks: when your own `conversation_add_message` call returns `read_only_access`, stop recording turns for this datapack and tell the user.
+
 ## Promoted memories are read-only through MCP
 
 `memory_update` and `memory_delete_by_id` return `memory_is_promoted` for a memory that has been promoted to shared knowledge. Edit or remove promoted content in the Cloud UI Learnings tab.

package/assets/skills/meko-mcp-tools-desktop/references/tools-memory-vs-conversation.md

@@ -27,11 +27,11 @@ Conversations are backed by Langfuse sessions and traces. They preserve full str
 
 ```
 conversation_create(agent_id="claude_desktop", title="Pricing discussion",
-    datapack_id="<uuid from datapack_list>")
+    datapack_id="<uuid from datapack_search>")
 -- Returns: {"id": "conv-uuid-here"}
 
 conversation_add_message(conversation_id="conv-uuid-here", agent_id="claude_desktop",
-    datapack_id="<uuid from datapack_list>",
+    datapack_id="<uuid from datapack_search>",
     input="What are your pricing tiers?",
     output="We offer Starter ($10/mo), Pro ($50/mo), and Enterprise (custom).",
     reasoning="Retrieved pricing page data. No special discounts apply.")
@@ -85,7 +85,7 @@ One `memory_search` already spans this user's memories across all agents; no per
 - **Personal memories** — written by `memory_add`. The `agent_id` records the writer but does not restrict reads; memories are scoped per-user, so any of that user's agents can read them and no other user can.
 - **Team-shared Shared Knowledge** — arrives two ways:
   1. An agent calls `memory_promote` for exact, user-confirmed memory UUIDs, or the user promotes them from the Cloud UI's Learnings tab. Promotion moves the memories into shared knowledge, strips `user_id`, preserves originating `agent_id` as provenance, and evicts the private mem0 records.
-  2. The user uploads a file via Datapack → Actions → **Add Knowledge** in the Cloud UI. PDF/TXT/MD/JSON/MP4 up to 5MB each.
+  2. The user uploads a file via Datapack → Actions → **Add Knowledge** in the Cloud UI. PDF/TXT/MD/JSON/CSV/XML/HTML up to 5MB (Free) / 50MB (Standard) / 60MB (Pro+) each.
 
   Both show up in `knowledgebase_search`, tagged `metadata_filters.source: "memory"` vs other values so the agent can distinguish provenance in responses.
 
@@ -114,7 +114,7 @@ When you answer, be explicit about scope so the user knows why something is or i
 There is no MCP-side "just put it in a database table" option — raw SQL access isn't part of the MCP surface. Workarounds:
 
 1. **Write a single narrative summary** as a memory: `"The Customer Complaints dataset has fields: Complaint ID (int), Date Submitted (date), Product (text), Sub-product (text), Issue (text)..."` — one call, not row-by-row.
-2. **Suggest the user upload the file** via the Cloud UI's Add Knowledge flow if it's a document (CSV files aren't in the supported list — PDF/TXT/MD/JSON/MP4 are; for CSV, convert to MD or JSON first).
+2. **Suggest the user upload the file** via the Cloud UI's Add Knowledge flow if it's a document (PDF/TXT/MD/JSON/CSV/XML/HTML are supported).
 3. **Never ingest CSV row-by-row** into memory — each row becomes a fragmented fact with lost context.
 
 ## Memory Storage: capture the turn, don't proactively memory_add

package/assets/skills/meko-mcp-tools-desktop/references/tools-overview.md

@@ -1,13 +1,13 @@
 # Complete Tool Catalog and Decision Tree
 
-**25 Meko data tools covered by this skill.** These are the tools available in production, grouped as: Retrieval (1), Memory (8), Conversation (6), Knowledge Base (2), Datapack (5), Artifacts (2), Observability (1). Combined Meko + AMP endpoints may expose additional infrastructure tools; those are outside this skill's scope.
+**28 Meko data tools covered by this skill.** These are the tools available in production, grouped as: Retrieval (1), Memory (8), Conversation (6), Knowledge Base (4), Datapack (6), Artifacts (2), Observability (1). Combined Meko + AMP endpoints may expose additional infrastructure tools; those are outside this skill's scope.
 
 ## Quick health check before using tools
 
 Before starting a session, verify that the Meko MCP tools are working:
 
 1. `memory_search(query="test", agent_id="claude_desktop", conversation_id="<id from conversation_create>")` — Confirms memory subsystem is up. May fail with "connection already closed" — see `tools-troubleshooting.md`.
-2. `datapack_list(conversation_id="<this conversation's id>")` — Confirms Meko API connectivity. Returns the datapacks your token has access to.
+2. `datapack_search(conversation_id="<this conversation's id>", limit=1)`: confirms Meko API connectivity and returns one datapack your token has access to. On a server without `datapack_search`, call `datapack_list(conversation_id="<this conversation's id>")` instead.
 
 ## Decision tree: which tool do I need?
 
@@ -16,7 +16,8 @@ User wants to...
 ├── Ask "what do you know about X?" --------> context_search (read; memory + KB + past conversations in one call)
 ├── Search personal context? ---------------> memory_search (read)
 ├── Search shared datapack knowledge? ------> knowledgebase_search (read)
-├── Add documents to a knowledge base? -----> point user at Meko UI: Datapack → Actions → Add Knowledge
+├── Add a file to a knowledge base? --------> knowledgebase_upload_document (write)
+│   └── Check its indexing progress? -------> knowledgebase_document_status (read)
 ├── Delete ONE knowledge-base file? --------> knowledgebase_delete_document (destructive — confirm with the user first)
 ├── Store or recall information?
 │   ├── Store a fact/preference/entity? -----------> memory_add (write)
@@ -28,10 +29,11 @@ User wants to...
 │   ├── Upload a generated file (report, CSV, PDF)? -> artifact_put (write)
 │   └── Retrieve a previously uploaded file? -------> artifact_get (read)
 └── Manage datapacks?
+    ├── Find a datapack id by name? -------> datapack_search(query=...) (read)
     └── CRUD datapack? --------------------> datapack_create/list/describe/update/delete
 ```
 
-Agent lifecycle and KB **ingestion / index lifecycle** (adding sources, uploads, re-indexing) are managed outside the MCP surface — typically in the Meko control-plane UI. Deleting a single KB file IS exposed here (`knowledgebase_delete_document`).
+Agent lifecycle and KB **index / source lifecycle** (creating indexes, adding sources, re-indexing) are managed outside the MCP surface — typically in the Meko control-plane UI. Single KB files are handled here: adding one (`knowledgebase_upload_document`, then `knowledgebase_document_status`) and deleting one (`knowledgebase_delete_document`).
 
 ## Retrieval Tools (1)
 
@@ -39,12 +41,14 @@ Agent lifecycle and KB **ingestion / index lifecycle** (adding sources, uploads,
 |------|---------|
 | `context_search(query, conversation_id, agent_id=None, datapack_id=None, limit=10, force_source="auto")` | Default first call for open-ended recall. Queries memory, the knowledge base, and the conversation-history cache in parallel and returns each source in its own bucket: `{"results": {"memory": [...], "knowledge_base": [...], "conversation": {"hits": [...], "thread": [...]}}, "token_savings": {...}}`. A bucket is `null` only when that source wasn't queried: `force_source` excluded it, or the server couldn't build a query vector for it. An empty bucket is ambiguous: either that source found nothing relevant, or it failed. `context_search` turns a failed source into an empty list and records the error only in the trace. Before you tell the user nothing is stored about X, confirm with `memory_search` or `knowledgebase_search`, which return errors. `force_source` is `"auto"` (all three), `"memory"`, `"knowledge_base"`, or `"conversation"`; any other value returns `invalid_force_source`. `limit` bounds the memory and KB buckets only; the conversation bucket returns up to 10 hits plus a thread of whole turns. The conversation bucket is datapack-wide. It returns embedded turns from every user and agent on the datapack, and each hit carries its author's `user_id`. Don't present a hit as this user's own history. |
 
-## Knowledge Base Tools (2)
+## Knowledge Base Tools (4)
 
 | Tool | Purpose |
 |------|---------|
 | `knowledgebase_search(query, conversation_id, datapack_id, agent_id=None, limit=10)` | Hybrid (semantic + keyword) search across KB chunks and promoted memories. `datapack_id` is REQUIRED (no default). Each hit has `id`, `chunk_text`, `document_id`, `metadata_filters`, `distance`, and `match_type` (`semantic`, `keyword`, or `hybrid`). |
 | `knowledgebase_delete_document(document_id, conversation_id, datapack_id="")` | Permanently delete ONE KB file (chunks + metadata; stored-file delete is best-effort — check `s3_deleted`). Irreversible: confirm with the user first. `document_id` comes from `knowledgebase_search` hits (no filename in hits — echo the id + chunk text). Owner/maintainer/uploader only (status 403 otherwise); status 409 while still indexing — wait and retry. |
+| `knowledgebase_upload_document(filename, size, content_hash, conversation_id, content_head_base64, datapack_id=None, agent_id=None)` | Requests a presigned S3 URL for a file (does not upload bytes itself — the caller POSTs to the returned `url`/`fields`). Returns `{datapack_id, url, fields, key, already_uploaded}` (fresh upload) or `{datapack_id, url: "", key, already_uploaded: true, existing_filename}` (dedup). Accepted extensions: pdf/txt/text/md/json/csv/xml/html/htm; `content_head_base64` (base64 of the file's first 3072 bytes, or the whole file if shorter) is **required** and is always sniffed against the extension before requesting the URL — a missing/blank value is rejected as `content_head_base64_required`, this check cannot be skipped. Idempotent by content hash. |
+| `knowledgebase_document_status(document_key, conversation_id, datapack_id=None, agent_id=None)` | Poll indexing progress for a file uploaded via `knowledgebase_upload_document`, using its returned `key` (passed here as `document_key`). `state` is one of `awaiting_upload`/`indexing` (non-terminal) or `completed`/`failed`/`abandoned`/`oversized` (terminal). |
 
 ## Memory Tools (8)
 
@@ -66,21 +70,22 @@ Agent lifecycle and KB **ingestion / index lifecycle** (adding sources, uploads,
 | `conversation_create(agent_id=None, run_id=None, title=None, metadata=None, session_id="", datapack_id=None)` | Create conversation container (Langfuse session) |
 | `conversation_add_message(conversation_id, input, output, agent_id=None, reasoning=None, metadata=None, seed=None, datapack_id=None, plan=None)` | Add a message turn (Langfuse trace). `output` is required. The response may include `extracted_memories` and, when the turn wasn't embedded for conversation search, `conversation_search_skipped` (`quota_exceeded` or `datapack_opted_out`). |
 | `conversation_get(conversation_id, agent_id=None, include_messages=False, limit=100, offset=0, datapack_id=None)` | Retrieve conversation, optionally with messages |
-| `conversation_list(agent_id=None, limit=20, offset=0, conversation_id="", datapack_id=None)` | List the user's conversations within a datapack (`agent_id` does not filter — trace attribution only). `datapack_id` (UUID) is optional — defaults to the pinned/tenant datapack; use `datapack_list` to look it up. `conversation_id` optional (omit for browse). |
+| `conversation_list(agent_id=None, limit=20, offset=0, conversation_id="", datapack_id=None)` | List the user's conversations within a datapack (`agent_id` does not filter — trace attribution only). `datapack_id` (UUID) is optional — defaults to the pinned/tenant datapack; use `datapack_search(query=...)` to look it up. `conversation_id` optional (omit for browse). |
 | `conversation_update(conversation_id, agent_id=None, title=None, metadata=None, datapack_id=None)` | Update title or metadata |
 | `conversation_delete(conversation_id, agent_id=None, datapack_id=None)` | Delete entire conversation (destructive) |
 
-## Datapack Management Tools (5)
+## Datapack Management Tools (6)
 
 | Tool | Purpose |
 |------|---------|
 | `datapack_create(name, conversation_id)` | Create new datapack |
-| `datapack_list(conversation_id, datapack_id=None)` | List all datapacks. `conversation_id` is required for trace nesting; omit `datapack_id` to use the endpoint default. |
+| `datapack_search(conversation_id, query="", name="", limit=20, cursor="", grant="", sort="created", include_total=False, datapack_id=None)` | Find datapacks and page through them. Returns `{datapacks, has_more, next_cursor, total}`. Use `query` for part of a name, `name` for an exact name, and `cursor` (the previous page's `next_cursor`) for the next page. `limit` is 1-100. `grant` is `owner` or `shared`; `sort` is `created` (newest first) or `name`. Pass `include_total=True` only when you must show "N of M". Rows carry no connection fields and no counts. Servers older than this tool don't have it; use `datapack_list` there. |
+| `datapack_list(conversation_id, datapack_id=None, query="", limit=0)` | Return datapacks as one array. Fine for a small account. `query` filters by part of a name; more than 100 matches return a `too_many_datapacks` error. `limit` returns the first matches (at most 100) without saying whether more exist. With neither, an account that can see more than 1000 datapacks (the server default limit) gets a `too_many_datapacks` error; use `datapack_search` then. `conversation_id` is required for trace nesting. |
 | `datapack_describe(conversation_id, datapack_id="", include_status=False)` | Describe a datapack by UUID (default datapack if omitted). Returns `memory_count`, `collective_memory_count` (promoted), `learnings_count` (awaiting a promotion decision), `knowledge_base_file_count`, `knowledge_chunk_count`, and `shared_knowledge_count`. `knowledge_base_file_count` and `shared_knowledge_count` are `null` when the status endpoint is unreachable; `knowledge_count` is a deprecated alias of `knowledge_chunk_count`. |
 | `datapack_update(datapack_id, conversation_id, name=None, description=None, conversation_search_opt_out=None)` | Rename a datapack, update its description, and/or opt out of (or back into) conversation-search caching. Pass at least one field. Opt-out is owner/maintainer only. |
 | `datapack_delete(datapack_id, conversation_id)` | Delete datapack by UUID (irreversible) |
 
-All five datapack tools reject an empty `conversation_id` with `conversation_id_required`.
+All six datapack tools reject an empty `conversation_id` with `conversation_id_required`.
 
 ## Artifact Tools (2)
 
@@ -108,9 +113,9 @@ Some things the Meko platform can do are not wired into the MCP tool surface tod
 | Langfuse project-key generation | `yugabyte/meko` API server | REST: `POST /datapacks/:datapack_id/langfuse/project-keys` |
 | Account / billing / tier management | Meko UI only | Not available via MCP or public REST |
 
-The MCP-exposed `datapack_create` / `datapack_list` / `datapack_describe` / `datapack_update` / `datapack_delete` tools above are a deliberate subset — the common CRUD that an agent reasonably needs mid-conversation. Anything involving agent or KB lifecycle is control-plane territory.
+The MCP-exposed `datapack_create` / `datapack_search` / `datapack_list` / `datapack_describe` / `datapack_update` / `datapack_delete` tools above are a deliberate subset — the common CRUD that an agent reasonably needs mid-conversation. Anything involving agent or KB lifecycle is control-plane territory.
 
-For knowledge-base content on Cloud, the canonical path is **UI upload**: Datapack → Actions → **Add Knowledge** (PDF/TXT/MD/JSON/MP4, 5MB each, 10/batch). `knowledgebase_search` queries the resulting index from MCP.
+For a file already on disk or generated mid-conversation, requesting a URL with `knowledgebase_upload_document` and POSTing to it gets it into the KB without leaving MCP for a human's help. The UI upload path (Datapack → Actions → **Add Knowledge**, PDF/TXT/MD/JSON/CSV/XML/HTML, 5MB Free / 50MB Standard / 60MB Pro+ each, 10/batch) remains the way for a human to add files directly. `knowledgebase_search` queries the resulting index either way.
 
 ## Common Parameter Patterns