@yugabytedb/meko-mcp 1.1.0 → 1.2.0

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

@@ -0,0 +1,406 @@
+# Tool Cookbook — Complete Usage Examples
+
+Every tool example below shows the correct parameters, expected response, and common errors. Use `scope="read"` for reads and `scope="write"` for writes — never `"all"` or any other value.
+
+> **Note on `agent_id` in the examples below.** The string `"agent"` appears in these examples as a placeholder shorthand; it is NOT a required constant. Substitute **your** client's bucket: for Claude Desktop, the bare client name `claude_desktop`; for Claude Code/Cursor, `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). For genuinely cross-project facts (user identity, global preferences) write/read with `agent_id="meko_agent"` — the common bucket the server stores empty/missing values into. See `tools-agent-id-conventions.md`.
+>
+> **Note on availability on Cloud.** The `db_*` tools and the three KB ingestion tools (`knowledgebase_trigger_index_creation`, `knowledgebase_add_source_to_index`, `knowledgebase_check_index_status`) return `{"error": "not_available"}` on Cloud Meko today. This cookbook keeps their examples for reference but you can't call them from a Cloud client.
+
+---
+
+## Database Tools
+
+### db_summarize_database
+
+**When to use:** First thing in a session to understand what's in the database. Prefer this over writing your own `information_schema` query.
+
+```
+db_summarize_database(scope="read", schema="public")
+```
+
+**Response:**
+```json
+[
+  {
+    "table_name": "customers",
+    "schema": [
+      {"column_name": "id", "data_type": "uuid"},
+      {"column_name": "name", "data_type": "text"}
+    ],
+    "row_count": 1523
+  }
+]
+```
+
+**With datapack:**
+```
+db_summarize_database(scope="read", schema="public", datapack_id="dp-uuid-123")
+```
+
+**Common errors:**
+- `Insufficient scope: 'all'` — Use `scope="read"`, not `"all"`
+- Empty result — The schema may not exist, try `schema="public"`
+
+---
+
+### db_run_read_only_query
+
+**When to use:** Any SELECT query. Always add `LIMIT` on exploratory queries.
+
+```
+db_run_read_only_query(scope="read", query="SELECT id, name FROM customers LIMIT 10")
+```
+
+**Response:** JSON array of row objects.
+```json
+[{"id": "abc-123", "name": "Alice"}, {"id": "def-456", "name": "Bob"}]
+```
+
+**Best practices:**
+- Always use `LIMIT` on unfamiliar tables to avoid flooding context
+- Select specific columns rather than `SELECT *` to keep responses small
+- For non-public schemas: `SELECT * FROM analytics."monthly_revenue" LIMIT 5`
+- Escape single quotes in values: `WHERE name = 'O''Brien'`
+
+**Common errors:**
+- `cannot execute INSERT in a read-only transaction` — Use `db_run_write_query` for writes
+- `permission denied for table X` — MCP user lacks access to this table (server-side config issue, not fixable via MCP)
+- `connection already closed` — Retry once. If persistent, the DB pool is unhealthy.
+
+---
+
+### db_run_write_query
+
+**When to use:** INSERT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, DROP TABLE, CREATE INDEX.
+
+```
+db_run_write_query(scope="write", query="INSERT INTO customers (id, name) VALUES ('abc-123', 'Alice')")
+```
+
+**Response:**
+```json
+{"rows_affected": 1}
+```
+
+**One statement per call.** This is wrong:
+```
+db_run_write_query(scope="write", query="CREATE TABLE a (id INT); CREATE TABLE b (id INT);")
+```
+Split into two separate calls.
+
+**Bulk inserts:** Maximum 1000 rows per INSERT VALUES. For more, use `INSERT ... SELECT` or batch into multiple calls.
+
+**Common errors:**
+- `Multi-statement queries not allowed` — Send one statement per call
+- `DROP SCHEMA is not allowed` — See `tools-write-guardrails.md` for blocked operations
+- `'dict' object has no attribute 'guardrail_config'` — Known server bug in some deployments. Write operations may be unavailable.
+
+---
+
+## Memory Tools
+
+**Critical:** Pass your session's `agent_id` on every memory call. For Claude Desktop that's `claude_desktop` for client-personal context, or `meko_agent` for genuinely cross-project facts (user identity, global preferences). Personal writes are scoped strictly by `agent_id` — other agents won't see your writes on personal reads unless they pass the same exact value.
+
+### memory_add
+
+**When to use:** Store facts, preferences, user profile info, org conventions, corrections, learnings. Use proactively — don't wait for the user to ask.
+
+```
+memory_add(scope="write", agent_id="agent",
+    text="User Amiram is VP of Product at YugabyteDB. Prefers concise responses.")
+```
+
+**Response:**
+```json
+{"results": [{"id": "mem-uuid-123", "memory": "User Amiram is VP of Product at YugabyteDB. Prefers concise responses."}]}
+```
+
+**With user scoping:**
+```
+memory_add(scope="write", agent_id="agent", user_id="amiram",
+    text="Prefers Python for backend, Go for infrastructure.")
+```
+
+**What NOT to store via memory_add:**
+- CSV rows or tabular data (use `db_run_write_query` instead)
+- Full conversations (use `conversation_create` + `conversation_add_message`)
+- Large documents (use knowledge base ingestion)
+
+**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.
+- `connection already closed` — Retry once. If it fails again, the memory subsystem is down.
+
+---
+
+### memory_search
+
+**When to use:** Find relevant memories by meaning. Always try this before asking the user to repeat information.
+
+```
+memory_search(scope="read", query="What programming language does the team use?", agent_id="agent")
+```
+
+**Response:**
+```json
+{"results": [{"id": "mem-uuid-123", "memory": "Team uses Python for backend", "score": 0.89}]}
+```
+
+**With limit:**
+```
+memory_search(scope="read", query="user preferences", agent_id="agent", limit=5)
+```
+
+---
+
+### memory_get_all
+
+**When to use:** List everything stored for an agent. Useful at session start to load context.
+
+```
+memory_get_all(scope="read", agent_id="agent")
+```
+
+**With user scoping:**
+```
+memory_get_all(scope="read", agent_id="agent", user_id="amiram")
+```
+
+---
+
+### memory_get_by_id
+
+```
+memory_get_by_id(scope="read", memory_id="mem-uuid-123", agent_id="agent")
+```
+
+---
+
+### memory_update
+
+**When to use:** Overwrite a specific memory's text. Requires the memory UUID.
+
+```
+memory_update(scope="write", memory_id="mem-uuid-123", text="Updated: Team uses Go for all new services", agent_id="agent")
+```
+
+---
+
+### memory_delete_by_id
+
+```
+memory_delete_by_id(scope="write", memory_id="mem-uuid-123", agent_id="agent")
+```
+
+---
+
+### memory_delete_all
+
+**Destructive. Requires admin scope.** Deletes all memories for the agent.
+
+```
+memory_delete_all(scope="admin", agent_id="agent")
+```
+
+---
+
+## Conversation Tools
+
+### conversation_create
+
+**When to use:** Start storing a multi-turn exchange. Do this when the session contains valuable dialog worth preserving.
+
+```
+conversation_create(scope="write", agent_id="agent", user_id="amiram",
+    title="Debugging the auth middleware")
+```
+
+**Response:**
+```json
+{"id": "conv-uuid-123", "title": "Debugging the auth middleware"}
+```
+
+---
+
+### conversation_add_message
+
+**When to use:** Add a user/assistant exchange to an existing conversation. **All fields must be verbatim** — never summarize or rephrase.
+
+```
+conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+    input="Why is the auth middleware returning 401?",
+    output="The token validation is checking the wrong issuer claim...",
+    reasoning="Checked the middleware source, found issuer mismatch between config and JWT...")
+```
+
+**With dedup seed (use when client hooks also write to Langfuse):**
+```
+conversation_add_message(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+    input="Why is the auth middleware returning 401?",
+    output="The token validation is checking the wrong issuer claim...",
+    seed="conv-uuid-123:agent:Why is the auth middleware returning 401?")
+```
+
+---
+
+### conversation_get
+
+```
+conversation_get(scope="read", conversation_id="conv-uuid-123", agent_id="agent",
+    include_messages=True, limit=50)
+```
+
+---
+
+### conversation_list
+
+```
+conversation_list(scope="read", agent_id="agent", limit=20)
+```
+
+---
+
+### conversation_update
+
+```
+conversation_update(scope="write", conversation_id="conv-uuid-123", agent_id="agent",
+    title="Resolved: Auth middleware issuer mismatch")
+```
+
+---
+
+### conversation_delete
+
+**Destructive. Requires admin scope.**
+
+```
+conversation_delete(scope="admin", conversation_id="conv-uuid-123", agent_id="agent")
+```
+
+---
+
+## RAG / Knowledge Base Tools
+
+**On cloud Meko today, 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). The three ingestion-side MCP tools below are Free-Tier-gated on cloud and brittle even when ungated. `knowledgebase_search` is the one KB tool to reach for.
+
+See `tools-rag-workflow.md` for the decision table and why.
+
+### knowledgebase_search
+
+**When to use:** Retrieve chunks from a populated KB. Works on cloud today.
+
+```
+knowledgebase_search(
+    scope="read",
+    query="natural-language question",
+    agent_id="agent",
+    conversation_id="<uuid from conversation_create>",
+    datapack_id="<datapack UUID — REQUIRED here, no default>",
+    limit=10)
+```
+
+Unlike memory tools, `datapack_id` has no default — you must pass it explicitly.
+
+**Response (empty KB, verified 2026-05-07):**
+```json
+{"results": [], "count": 0}
+```
+
+Populated KBs return results with chunk content and similarity scores. An empty/nonexistent KB is not an error — just `count: 0`.
+
+---
+
+### knowledgebase_trigger_index_creation
+
+**When to use:** Self-hosted deployments where the ingestion worker has IAM access to the target S3 bucket. **Not available on cloud Free Tier** (returns `{"error": "not_available", "detail": "Vector index creation is not available on the free tier."}`).
+
+```
+knowledgebase_trigger_index_creation(
+    scope="write",
+    conversation_id="<uuid from conversation_create>",
+    source_uris="s3://my-bucket/docs/,s3://my-bucket/reports/",
+    index_name="company_docs")
+```
+
+**Optional parameters:**
+- `ai_provider="OPENAI"` (default)
+- `embedding_model="text-embedding-3-large"` (default)
+- `embedding_dimensions=1536` (default)
+- `chunk_size=1024` (default)
+- `chunk_overlap=256` (default)
+- `datapack_id=None`
+
+**Success response:**
+```json
+{"source_ids": ["<uuid>", ...], "index_id": "<uuid>", "index_name": "company_docs",
+ "status": "build_triggered", "message": "... registered, index '...' initialised, and build triggered."}
+```
+
+**Critical caveats:**
+- URIs must start with `s3://`. The worker (`aws_source_processor.py:86-117`) rejects any other scheme with `ValueError("Invalid source URI")` — async, not surfaced through the MCP response.
+- The worker uses the boto3 default credential chain (env vars, IAM role, `~/.aws/credentials` on the worker host). There is no way for the user to pass AWS credentials through the MCP tool. If the worker's identity can't read the bucket, the build stalls at INIT.
+- Each call creates a new index. Do NOT retry on failure — you'll get duplicate indexes.
+- Tracked as a gap: [yugabyte/meko-mcp-server#89](https://github.com/yugabyte/meko-mcp-server/issues/89) / MEKO-96.
+
+---
+
+### knowledgebase_check_index_status
+
+**When to use:** Poll a self-hosted build for completion. **Not available on cloud Free Tier** (returns `{"error": "not_available"}`).
+
+```
+knowledgebase_check_index_status(
+    scope="read",
+    conversation_id="<uuid from conversation_create>",
+    index_name="company_docs",
+    datapack_id=None)
+```
+
+Check `completion_rate_percent` in `pipeline_stats` and `document_status` in `pipeline_details`. If documents stay at `INIT` for >5 minutes, the worker probably can't reach the bucket. Stop polling after 3 consecutive no-progress checks.
+
+---
+
+### knowledgebase_add_source_to_index
+
+**When to use:** Grow an existing index with a new source URI (self-hosted / paid). **Not available on cloud Free Tier** (same "Vector index creation is not available" gate as `trigger_index_creation`).
+
+```
+knowledgebase_add_source_to_index(
+    scope="write",
+    conversation_id="<uuid from conversation_create>",
+    index_name="company_docs",
+    source_uri="s3://my-bucket/new-docs/")
+```
+
+Param is **`source_uri`** (URI string), not `source_id` — older docs had this wrong.
+
+The historical `r_index_name` vs `r_index_id` parameter-mismatch bug (reported in 2026-03) is **fixed** on main. The tool now resolves `index_name → index_id` internally via `SELECT id FROM dist_rag.vector_indexes WHERE index_name = %s` before calling the dist_rag function. If the name doesn't exist you get `{"error": "index_not_found", "detail": "No vector index found with name '...'"}`.
+
+Same S3-only / worker-credentials caveats as `trigger_index_creation` apply.
+
+---
+
+## Datapack Management Tools
+
+### datapack_create / datapack_list / datapack_describe
+
+```
+datapack_create(scope="write", name="analytics_prod")
+datapack_list(scope="read")
+datapack_describe(scope="read", name="analytics_prod", include_status=True)
+```
+
+### datapack_update / datapack_delete
+
+```
+datapack_update(scope="write", name="analytics_prod", connection_string="postgresql://...")
+datapack_delete(scope="admin", name="analytics_prod")  # Irreversible!
+```
+
+### Agent and knowledge-base management (NOT MCP — control-plane only)
+
+Agent and KB lifecycle does not ship as MCP tools. If the user asks to create/list/delete agents or KB sources, don't invent a tool call — point them at the control plane:
+
+- REST: `POST/GET/DELETE /datapacks/:name/agents` (agents), `POST/GET/DELETE /datapacks/:name/knowledge-bases` (KB sources).
+- Or the Meko UI at `app.mekodev.com` → Datapacks → agents / knowledge-bases.
+
+To build a RAG index from inside a session (which IS MCP-exposed), use `knowledgebase_trigger_index_creation` / `knowledgebase_add_source_to_index` / `knowledgebase_check_index_status` — those operate on `dist_rag` tables inside the datapack's database.

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

@@ -0,0 +1,69 @@
+# Known Limitations
+
+These are current limitations of the Meko MCP tools. Know them upfront to avoid wasted tool calls.
+
+## No delete tools for RAG artifacts
+
+There are no MCP tools to:
+- Delete a vector index
+- Remove a source from an index
+- Clear stuck work queue entries
+- Reset a failed pipeline
+
+KB-source deletion happens via the Meko control plane (REST: `DELETE /datapacks/:name/knowledge-bases`, or the UI), which removes the registration from the Meko API — but does **not** touch the actual `dist_rag` index, source records, or vector data in the datapack's database.
+
+**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.
+
+## No MCP tool to query a built RAG index
+
+The RAG tools (`knowledgebase_trigger_index_creation`, `knowledgebase_add_source_to_index`, `knowledgebase_check_index_status`) handle index **creation and monitoring** only.
+
+To actually **query** a built index on Cloud, use `knowledgebase_search` — it returns both uploaded documents (UI "Add Knowledge" flow) and memories the user promoted from the Learnings tab. The `db_run_read_only_query` direct-DB path is Free-Tier-gated on Cloud.
+
+## Memory tools unreliable for structured/tabular data
+
+`memory_add` passes text through Mem0's fact extraction pipeline. This works well for:
+- Facts: "Alice works at Acme Corp"
+- Preferences: "User prefers dark mode"
+- Entity relationships: "Amiram reports to Karthik"
+
+It works **poorly** for:
+- CSV rows or tabular data — columns and rows get dropped
+- Data dictionaries — only partial information extracted
+- Structured schemas — relationships between fields lost
+
+**On Cloud, structured data is not MCP-supported today.** `db_run_write_query` / `db_run_read_only_query` / `db_summarize_database` all return `{"error": "not_available", "detail": "Free Tier: DB Tools access is not enabled. coming soon."}`. The options are:
+
+1. **Write a single narrative summary** as a memory — one call, not row-by-row:
+   ```
+   memory_add(scope="write",
+       agent_id="<your session agent_id>",
+       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 a Cloud feature today and let them decide how to proceed.
+
+Never ingest CSV row-by-row into memory — each row becomes a fragmented fact with lost context.
+
+## MCP user permission gaps
+
+The MCP database user may not have read access to all tables within a datapack, particularly:
+- Data tables created by the provisioning system
+- Tables in non-public schemas
+
+If `db_run_read_only_query` returns "permission denied", this is a server-side configuration issue. Use `db_summarize_database` to see which tables are accessible.
+
+## Currently broken tools
+
+**`db_run_write_query`** — May fail with `'dict' object has no attribute 'guardrail_config'` in some deployments. When this happens, all write operations are blocked for the session.
+
+**Knowledge-base ingestion tools on cloud Meko** (`knowledgebase_trigger_index_creation`, `knowledgebase_add_source_to_index`, `knowledgebase_check_index_status`) return `{"error": "not_available"}` on Free Tier. Even when ungated, the async worker only reads `s3://` URIs and uses its own boto3 credential chain — it cannot read buckets the user provides credentials for. Tracked: [yugabyte/meko-mcp-server#89](https://github.com/yugabyte/meko-mcp-server/issues/89) / MEKO-96. Use the Meko UI's **Add Knowledge** file-upload dialog for ingestion on cloud. `knowledgebase_search` works on cloud today.
+
+(Historical note: `knowledgebase_add_source_to_index` used to have a `r_index_name` vs `r_index_id` SQL-signature bug. That specific bug was fixed on main in commit `3ae724a` — the tool now resolves `index_name → index_id` internally.)
+
+## No conversation search
+
+`conversation_list` returns conversations by agent, but there is no semantic search across conversation content. To find a specific past exchange, you need to list conversations and inspect them individually with `conversation_get`.
+
+For finding past knowledge by meaning, use `memory_search` instead — which is why storing key facts via `memory_add` alongside conversations is important.