@yugabytedb/meko-mcp 2.5.0 → 2.5.1

package/README.md

@@ -16,8 +16,11 @@ through `mcp-remote` header interpolation. Capture hooks use the same key.
 You don't need to have a key already. The installer gets one in this order:
 
 1. `--api-key <key>`.
-2. The `MEKO_API_KEY` environment variable.
-3. **Browser sign-in (the default).** The installer opens the Meko sign-in page,
+2. The `MEKO_API_KEY` environment variable, for any MCP URL, local ones
+   included. `--local` ignores it, and so does a `--yes` rerun that reuses the
+   URL an earlier `--local` install registered: the docker-compose dev stack
+   takes no key.
+3. **Browser sign-in (the default, Cloud only).** The installer opens the Meko sign-in page,
    and after you sign in it creates a key named `Meko installer (<host>)
    <timestamp>`. It uses the MCP server's OAuth flow with a `localhost`
    callback, then calls the server's `POST /api-keys`. The OAuth session is
@@ -170,6 +173,17 @@ npx @yugabytedb/meko-mcp \
   --yes
 ```
 
+**Meko Local (the `meko` server, which requires its client token):**
+
+```bash
+MEKO_API_KEY="$(meko token)" npx @yugabytedb/meko-mcp \
+  --url http://127.0.0.1:7778/mcp \
+  --yes
+```
+
+Passing the key through `MEKO_API_KEY` keeps it off the command line, where
+`ps` would show it.
+
 ## What It Does
 
 The installer performs up to 5 steps (some are skippable via flags):
@@ -256,9 +270,9 @@ Usage:
 |------|-------------|---------|
 | `--client <list>` | Target client(s): one or more of `claude-code`, `claude-desktop`, `cursor`, `codex`, `kiro`, `opencode`. Comma-separated, or `all`. `codex` covers both the OpenAI Codex CLI and the Codex Desktop App (they share `~/.codex/config.toml`); `kiro` covers both the Kiro IDE and `kiro-cli` (they share `~/.kiro/settings/mcp.json`). OpenCode is version-gated to CLI/TUI 1.18.x. Aliases: `claude` → `claude-code`, `kiro-cli` / `kiro-ide` → `kiro`. | `claude-code` |
 | `--url <url>` | MCP server URL (from cloud.mekodata.ai > Datapacks > Connect) | Shared existing endpoint, otherwise production; conflicts prompt or require `--url` under `--yes` |
-| `--api-key <key>` | Use an existing Cloud Meko API key instead of signing in. Without this flag, the installer falls back to `$MEKO_API_KEY`, then to browser sign-in, which creates a key. Fails hard when no TTY is attached, with or without `--yes`. | _(`$MEKO_API_KEY`, else browser sign-in)_ |
+| `--api-key <key>` | Use an existing Meko API key (Cloud, or Meko Local's client token) instead of signing in. Without this flag, the installer falls back to `$MEKO_API_KEY` for any URL (not with `--local`), then, for Cloud URLs only, to browser sign-in, which creates a key. A Cloud URL with no key fails hard when no TTY is attached, with or without `--yes`; a local URL installs without one. | _(`$MEKO_API_KEY`, else browser sign-in for Cloud)_ |
 | `--no-browser` | Print the sign-in URL instead of opening a browser. | `false` |
-| `--local` | Use local Meko at `http://localhost:8000/mcp` (no API key needed) | `false` |
+| `--local` | Use local Meko at `http://localhost:8000/mcp` (no API key; ignores `$MEKO_API_KEY`) | `false` |
 | `--scope <scope>` | Config scope: `user` or `project` (`claude-desktop` uses user scope config) | `user` |
 | `--name <name>` | MCP server name in config | `meko` |
 | `--cursor-hook-mode <mode>` | Cursor hook strategy: `native` or `claude-compat` | `native` |
@@ -351,7 +365,7 @@ Dry run:
 
 ### Why the migrator drives memory extraction
 
-The Meko MCP server does **not** currently auto-extract memories on `conversation_add_message` (that call only writes to Langfuse). See [yugabyte/meko#120](https://github.com/yugabyte/meko/issues/120) — auto-extraction on the live write path was deferred because of LLM cost, but batch extraction for *previously-existing* conversations was explicitly endorsed. Until #120 lands, the migrator closes that gap itself by calling `memory_add(messages=...)` once per paired turn.
+The Meko MCP server does **not** currently auto-extract memories on `conversation_add_message` (that call only writes to Langfuse). See [yugabyte/agentic-cloud#120](https://github.com/yugabyte/agentic-cloud/issues/120) — auto-extraction on the live write path was deferred because of LLM cost, but batch extraction for *previously-existing* conversations was explicitly endorsed. Until #120 lands, the migrator closes that gap itself by calling `memory_add(messages=...)` once per paired turn.
 
 `--no-extract` skips step 3 above, turning migration into conversation-only replay. Use it when you're re-running for any reason other than seeding memories, when extraction cost is a concern, or if / when #120 lands (the migrator will be updated to default to `--no-extract` then).
 

package/assets/hooks-handlers/lib/capture.js

@@ -2007,6 +2007,7 @@ function peekTranscriptMetadata(transcriptPath) {
 async function fetchRecentMemories(agentId, datapackId = null, { limit = 10, budget = 2000 } = {}) {
   // memory_get_all takes no `limit`, and FastMCP rejects an unknown argument
   // with an isError result, so `limit` caps the page client-side instead.
+  // Don't send `page_size` either: a server older than MEKO-453 rejects it.
   const payload = {
     agent_id: agentId,
     conversation_id: "00000000-0000-0000-0000-000000000000",

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

@@ -4,7 +4,7 @@ description: Behavioral guide for AI agents using Meko MCP tools. Triggers when
 license: MIT
 metadata:
   author: Meko
-  version: "3.4.0"
+  version: "3.5.0"
   tags: mcp, tools, datapack, memory, conversation, rag, meko
 ---
 
@@ -102,7 +102,8 @@ Recall first; save only what capture cannot reach; never re-store a just-stated
 | 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 private memories | Follow the exact-ID `memory_promote` confirmation workflow below. |
 | 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, 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. |
+| User wants a file kept in Meko but didn't say how | KB (`knowledgebase_upload_document`) if its content should be searchable later — docs, manuals, policies, notes people will ask about. Artifact (`artifact_put`) to keep it exactly as-is and fetch it back whole — a generated report, a result CSV. If it is not clear whether the user needs semantic search or whole-file retrieval, ask. |
+| 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 have the file's bytes — already on disk, or generated mid-conversation — and a shell, check that you can reach S3 first: run `curl -sS -o /dev/null -m 10 -w '%{http_code}' https://s3.amazonaws.com`; in Windows PowerShell, run `curl.exe` with `NUL` in place of `/dev/null`. A 2xx or 3xx status means yes (S3's root normally answers 307). `000`, a connection, DNS or proxy error, or any other status, such as a proxy's 403 or 407, means no. A pass shows outbound HTTPS to S3 works, not that the presigned bucket host does, so if the POST still fails, report it and stop. If it passes, call `knowledgebase_upload_document`. A sandboxed session may have the file but no outbound network; if the check fails, don't call it, since an unused URL holds storage quota for up to 15 minutes. 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. |
 
 ### When to call memory_add
 

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

@@ -296,7 +296,7 @@ Returns `{"document_id", "chunks_deleted", "s3_deleted"}` — if `s3_deleted` is
 
 ### 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"`.
+**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. Use it when the content should be searchable by meaning; to keep a file exactly as-is and fetch it back whole, use `artifact_put`. Before calling it, check that you can reach S3 first: run `curl -sS -o /dev/null -m 10 -w '%{http_code}' https://s3.amazonaws.com`; in Windows PowerShell, run `curl.exe` with `NUL` in place of `/dev/null`. A 2xx or 3xx status means yes (S3's root normally answers 307). `000`, a connection, DNS or proxy error, or any other status, such as a proxy's 403 or 407, means no. A pass shows outbound HTTPS to S3 works, not that the presigned bucket host does, so if the POST still fails, report it and stop; a sandboxed session may have the file but no outbound network. If the check fails, don't call it — point the user at the UI. 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.
 
@@ -465,7 +465,7 @@ Poll until `state` is `completed` or `failed` (or the pre-registration terminals
 
 ### artifact_put
 
-**When to use:** An agent has generated a file (report, CSV, PDF, code output, image) and wants to persist it in Meko for later retrieval or cross-agent sharing. Files < 1 MB are stored inline in the DB; files ≥ 1 MB go to the datapack's S3 bucket. Idempotent — uploading the same bytes twice returns the same `content_hash`.
+**When to use:** An agent has generated a file (report, CSV, PDF, code output, image) and wants to persist it in Meko for later retrieval or cross-agent sharing. To make its content searchable by meaning instead, use `knowledgebase_upload_document`. Files < 1 MB are stored inline in the DB; files ≥ 1 MB go to the datapack's S3 bucket. Idempotent — uploading the same bytes twice returns the same `content_hash`.
 
 ```
 artifact_put(
@@ -604,4 +604,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.
 
-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`.
+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, when you can POST the file's bytes yourself. 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/references/tools-datapack-workflow.md

@@ -35,7 +35,7 @@ Provisioning agents and knowledge-base *sources* (registering/indexing a new sou
 
 If the user asks to set those up mid-session, point them at the control plane rather than inventing an MCP call that will fail.
 
-Uploading a *file* into an existing KB is a different, already-MCP-exposed operation — use `knowledgebase_upload_document` (see `tools-cookbook.md`) rather than routing the user to the Add Knowledge UI.
+Uploading a *file* into an existing KB is a different, already-MCP-exposed operation — use `knowledgebase_upload_document` (see `tools-cookbook.md`) rather than routing the user to the Add Knowledge UI, when you can POST the file's bytes yourself.
 
 ### Targeting a specific datapack on subsequent calls
 

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

@@ -60,7 +60,7 @@ The one exception is a single uploaded **file**: `knowledgebase_delete_document`
 
 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.
+**Adding a file** is a registered MCP tool: if you can send the file's bytes in an HTTPS POST to an external URL yourself (a sandboxed session may have the file but no outbound network), 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.
 
@@ -85,7 +85,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 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.)
+2. **Upload the file itself to the knowledge base** with `knowledgebase_upload_document`, if you can POST its bytes yourself — `.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.
 

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

@@ -85,7 +85,7 @@ Agents on Cloud Meko have two distinct read surfaces. Pick the right one for the
 - **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 via MCP, 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/CSV/XML/HTML up to 5MB (Free) / 50MB (Standard) / 60MB (Pro+) each.
+  2. A file is uploaded — by an agent with `knowledgebase_upload_document`, or by the user 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.
 
@@ -102,7 +102,7 @@ Call `context_search`. One call returns your personal memories (every agent, no
 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 (PDF/TXT/MD/JSON/CSV/XML/HTML are supported).
+2. **Upload the file** with `knowledgebase_upload_document` if you have it and can POST its bytes to an external URL yourself, or suggest the user upload it 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: automatic, not proactive

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

@@ -108,14 +108,14 @@ Some things the Meko platform can do are not wired into the MCP tool surface tod
 
 | Capability | Where it lives | How to reach it |
 |---|---|---|
-| Create / list / delete **agents** within a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/agents` (`POST/GET/DELETE /agents/:agent` for targeted deletes), or the Meko control-plane UI |
-| Add / list / delete **knowledge-base sources** on a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/knowledge-bases`, plus `upload-url`, `upload-complete`, `create`, `status` subroutes. Also available in the Meko UI. |
-| Langfuse project-key generation | `yugabyte/meko` API server | REST: `POST /datapacks/:datapack_id/langfuse/project-keys` |
+| Create / list / delete **agents** within a datapack | Meko API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/agents` (`POST/GET/DELETE /agents/:agent` for targeted deletes), or the Meko control-plane UI |
+| Add / list / delete **knowledge-base sources** on a datapack | Meko API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/knowledge-bases`, plus `upload-url`, `upload-complete`, `create`, `status` subroutes. Also available in the Meko UI. |
+| Langfuse project-key generation | 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_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 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.
+For a file already on disk or generated mid-conversation, and when you can send the file's bytes in an HTTPS POST to an external URL yourself (a sandboxed session may have the file but no outbound network), 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
 

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

@@ -129,6 +129,8 @@ From `cloud.mekodata.ai`:
 
 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 — call
+already on disk, or generated mid-conversation — and can send them in an
+HTTPS POST to an external URL yourself, call
 `knowledgebase_upload_document` directly instead of describing the UI
-flow to yourself.
+flow to yourself. A sandboxed session may have the file but no outbound
+network; point the user at the UI then.

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

@@ -17,7 +17,7 @@ description: >-
 license: MIT
 metadata:
   author: Meko
-  version: "2.11.0"
+  version: "2.12.0"
   tags: mcp, yugabytedb, tools, datapack, memory, conversation, rag, meko, desktop
 ---
 
@@ -146,7 +146,8 @@ Your job is not to decide fact-by-fact what to `memory_add`. It's to **post ever
 | 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) | 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. |
+| User wants a file kept in Meko but didn't say how | KB (`knowledgebase_upload_document`) if its content should be searchable later — docs, manuals, policies, notes people will ask about. Artifact (`artifact_put`) to keep it exactly as-is and fetch it back whole — a generated report, a result CSV. If it is not clear whether the user needs semantic search or whole-file retrieval, ask. |
+| 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 have the file's bytes — already on disk, or generated mid-conversation — and a shell or code tool, check that you can reach S3 first: run `curl -sS -o /dev/null -m 10 -w '%{http_code}' https://s3.amazonaws.com`; in Windows PowerShell, run `curl.exe` with `NUL` in place of `/dev/null`. A 2xx or 3xx status means yes (S3's root normally answers 307). `000`, a connection, DNS or proxy error, or any other status, such as a proxy's 403 or 407, means no. A pass shows outbound HTTPS to S3 works, not that the presigned bucket host does, so if the POST still fails, report it and stop. If it passes, call `knowledgebase_upload_document`. Claude Desktop usually has no shell; with no shell or code tool, or a failed check, don't call it, since an unused URL holds storage quota for up to 15 minutes. 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
 
@@ -269,7 +270,7 @@ The Cloud UI's Learnings tab remains an alternative user-driven path.
 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 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`.
+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 send them in an HTTPS POST to an external URL yourself (a local shell, or a code tool with internet access); Claude Desktop usually can't, so point the user at the UI instead. Use the KB when the content should be searchable later, `artifact_put` to keep a file whole. 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.

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

@@ -295,7 +295,7 @@ Returns `{"document_id", "chunks_deleted", "s3_deleted"}` — if `s3_deleted` is
 
 ### 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"`.
+**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. Use it when the content should be searchable by meaning; to keep a file exactly as-is and fetch it back whole, use `artifact_put`. Before calling it, check that you can reach S3 first: run `curl -sS -o /dev/null -m 10 -w '%{http_code}' https://s3.amazonaws.com`; in Windows PowerShell, run `curl.exe` with `NUL` in place of `/dev/null`. A 2xx or 3xx status means yes (S3's root normally answers 307). `000`, a connection, DNS or proxy error, or any other status, such as a proxy's 403 or 407, means no. A pass shows outbound HTTPS to S3 works, not that the presigned bucket host does, so if the POST still fails, report it and stop. With no shell or code tool, or a failed check, don't call it — point the user at the UI. 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.
 
@@ -464,7 +464,7 @@ Poll until `state` is `completed` or `failed` (or the pre-registration terminals
 
 ### artifact_put
 
-**When to use:** An agent has generated a file (report, CSV, PDF, code output, image) and wants to persist it in Meko for later retrieval or cross-agent sharing. Files < 1 MB are stored inline in the DB; files ≥ 1 MB go to the datapack's S3 bucket. Idempotent — uploading the same bytes twice returns the same `content_hash`.
+**When to use:** An agent has generated a file (report, CSV, PDF, code output, image) and wants to persist it in Meko for later retrieval or cross-agent sharing. To make its content searchable by meaning instead, use `knowledgebase_upload_document`. Files < 1 MB are stored inline in the DB; files ≥ 1 MB go to the datapack's S3 bucket. Idempotent — uploading the same bytes twice returns the same `content_hash`.
 
 ```
 artifact_put(
@@ -596,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.
 
-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`.
+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, when you can POST the file's bytes yourself. 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

@@ -18,7 +18,7 @@ The one exception is a single uploaded **file**: `knowledgebase_delete_document`
 
 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.
+**Adding a file** is a registered MCP tool: if you can send the file's bytes in an HTTPS POST to an external URL yourself (a local shell, or a code tool with internet access), 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.
 
@@ -43,7 +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 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.)
+2. **Upload the file itself to the knowledge base** with `knowledgebase_upload_document`, if you can POST its bytes yourself — `.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.
 

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

@@ -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/CSV/XML/HTML up to 5MB (Free) / 50MB (Standard) / 60MB (Pro+) each.
+  2. A file is uploaded — by an agent with `knowledgebase_upload_document`, or by the user 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 (PDF/TXT/MD/JSON/CSV/XML/HTML are supported).
+2. **Upload the file** with `knowledgebase_upload_document` if you have it and can POST its bytes to an external URL yourself, or suggest the user upload it 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

@@ -108,14 +108,14 @@ Some things the Meko platform can do are not wired into the MCP tool surface tod
 
 | Capability | Where it lives | How to reach it |
 |---|---|---|
-| Create / list / delete **agents** within a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/agents` (`POST/GET/DELETE /agents/:agent` for targeted deletes), or the Meko control-plane UI |
-| Add / list / delete **knowledge-base sources** on a datapack | `yugabyte/meko` API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/knowledge-bases`, plus `upload-url`, `upload-complete`, `create`, `status` subroutes. Also available in the Meko UI. |
-| Langfuse project-key generation | `yugabyte/meko` API server | REST: `POST /datapacks/:datapack_id/langfuse/project-keys` |
+| Create / list / delete **agents** within a datapack | Meko API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/agents` (`POST/GET/DELETE /agents/:agent` for targeted deletes), or the Meko control-plane UI |
+| Add / list / delete **knowledge-base sources** on a datapack | Meko API server | REST: `POST/GET/DELETE /datapacks/:datapack_id/knowledge-bases`, plus `upload-url`, `upload-complete`, `create`, `status` subroutes. Also available in the Meko UI. |
+| Langfuse project-key generation | 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_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 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.
+For a file already on disk or generated mid-conversation, and when you can send the file's bytes in an HTTPS POST to an external URL yourself (a local shell, or a code tool with internet access), 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
 

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

@@ -129,6 +129,7 @@ From `cloud.mekodata.ai`:
 
 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 — call
-`knowledgebase_upload_document` directly instead of describing the UI
-flow to yourself.
+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/bin/create-meko-setup.mjs

@@ -10,6 +10,7 @@ import { askChoice, askMultiChoice, askText, askSecret, askYesNo, close as close
 import { banner, error, dim, info, success, warn } from '../lib/logger.mjs';
 import { BrowserLoginError, consoleUrlFor, loginAndCreateApiKey } from '../lib/browser-login.mjs';
 import {
+  isLocalUrl,
   isPackagedInstall,
   MEKO_PRODUCTION_CONSOLE_URL,
   selfInvocation,
@@ -86,6 +87,9 @@ function readVersion() {
   return pkg.version;
 }
 
+// The docker-compose dev stack that --local points at. It takes no API key.
+const LOCAL_DEV_MCP_URL = 'http://localhost:8000/mcp';
+
 const ALL_CLIENTS = ['claude-code', 'claude-desktop', 'cursor', 'codex', 'kiro', 'opencode'];
 
 function printHelp() {
@@ -139,11 +143,13 @@ Options:
                         untrusted IDE workspaces and non-managed CLI agents fall
                         back to agent-driven persistence.
   --url <url>           MCP server URL (from cloud.mekodata.ai > Datapacks > Connect)
-  --api-key <key>       Use an existing Cloud Meko API key instead of signing in
-                        through the browser. Also read from $MEKO_API_KEY.
-                        Required when no terminal is attached (CI, scripts).
+  --api-key <key>       Use an existing Meko API key (Cloud, or Meko Local's
+                        client token) instead of signing in through the
+                        browser. Also read from $MEKO_API_KEY for any URL
+                        (ignored with --local). Required for Cloud when no
+                        terminal is attached (CI, scripts).
   --no-browser          Print the sign-in URL instead of opening a browser
-  --local               Use local Meko at http://localhost:8000/mcp
+  --local               Use local Meko at http://localhost:8000/mcp (no API key)
   --scope <scope>       Config scope: user or project (default: user)
                         codex always installs at user scope (no project-level
                         config); --scope=project degrades with a warning.
@@ -225,10 +231,6 @@ Migrate existing conversations and memories into Meko:
   console.log(text);
 }
 
-function isCloudUrl(url) {
-  return url && !url.includes('localhost') && !url.includes('127.0.0.1');
-}
-
 /**
  * Sanitize a raw API key from any source (CLI flag, env var, askSecret prompt).
  *
@@ -479,7 +481,7 @@ async function main() {
     }
     let url = flags.url ?? process.env.MEKO_MCP_URL ?? null;
     let apiKey = normalizeApiKey(flags['api-key'] ?? process.env.MEKO_API_KEY);
-    if (flags.local) { url = 'http://localhost:8000/mcp'; apiKey = null; }
+    if (flags.local) { url = LOCAL_DEV_MCP_URL; apiKey = null; }
 
     let parentRate;
     try { parentRate = parseRate(flags.rate); }
@@ -558,11 +560,17 @@ async function main() {
   // prompt. Someone answered that prompt, so sign-in runs even when stdin
   // is not a TTY (e.g. piped answers in the smoke harness).
   let choseBrowserSignIn = false;
+  // Set for --local, the interactive "Local Meko" choice, and a --yes run
+  // that reuses an existing LOCAL_DEV_MCP_URL entry: the docker-compose dev
+  // stack takes no key, so $MEKO_API_KEY is not read for it. An explicit
+  // --url, local or not, still reads it.
+  let keylessLocal = false;
 
   // --local shortcut
   if (flags.local) {
-    url    = 'http://localhost:8000/mcp';
+    url    = LOCAL_DEV_MCP_URL;
     apiKey = null;
+    keylessLocal = true;
   }
 
   // Client picker — runs for any interactive invocation (including
@@ -628,6 +636,11 @@ async function main() {
         process.exit(1);
       }
       url = suggestedUrl.url;
+      // Reusing the dev stack an earlier --local install registered: keep it
+      // keyless, as --local would.
+      if (suggestedUrl.source === 'existing' && url === LOCAL_DEV_MCP_URL) {
+        keylessLocal = true;
+      }
     }
   }
 
@@ -689,8 +702,9 @@ async function main() {
         }
       }
     } else {
-      url    = 'http://localhost:8000/mcp';
+      url    = LOCAL_DEV_MCP_URL;
       apiKey = null;
+      keylessLocal = true;
     }
 
     // Step 4 — skills
@@ -724,22 +738,32 @@ async function main() {
     process.exit(1);
   }
 
-  // Validation — Cloud URL requires an API key.
-  // Resolution order: --api-key (already in `apiKey`) → $MEKO_API_KEY →
-  // browser sign-in, which creates a key through the server's
-  // POST /api-keys. Sign-in also covers the cloud one-liner from the UI,
-  // which only shows --url and --client. It is skipped when the full
-  // interactive flow already took a pasted key (an empty paste is an
-  // error, not a silent switch to the browser), and whenever stdin is not
-  // a terminal, with or without --yes: a script or CI step may have nobody
-  // at the browser, and a 5-minute callback wait would stall it. The one
-  // exception is an explicit "Sign in with browser" answer at the prompt.
-  if (isCloudUrl(url) && !apiKey) {
+  // API key resolution order: --api-key (already in `apiKey`) →
+  // $MEKO_API_KEY → browser sign-in (Cloud only).
+  //
+  // $MEKO_API_KEY applies to every URL, local ones included: Meko Local
+  // (the `meko` server, MCP on 127.0.0.1:7778) requires its client token,
+  // and AgentK passes that token only through the environment so it stays
+  // out of `ps`. Only the keyless dev stack (see `keylessLocal`) skips it.
+  if (!apiKey && !keylessLocal) {
     apiKey = normalizeApiKey(process.env.MEKO_API_KEY);
-    let signInFailed = false;
     if (apiKey) {
       dim('Using API key from MEKO_API_KEY environment variable.');
-    } else if (!promptedForApiKey && (process.stdin.isTTY || choseBrowserSignIn)) {
+    }
+  }
+
+  // Validation — Cloud URL requires an API key. Browser sign-in creates one
+  // through the server's POST /api-keys. Sign-in also covers the cloud
+  // one-liner from the UI, which only shows --url and --client. It is
+  // skipped when the full interactive flow already took a pasted key (an
+  // empty paste is an error, not a silent switch to the browser), and
+  // whenever stdin is not a terminal, with or without --yes: a script or CI
+  // step may have nobody at the browser, and a 5-minute callback wait would
+  // stall it. The one exception is an explicit "Sign in with browser" answer
+  // at the prompt. A local URL with no key installs without one.
+  if (!isLocalUrl(url) && !apiKey) {
+    let signInFailed = false;
+    if (!promptedForApiKey && (process.stdin.isTTY || choseBrowserSignIn)) {
       apiKey = await signInWithBrowser({
         url,
         noBrowser: flags['no-browser'],

package/lib/clients/codex.mjs

@@ -38,6 +38,7 @@ import {
 import {
   getInstallerVersion,
   installStableTree,
+  isLocalUrl,
   isPackagedInstall,
   isDanglingSymlink,
   markerIsStale,
@@ -909,30 +910,6 @@ function buildCliRegisterCommand(name, url, bearerEnv) {
   return cmd;
 }
 
-/**
- * True for localhost / loopback MCP URLs (no cloud WAF in front). Parses the
- * URL and compares the HOSTNAME exactly — a substring test would wrongly
- * classify `https://localhost.example.com` (a real remote host) as local and
- * skip the WAF User-Agent header. Unparseable input is treated as non-local
- * (cloud), i.e. we err toward setting the header.
- */
-function isLocalUrl(url) {
-  let host;
-  try {
-    host = new URL(String(url ?? "")).hostname;
-  } catch {
-    return false;
-  }
-  // `new URL` strips the brackets from IPv6 literals, so `[::1]` → `::1`.
-  host = host.replace(/^\[|\]$/g, "").toLowerCase();
-  return (
-    host === "localhost" ||
-    host === "::1" ||
-    // Entire 127.0.0.0/8 block is loopback, not just 127.0.0.1.
-    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)
-  );
-}
-
 const HTTP_HEADER_USER_AGENT_KEY = "User-Agent";
 
 // Matches one `KEY = "VALUE"` (or single-quoted) pair. KEY may be

package/lib/clients/common.mjs

@@ -114,6 +114,31 @@ export function run(cmd) {
   return execSync(cmd, { encoding: "utf8", stdio: "pipe" }).trim();
 }
 
+/**
+ * True for localhost / loopback MCP URLs (no cloud WAF in front, no browser
+ * sign-in). Parses the URL and compares the HOSTNAME exactly — a substring
+ * test would wrongly classify `https://localhost.example.com` (a real remote
+ * host) as local and `http://[::1]/mcp` as cloud. Unparseable input is
+ * treated as non-local (cloud): Codex errs toward setting the WAF User-Agent
+ * header, and the installer toward requiring an API key.
+ */
+export function isLocalUrl(url) {
+  let host;
+  try {
+    host = new URL(String(url ?? "")).hostname;
+  } catch {
+    return false;
+  }
+  // `new URL` strips the brackets from IPv6 literals, so `[::1]` → `::1`.
+  host = host.replace(/^\[|\]$/g, "").toLowerCase();
+  return (
+    host === "localhost" ||
+    host === "::1" ||
+    // Entire 127.0.0.0/8 block is loopback, not just 127.0.0.1.
+    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)
+  );
+}
+
 /**
  * @param {string|null|undefined} apiKey
  * @returns {string}

package/lib/migrate.mjs

@@ -20,7 +20,7 @@ import * as progress from "./migrate/progress.mjs";
 import { datapackKeyFromUrl } from "./migrate/id.mjs";
 import { resolveDestinationDatapack } from "./migrate/datapack.mjs";
 import { McpClient } from "./migrate/mcp-client.mjs";
-import { selfInvocation } from "./clients/common.mjs";
+import { isLocalUrl, selfInvocation } from "./clients/common.mjs";
 import { askYesNo } from "./prompt.mjs";
 
 function home() {
@@ -764,7 +764,3 @@ export async function stopMigration() {
     message: `Force-killed pid=${holder.pid} (run-id=${holder.runId}).`,
   };
 }
-
-function isLocalUrl(url) {
-  return /localhost|127\.0\.0\.1/.test(url ?? "");
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yugabytedb/meko-mcp",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Installer for Meko across Claude, Cursor, Codex, and Kiro clients",
   "type": "module",
   "bin": {