@yugabytedb/meko-mcp 2.3.0 → 2.5.1

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

@@ -1,16 +1,19 @@
 # Knowledge Base / RAG workflow
 
-MCP exposes two KB tools: `knowledgebase_search` (retrieval) and
-`knowledgebase_delete_document` (remove ONE uploaded file). Index
-creation and ingestion happen out of band — through the **Meko UI**
-(`cloud.mekodata.ai`).
+MCP exposes four KB tools: `knowledgebase_search` (retrieval),
+`knowledgebase_upload_document` and `knowledgebase_document_status` (add a
+file and track its indexing), and `knowledgebase_delete_document` (remove ONE
+uploaded file). Creating, listing or renaming a knowledge base itself still
+happens out of band — through the **Meko UI** (`cloud.mekodata.ai`).
 
 ## Decision table
 
 | Situation | Use this | Why |
 |---|---|---|
 | Search an existing KB | `knowledgebase_search` | Retrieval over the indexed chunks |
-| Add documents to a KB | **Meko UI** — Datapack → Actions → **Add Knowledge** | File-upload dialog (PDF/TXT/MD/JSON/MP4, 5 MB each, 10/batch). No MCP equivalent |
+| Add a file to a KB | `knowledgebase_upload_document` + one direct S3 POST | Requests a presigned URL, then you POST the file to it; no need to leave MCP |
+| Track a file's indexing progress | `knowledgebase_document_status` | Poll with the `key` from the upload response, passed here as `document_key`, until `state` is terminal |
+| Add documents to a KB from the Cloud UI instead | **Meko UI** — Datapack → Actions → **Add Knowledge** | File-upload dialog (PDF/TXT/MD/JSON/CSV/XML/HTML, 5 MB Free / 50 MB Standard / 60 MB Pro+ each, 10/batch). Same index either way — this is the human-facing path, not required when an agent can upload directly |
 | Delete ONE uploaded file | `knowledgebase_delete_document` | Destructive; `document_id` from search hits; confirm with the user first |
 | Anything else (list / rename / re-index / source lifecycle) | **UI** | No MCP tools for the rest of KB lifecycle |
 
@@ -58,6 +61,59 @@ Lower `distance` is closer. Promoted memories appear as hits whose `metadata_fil
 Empty or nonexistent KB: `{"results": [], "count": 0}` (no error,
 just an empty array).
 
+## knowledgebase_upload_document — putting a file in
+
+This tool never touches the file's bytes itself — it only requests a
+presigned S3 URL. **You POST the file to that URL yourself**, as a
+second step:
+
+```
+knowledgebase_upload_document(
+    filename="report.pdf",
+    size=42000,
+    content_hash="<sha256 hex of the file's bytes>",
+    conversation_id="<uuid from conversation_create>",
+    agent_id="claude_desktop",
+    content_head_base64="<base64 of the file's first ~4KB>")
+```
+
+Build the POST from every key in the response's `fields`, not a hand-picked list:
+a missing signed field such as `x-amz-security-token` makes S3 answer 403. Use
+the Python, curl, or PowerShell snippet under `knowledgebase_upload_document`
+in `tools-cookbook.md`. Confirm with the user first: the file becomes visible to
+every datapack member.
+
+Required: `filename`, `size` (the exact byte count — the URL accepts no
+other length), `content_hash`, `conversation_id`, `content_head_base64`. `content_hash` is the SHA-256 hex digest of the
+file's bytes, computed by you (e.g. `sha256sum`) — it becomes part of
+the S3 key, so it also drives the dedup check. A response with
+`already_uploaded: true` means identical content already exists; skip
+the S3 POST entirely, there is nothing left to upload. Otherwise POST
+as above: every key in `fields` as a form field (in order), then the
+bytes last as a field named `"file"`. Meko registers the object once
+it lands, so no separate confirm call is needed after the POST. Accepted extensions:
+pdf, txt, text, md, json, csv, xml, html, htm; `content_head_base64` is
+always sniffed against the extension before requesting the URL,
+rejecting an obvious mismatch immediately instead of waiting for the
+watcher — a missing/blank value is rejected as
+`content_head_base64_required`, this sniff cannot be skipped.
+Ingestion is asynchronous — save the response's
+`key` (as `document_key`) and poll `knowledgebase_document_status`.
+
+## knowledgebase_document_status — tracking it
+
+```
+knowledgebase_document_status(
+    document_key="<the upload response's `key`>",
+    conversation_id="<uuid from conversation_create>",
+    agent_id="claude_desktop")
+```
+
+`state` covers the whole lifecycle: `awaiting_upload` and `indexing`
+are non-terminal (poll again); `completed`, `failed`, `abandoned`, and
+`oversized` are terminal. `NOT_FOUND` means the `document_key` doesn't
+belong to this datapack.
+
 ## UI ingestion — what the user sees
 
 From `cloud.mekodata.ai`:
@@ -65,11 +121,15 @@ From `cloud.mekodata.ai`:
 1. Open a datapack (`/datapacks/<name>`).
 2. Click **Actions** → **Add Knowledge**.
 3. Drag-and-drop or browse for files. Supported: PDF, TXT, MD, JSON,
-   MP4. Per-file limit 5 MB. Up to 10 files per batch.
+   CSV, XML, HTML. Per-file limit 5 MB (Free) / 50 MB (Standard) / 60 MB (Pro+). Up to 10 files per batch.
 4. The UI handles upload, storage, and index build. The user does not
    pick a bucket or provide credentials.
 5. Search results from `knowledgebase_search` become available once
    indexing completes.
 
-If a user asks you "how do I add a document to my knowledge base?",
-point them at this flow.
+If a *human* asks you "how do I add a document to my knowledge base?",
+point them at this flow. If *you* (the agent) have the file's bytes —
+already on disk, or generated mid-conversation — and can send them in an
+HTTPS POST to an external URL yourself (a local shell, or a code tool with
+internet access), call `knowledgebase_upload_document` directly instead
+of describing the UI flow to yourself.

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

@@ -53,9 +53,11 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 | Error | Meaning | What to do |
 |---|---|---|
 | `datapack_access_denied` | The `datapack_id` isn't a UUID, or it isn't owned by or shared with your account. The access check also fails closed on a transient server database error. | Retry once. If it repeats, stop; don't switch to another datapack. If the id came from a pin, ask the user to re-pin with the select-datapack skill. |
-| `datapack_id_required` | The call couldn't resolve a datapack. Conversation reads and writes (including `conversation_list`), `datapack_describe`, and `knowledgebase_delete_document` return it. | Pass the pinned `datapack_id`. Don't drop the parameter to make the call pass. |
+| `datapack_id_required` | The call couldn't resolve a datapack. Conversation reads and writes (including `conversation_list`), `datapack_describe`, `knowledgebase_upload_document`, `knowledgebase_document_status`, and `knowledgebase_delete_document` return it. | Pass the pinned `datapack_id`. Don't drop the parameter to make the call pass. |
 | `not_found` from `memory_get_by_id`, `memory_update`, or `memory_delete_by_id` | The memory doesn't exist **or** belongs to another account. The server returns the same error for both on purpose. | Check the id came from a search in this datapack. |
 | `memory_is_promoted` | The memory was promoted to shared knowledge and is read-only through MCP. | Point the user at the Cloud UI Learnings tab. |
+| `read_only_access` | You're a viewer on this datapack. Viewers can't write conversations or memories, call `memory_promote`, `artifact_put`, or `track_token_usage`, or delete a conversation someone else started. | Don't retry, and don't switch datapacks to get around it. Tell the user; an owner or maintainer can change their role. |
+| `role_lookup_failed` | The server couldn't read your role for this datapack, so it refused the write. | Retry. |
 | `invalid_run_id` | `memory_delete_all` got a `run_id` that isn't a conversation id. | Pass the conversation UUID, or omit `run_id`. |
 | `embedder_error` from `knowledgebase_search` | The server couldn't resolve the embedding setup for this datapack's index. | Report it; retrying won't help. |
 | `invalid_force_source` from `context_search` | `force_source` isn't `auto`, `memory`, `knowledge_base`, or `conversation`. | Omit `force_source`. |

package/assets/skills/meko-select-datapack-desktop/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 license: MIT
 metadata:
   author: Meko
-  version: "1.2.2"
+  version: "1.3.1"
   tags: meko, datapack, selection, project, claude-desktop, desktop
 ---
 
@@ -63,7 +63,7 @@ This is once per turn, not once per call. Cache within the turn.
 Use a **temporary** conversation for browsing only. Call
 `conversation_create(agent_id="claude_desktop", title="Claude
 Desktop datapack selection")` and use its returned ID for the read-only
-`datapack_list` below and for the pin `memory_add`/`memory_update` in step 4.
+datapack calls below and for the pin `memory_add`/`memory_update` in step 4.
 
 **Do not reuse this conversation for later capture.** It lives in whatever
 datapack was active when it was created (typically the default), and a
@@ -71,12 +71,28 @@ conversation cannot move between datapacks. Once a datapack is pinned, capture
 must flow through a *new* conversation created in the selected datapack — see
 step 5.
 
+Check your tool list. If it has `datapack_search`, use it as below. If it
+doesn't (an older Meko server), use the fallback section at the end of step 3.
+
 ```
-datapack_list(conversation_id="<this conversation's id>")
+datapack_search(conversation_id="<this conversation's id>", limit=10, include_total=true)
+```
+
+The server sorts, filters and pages, so this works the same for 3 datapacks or
+1,000,000. The response is one page:
+
+```
+{"datapacks": [...], "has_more": true, "next_cursor": "<opaque token>", "total": 14}
 ```
 
-The response is an array; the fields you'll use are `datapack_id`,
-`datapack_name`, `created_at`, `account_id`, and `grant`.
+- `datapacks`: up to `limit` rows, newest first (`created_at DESC`). The
+  fields you'll use are `datapack_id`, `datapack_name`, `created_at`, and
+  `grant`.
+- `has_more`: `true` when another page exists.
+- `next_cursor`: pass it as `cursor` to get the next page. It is `""` on the
+  last page. Treat it as opaque: never build or edit one.
+- `total`: how many datapacks match, present because you passed
+  `include_total=true`.
 
 `grant` is the caller's actual authorization on the datapack — one of
 `"owner"`, `"maintainer"`, `"contributor"`, `"viewer"`. Display it verbatim in
@@ -85,13 +101,22 @@ the Role column. Do not hardcode "Owner", do not invent or normalize the value
 response is the source of truth — see `references/role-display-future.md` for
 the taxonomy.
 
-If the response has zero entries, tell the user: *"You don't have any datapacks yet. Run `datapack_create(name='<name>', conversation_id='<conversation id>')` to make one, or visit the Meko Cloud console."* Stop here.
+If `total` is 0, tell the user: *"You don't have any datapacks yet. Run `datapack_create(name='<name>', conversation_id='<conversation id>')` to make one, or visit the Meko Cloud console."* Stop here.
+
+If `total` is exactly **1**, **auto-select it**. Print: *"Only one datapack: `<name>`. Auto-selecting. Run `meko-select-datapack-desktop` again with `clear` to unset."* Skip the table; jump to step 4 (persist) and step 5 (confirm).
+
+If `total` is missing or `null`, decide from the page instead: no rows and
+`has_more` false means zero datapacks; one row and `has_more` false means
+exactly one. Drop `of <total>` from the header in step 2.
 
-If the response has exactly **one** entry, **auto-select it**. Print: *"Only one datapack: `<name>`. Auto-selecting. Run `meko-select-datapack-desktop` again with `clear` to unset."* Skip the table; jump to step 4 (persist) and step 5 (confirm).
+**Keep the paging state in the conversation.** Remember the current filter
+(none yet), the `total`, the page number, the `next_cursor`, and a list of the
+cursors you used for each page so far (page 1 used no cursor). `next` and
+`prev` in step 3 need them.
 
 ### 2. Render the table
 
-For 2+ datapacks, render a numbered table. **Page size 10.** Default sort: `created_at DESC` (newest first).
+For 2+ datapacks, render a numbered table of the current page. **Page size 10.** Row order is the server's (`created_at DESC`, newest first). Number rows by position in the whole list: page 1 shows 1-10, page 2 shows 11-20. The count line is `Your datapacks (showing <first>-<last> of <total>):`, for example:
 
 ```
 Your datapacks (showing 1-10 of 14):
@@ -112,17 +137,71 @@ The **Role** column shows each datapack's `grant` value verbatim (`owner`,
 datapacks legitimately carry other grants, and misreporting them (e.g. showing
 a `maintainer` grant as "Owner") misleads the user about their own access.
 
-Mark the currently-pinned row with `←  (pinned)` based on the `memory_search` result (if any).
+Mark the currently-pinned row with `←  (pinned)` based on the `memory_search` result (if any). If the pinned datapack is not on the current page, name it in one line above the table.
+
+In the legend, the number range is the rows on the current page (`11-20` on
+page 2). Offer `next` only when `has_more` is true and `next_cursor` is
+non-empty. An empty `next_cursor` with `has_more` still true means this
+server cannot page further: tell the user to narrow with a substring, and
+do not send an empty cursor. Offer `prev` only after page 1.
+
+For a search (step 3), the count line is
+`Datapacks matching "<text>" (showing <first>-<last> of <total>):`, numbered
+from 1.
 
 ### 3. Parse the user's reply
 
-- **Integer in range** → that row is the choice.
-- **Substring** → re-render filtered. If it narrows to one row, that's the choice.
-- **`next` / `prev`** → re-render next/previous page.
+- **Integer shown on the current page** → that row is the choice.
+- **Substring** → search on the server; do not filter the rows you already have:
+  ```
+  datapack_search(conversation_id="<this conversation's id>", query="<text>", limit=10, include_total=true)
+  ```
+  This starts a new listing: reset the page number and the cursor list, and
+  keep `<text>` as the filter so `next` / `prev` page through the matches. If
+  `total` is 0, say *"No datapacks match `<text>`."* and re-prompt with the
+  legend. If `total` is exactly 1, that's the choice. Otherwise render the
+  matches with the search count line from step 2.
+- **`next`** → if `has_more` is false, say this is the last page and
+  re-prompt. If `next_cursor` is empty, say this server cannot page further
+  and ask for a substring; do not send an empty cursor. Otherwise call
+  `datapack_search` with the same `query` (if any), `limit=10` and
+  `cursor="<next_cursor>"`, add that cursor to your list, and render the new
+  page. Reuse the `total` you already have.
+- **`prev`** → on page 1, say this is the first page and re-prompt. Otherwise
+  drop the last cursor from your list and call `datapack_search` again with
+  the same `query` and the cursor now at the end of the list (no cursor for
+  page 1).
 - **`cancel`** → leave any existing pin in place; print *"Cancelled. Active datapack unchanged."* Stop.
 - **`clear` / `none` / `unpin`** → see step 4's clear path.
 - **Unrecognized** → re-prompt with the legend.
 
+If a call with a `cursor` returns an error, the cursor is no longer usable.
+Tell the user, then start again from the first page of the same filter.
+
+When the user names a datapack in the request itself ("pin prod-research"),
+skip the first listing and go straight to the substring search with that name.
+
+### Fallback: servers without `datapack_search`
+
+An older Meko server has only `datapack_list`. Run the same steps with these
+changes:
+
+```
+datapack_list(conversation_id="<this conversation's id>")
+```
+
+- The response is one array of every datapack, with the same row fields.
+  `total` is the array length.
+- Sort it `created_at DESC` yourself, show 10 rows per page, and page
+  `next` / `prev` over the array you already have.
+- Filter substrings client-side on `datapack_name` (case-insensitive) and
+  re-render the matching rows numbered from 1. If the filter narrows to one
+  row, that's the choice.
+
+If `datapack_list` returns `{"error": "too_many_datapacks", ...}`, the server
+does have `datapack_search`; your tool list is stale. Reload the Meko tools and
+use the main flow.
+
 ### 4. Persist
 
 **On first pin (no existing pin memory):**

package/assets/skills/meko-select-datapack-desktop/references/cookbook.md

@@ -1,6 +1,6 @@
 # Cookbook — meko-select-datapack-desktop
 
-Concrete transcripts of the four flows the skill supports on Claude Desktop.
+Concrete transcripts of the flows the skill supports on Claude Desktop.
 
 ## Flow 1 — First pin (no existing pin memory)
 
@@ -11,8 +11,8 @@ Concrete transcripts of the four flows the skill supports on Claude Desktop.
 > memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<conv-id>", limit=1)
 [empty]
 
-> datapack_list(conversation_id="<conv-id>")
-[14 entries returned, filtering by "prod-research"]
+> datapack_search(conversation_id="<conv-id>", query="prod-research", limit=10, include_total=true)
+[1 row, has_more=false, next_cursor="", total=1]
 
 One match: `prod-research`. Pinning.
 
@@ -44,8 +44,8 @@ datapack_id flows through automatically.
 > memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<conv-id>", limit=1)
 [returns id=mem_abc123, text="meko_active_datapack=8b1c…f4a2 name=prod-research …"]
 
-> datapack_list(conversation_id="<conv-id>")
-[14 entries returned, filtering by "q2-roadmap-deck"]
+> datapack_search(conversation_id="<conv-id>", query="q2-roadmap-deck", limit=10, include_total=true)
+[1 row, has_more=false, next_cursor="", total=1]
 
 One match: `q2-roadmap-deck`. Switching pin.
 
@@ -69,8 +69,8 @@ The `memory_update` is critical here — using `memory_add` again would create a
 > memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<conv-id>", limit=1)
 [empty]
 
-> datapack_list(conversation_id="<conv-id>")
-[1 entry returned]
+> datapack_search(conversation_id="<conv-id>", limit=10, include_total=true)
+[1 row, has_more=false, next_cursor="", total=1]
 
 Only one datapack: `meko-local-setup`. Auto-selecting.
 
@@ -119,3 +119,35 @@ This isn't a user-triggered flow — it's the per-turn lookup the skill teaches
 ```
 
 Cache the UUID for the rest of the turn — don't call `memory_search` once per Meko tool call.
+
+## Flow 6: Browse and page
+
+**User:** `list my datapacks`
+
+**Skill:**
+```
+> datapack_search(conversation_id="<conv-id>", limit=10, include_total=true)
+[10 rows, has_more=true, next_cursor="eyJ2Ijox…", total=14]
+
+Your datapacks (showing 1-10 of 14):
+…
+```
+
+**User:** `next`
+
+```
+> datapack_search(conversation_id="<conv-id>", limit=10, cursor="eyJ2Ijox…")
+[4 rows, has_more=false, next_cursor=""]
+
+Your datapacks (showing 11-14 of 14):
+…
+
+Reply with: a number (11-14) to pin · a substring to search · `prev` to page
+            · `clear` to unset · `cancel` to leave the current pin alone
+```
+
+The skill remembers each cursor it used. On `prev` it drops the last one and repeats the call for page 1, which had no cursor. The total (14) is reused from page 1. A substring reply calls `datapack_search(query="<text>", limit=10, include_total=true)` and starts a new listing.
+
+## Flow 7: Older server without `datapack_search`
+
+The tool list has `datapack_list` but no `datapack_search`. The skill calls `datapack_list(conversation_id="<conv-id>")` once, then sorts, pages and filters that array in the conversation. The table and replies look the same.

package/assets/skills/meko-select-datapack-desktop/references/role-display-future.md

@@ -2,7 +2,7 @@
 
 ## Today: render `grant` verbatim
 
-The deployed Meko `GET /datapacks` response includes a `grant` field on every datapack. Possible values (per maintainer guidance, 2026-05-26):
+The deployed Meko `GET /datapacks` response includes a `grant` field on every datapack, and so does every row that `datapack_search` and `datapack_list` return. Possible values (per maintainer guidance, 2026-05-26):
 
 - `"owner"` — datapacks the caller created.
 - `"maintainer"` — write access to a shared datapack including memories AND collective learnings/knowledge.
@@ -20,11 +20,11 @@ Use the field directly in the **Role** column:
 
 Do not invent values, do not normalize the casing, do not display `"Owner"` if the field says `"owner"`. The deployed schema is the source of truth.
 
-Note that the upstream Go source (the `Datapack` struct in `api_server/internal/models/models.go` of the `meko` API-server repo) does NOT declare `grant` — the deployed server enriches the response beyond what the public Go code lists. Don't rely on the public struct for the wire schema; trust the actual response.
+Note that the server's `Datapack` model doesn't declare `grant`: the deployed server enriches the response beyond what the public Go code lists. Don't rely on the public struct for the wire schema; trust the actual response.
 
-## Other fields the live response includes
+## Counts are not on the list response
 
-`datapack_list` doesn't compute counts; its list response carries no count fields. If the user asks for counts, call `datapack_describe(datapack_id=<id>, conversation_id="<conversation id>")` and read them from that response:
+Neither `datapack_search` nor `datapack_list` computes counts; their rows carry no count fields. If the user asks for counts, call `datapack_describe(datapack_id=<id>, conversation_id="<conversation id>")` and read them from that response:
 
 - `memory_count`: all memories stored in the datapack.
 - `collective_memory_count`: memories promoted to shared knowledge.
@@ -34,9 +34,11 @@ Note that the upstream Go source (the `Datapack` struct in `api_server/internal/
 
 Don't add counts to the table silently, and never invent the numbers.
 
-## Sharing UI vs API state
+## Sharing a datapack
 
-The Cloud console "Share <datapack>" page (`meko_ui/src/features/datapacks/pages/DatapackSharePage.tsx`) shows interactive controls with "Coming Soon" overlays on a few specific actions (e.g. invite-by-email link sharing, transfer-ownership). Those overlays mean *those specific UI affordances* aren't shipped — NOT that the underlying `grant`/sharing model is absent. Contributor/maintainer/viewer grants are functional in the data layer today; only the user-facing self-serve invite flow is gated.
+An owner or maintainer shares a datapack from the Cloud console's **Share** page. Each datapack has one share link. The owner or maintainer can turn it on or off, reset it, and choose whether people who open it join as viewer or contributor. Anyone signed in who opens an active link joins straight away. There are no MCP tools to manage sharing.
+
+A viewer is read-only, and the server enforces it: over MCP, conversation and memory writes return `read_only_access`. If the user picks a datapack where they're a viewer, tell them that Meko won't record conversations or save memories there.
 
 ## Why the skill ships without Mine / Shared / All filter tabs
 

package/assets/skills/meko-select-datapack-desktop/references/troubleshooting.md

@@ -33,7 +33,7 @@ Then either re-run the skill or delete the pin memory. Do not silently fall back
 
 Never auto-pick when there's ambiguity. Re-render just the matching rows numbered from 1, and ask the user to pick a number from the filtered subset. Same as the Claude Code variant.
 
-## Symptom: `datapack_list` returns an empty array
+## Symptom: The account has no datapacks (`total` is 0, or `datapack_list` returns an empty array)
 
 The user has zero datapacks. Print:
 
@@ -47,6 +47,18 @@ Or visit the Meko Cloud console (Datapacks → New datapack).
 
 Stop. Don't `memory_add` an empty pin.
 
+## Symptom: `next` or `prev` returns an error about the cursor
+
+The cursor is tied to the search it came from. It stops working if you change `query`, `sort` or `grant` while paging, or if you edit it. Always send the cursor back unchanged, with the same filters as the call that returned it. Tell the user the page could not be loaded and start again from page 1 of the same search (no cursor).
+
+## Symptom: `datapack_list` returns `too_many_datapacks`
+
+The account can see more datapacks than `datapack_list` returns in one array (1000 by default). The server that sends this error also has `datapack_search`. Use the main flow with `datapack_search`; if it is missing from your tool list, the list is stale, so reload the Meko tools.
+
+## Symptom: The tool list has no `datapack_search`
+
+The Meko server is older than that tool. Use the skill's fallback flow with `datapack_list`: one call, then sort, page and filter the array in the conversation. On an older server, this call can fail for an account with a very large number of datapacks; that account needs a server that has `datapack_search`.
+
 ## Symptom: User typed `cancel` after the table rendered
 
 Leave the existing pin memory alone. Print: