mcp-probe-kit 3.0.17 → 3.0.19

package/docs/memory-local-setup.zh-CN.md

@@ -0,0 +1,280 @@
+# 本地记忆栈（Qdrant + Nomic Embed）
+
+面向 `memorize_asset`、`read_memory_asset`、`scan_and_extract_patterns` 的**轻量本机部署**说明：
+
+- **Qdrant** — 向量库（端口 `50008`）
+- **Infinity（nomic-embed）** — 向量生成（端口 `50012`），**替代 Ollama**，对用户更轻
+
+建议使用 Docker Compose 统一部署；端口采用 `500xx` 段，避免与其它服务冲突。
+
+| 服务 | 宿主机端口 | 容器端口 | 说明 |
+|------|------------|----------|------|
+| Qdrant HTTP | `50008` | `6333` | REST、Dashboard |
+| Qdrant gRPC | `50009` | `6334` | gRPC |
+| Nomic Embed | `50012` | `7997` | OpenAI 兼容 embedding |
+
+---
+
+## 1. Qdrant 向量数据库
+
+### 服务信息
+
+| 项 | 值 |
+|----|-----|
+| **镜像** | `qdrant/qdrant:latest` |
+| **容器名** | `qdrant` |
+| **HTTP** | `http://127.0.0.1:50008` |
+| **gRPC** | `127.0.0.1:50009` |
+| **数据** | `./data` → `/qdrant/storage` |
+| **快照** | `./snapshots` → `/qdrant/snapshots` |
+| **认证** | `.env` 中 `QDRANT_API_KEY`，请求头 `api-key` |
+
+### `docker-compose.yml`
+
+```yaml
+services:
+  qdrant:
+    image: qdrant/qdrant:latest
+    container_name: qdrant
+    restart: always
+    env_file:
+      - .env
+    ports:
+      - "50008:6333"
+      - "50009:6334"
+    volumes:
+      - ./data:/qdrant/storage
+      - ./snapshots:/qdrant/snapshots
+    environment:
+      - QDRANT__SERVICE__HTTP_PORT=6333
+      - QDRANT__SERVICE__GRPC_PORT=6334
+      - QDRANT__LOG_LEVEL=INFO
+      - QDRANT__SERVICE__API_KEY=${QDRANT_API_KEY}
+    healthcheck:
+      test:
+        - "CMD"
+        - "bash"
+        - "-c"
+        - "exec 3<>/dev/tcp/127.0.0.1/6333 && printf 'GET /collections HTTP/1.1\r\nHost: localhost\r\napi-key: ${QDRANT_API_KEY}\r\nConnection: close\r\n\r\n' >&3 && IFS= read -r line <&3 && [[ \"$$line\" == *\"200\"* ]]"
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 30s
+```
+
+### `.env.example`
+
+```bash
+# 复制：copy .env.example .env
+# 生成密钥：python -c "import secrets; print(secrets.token_urlsafe(32))"
+
+QDRANT_API_KEY=请改为长随机串
+QDRANT_URL=http://127.0.0.1:50008
+```
+
+### 首次部署
+
+```powershell
+cd qdrant
+copy .env.example .env
+# 编辑 .env，设置 QDRANT_API_KEY
+docker compose up -d
+```
+
+### 验证
+
+```bash
+curl http://127.0.0.1:50008/collections \
+  -H "api-key: 你的QDRANT_API_KEY"
+
+# 面板（需填入相同 Key）
+# http://127.0.0.1:50008/dashboard
+```
+
+### 常用命令
+
+```powershell
+docker compose up -d
+docker compose down
+docker compose logs -f qdrant
+docker compose restart qdrant
+```
+
+### 说明
+
+- 开启 `QDRANT__SERVICE__API_KEY` 后，所有 REST/gRPC 请求必须带 `api-key` 头。
+- mcp-probe-kit 通过环境变量 `MEMORY_QDRANT_API_KEY` 传入。
+- 首次 `memorize_asset` 写入会自动创建 collection `mcp_probe_memory`（Cosine；维度由首次 embedding 推断）。
+
+---
+
+## 2. Nomic Embed（Infinity 推理服务）
+
+基于 [Infinity](https://github.com/michaelfeil/infinity)，模型 `nomic-ai/nomic-embed-text-v1.5`，**768 维**，无需 Ollama。
+
+### 服务信息
+
+| 项 | 值 |
+|----|-----|
+| **镜像** | `michaelf34/infinity:0.0.70` |
+| **容器名** | `nomic-embed` |
+| **端口** | `50012` → `7997` |
+| **模型** | `nomic-ai/nomic-embed-text-v1.5` |
+| **向量维度** | 768 |
+| **引擎** | `torch`（无 GPU 走 CPU） |
+| **认证** | `INFINITY_API_KEY`（`Authorization: Bearer`） |
+| **模型缓存** | 卷 `hf_cache` → `/app/.cache` |
+
+### `docker-compose.yml`
+
+```yaml
+services:
+  nomic-embed:
+    image: michaelf34/infinity:0.0.70
+    container_name: nomic-embed
+    restart: unless-stopped
+    ports:
+      - "50012:7997"
+    volumes:
+      - hf_cache:/app/.cache
+    environment:
+      INFINITY_API_KEY: ${INFINITY_API_KEY}
+    command:
+      - v2
+      - --model-id
+      - nomic-ai/nomic-embed-text-v1.5
+      - --revision
+      - main
+      - --dtype
+      - float32
+      - --batch-size
+      - "8"
+      - --engine
+      - torch
+      - --port
+      - "7997"
+      - --no-bettertransformer
+    healthcheck:
+      test:
+        - "CMD"
+        - "curl"
+        - "-f"
+        - "http://127.0.0.1:7997/health"
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 120s
+
+volumes:
+  hf_cache:
+```
+
+### 首次部署
+
+```powershell
+cd nomic-embed
+copy .env.example .env
+docker compose up -d
+docker logs -f nomic-embed
+```
+
+冷启动需下载模型，约 **2–5 分钟**，日志出现 `ready to batch requests` 即就绪。
+
+### 访问与验证
+
+```bash
+curl http://127.0.0.1:50012/health
+
+curl http://127.0.0.1:50012/models \
+  -H "Authorization: Bearer 你的INFINITY_API_KEY"
+
+# 注意：路径是 POST /embeddings，不是 /v1/embeddings
+curl http://127.0.0.1:50012/embeddings \
+  -H "Authorization: Bearer 你的INFINITY_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"nomic-ai/nomic-embed-text-v1.5","input":"hello world"}'
+```
+
+Swagger：`http://127.0.0.1:50012/docs`
+
+### 性能（纯 CPU，参考）
+
+| 场景 | 约耗时 |
+|------|--------|
+| 单条短文本（热） | 30–50 ms |
+| 首条 | ~150 ms |
+| batch 8 | ~150 ms |
+| 常驻内存 | ~1 GB |
+
+适合 MCP 记忆、低频写入；不适合高并发批量入库。
+
+---
+
+## 3. 与 mcp-probe-kit / Qdrant 配合
+
+**推荐组合**：Qdrant `50008` + Infinity `50012`。
+
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "npx",
+      "args": ["-y", "mcp-probe-kit@latest"],
+      "env": {
+        "MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
+        "MEMORY_QDRANT_API_KEY": "与 qdrant/.env 中 QDRANT_API_KEY 相同",
+        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
+        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
+        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:50012/embeddings",
+        "MEMORY_EMBEDDING_MODEL": "nomic-ai/nomic-embed-text-v1.5",
+        "MEMORY_EMBEDDING_API_KEY": "与 nomic-embed/.env 中 INFINITY_API_KEY 相同",
+        "MEMORY_SEARCH_LIMIT": "3",
+        "MEMORY_SUMMARY_MAX_CHARS": "280"
+      }
+    }
+  }
+}
+```
+
+Claude Code：写入 `.mcp.json` 的 `mcpServers.mcp-probe-kit.env`。修改后**完全重启** Cursor。
+
+---
+
+## 4. 端到端自测
+
+```bash
+curl -s http://127.0.0.1:50008/collections -H "api-key: 你的QDRANT_API_KEY"
+
+curl -s -X POST http://127.0.0.1:50012/embeddings \
+  -H "Authorization: Bearer 你的INFINITY_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"nomic-ai/nomic-embed-text-v1.5","input":"测试"}' \
+  | jq '.data[0].embedding | length'
+# 期望输出：768
+```
+
+---
+
+## 5. 故障排查
+
+| 现象 | 处理 |
+|------|------|
+| Qdrant `401` | 配置 `MEMORY_QDRANT_API_KEY`，与 `.env` 一致 |
+| Embedding `401` | 检查 `Authorization: Bearer` 与 `INFINITY_API_KEY` |
+| Embedding `404` | URL 必须是 `/embeddings`，勿用 `/v1/embeddings` |
+| health 长期 `starting` | 首次下模型，看 `docker logs nomic-embed` |
+| 日志 `No CUDA runtime` | 正常，表示 CPU 推理 |
+| 向量维度不匹配 | 换模型后需新 collection 或删旧 collection |
+| 记忆写入不可用 | 同时配置 `MEMORY_QDRANT_URL`、`MEMORY_EMBEDDING_URL`、`MEMORY_EMBEDDING_MODEL` |
+
+---
+
+## 6. 其它方案
+
+| 方案 | 适用 |
+|------|------|
+| **本指南（Qdrant + Infinity）** | 本地开发默认，比 Ollama 轻 |
+| Qdrant + Ollama | 已用 Ollama 跑聊天模型时 |
+| Qdrant + 云端 OpenAI 兼容 API | 不想跑本地 embedding 容器 |
+
+英文版：[memory-local-setup.md](./memory-local-setup.md)

package/docs/pages/getting-started.html

@@ -255,51 +255,235 @@
                             <code class="bg-gray-200 px-1 rounded text-xs">scan_and_extract_patterns</code>
                             <span data-i18n="gettingStarted.step1.memory.descriptionSuffix">, you need to configure both a vector database and an embedding service.</span>
                         </p>
-                        <div class="space-y-3">
-                            <div>
-                                <p class="font-medium mb-2" data-i18n="gettingStarted.step1.memory.optionA.title">Option A: Qdrant + Ollama (recommended)</p>
-                                <pre class="code-block mb-2 p-3 text-sm text-slate-200 bg-slate-900 rounded overflow-x-auto"><code>docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
-ollama pull nomic-embed-text</code></pre>
-                                <pre class="code-block p-3 text-sm text-slate-200 bg-slate-900 rounded overflow-x-auto"><code>{
-  "mcpServers": {
-    "mcp-probe-kit": {
-      "command": "npx",
-      "args": ["-y", "mcp-probe-kit@latest"],
-      "env": {
-        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
-        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
-        "MEMORY_EMBEDDING_PROVIDER": "ollama",
-        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
-        "MEMORY_EMBEDDING_MODEL": "nomic-embed-text",
-        "MEMORY_SEARCH_LIMIT": "3",
-        "MEMORY_SUMMARY_MAX_CHARS": "280"
-      }
-    }
-  }
-}</code></pre>
+                        <p class="mb-3 text-text-secondary" data-i18n="gettingStarted.step1.memory.deployIntro">Copy the files below into two folders, start both services, then paste the MCP config. No Ollama required.</p>
+                        <p class="mb-3 text-text-secondary">
+                            <span data-i18n="gettingStarted.step1.memory.guideLink">Extended guide (troubleshooting, performance):</span>
+                            <a class="text-emerald-700 underline" href="https://github.com/mybolide/mcp-probe-kit/blob/main/docs/memory-local-setup.md" data-i18n="gettingStarted.step1.memory.guidePath">docs/memory-local-setup.md</a>
+                            · <a class="text-emerald-700 underline" href="https://github.com/mybolide/mcp-probe-kit/blob/main/docs/memory-local-setup.zh-CN.md">中文</a>
+                        </p>
+
+                        <p class="font-medium mb-1" data-i18n="gettingStarted.step1.memory.portTitle">Ports</p>
+                        <table class="w-full mb-4 text-xs border border-emerald-200 rounded overflow-hidden">
+                            <thead class="bg-emerald-100"><tr><th class="px-2 py-1 text-left">Service</th><th class="px-2 py-1 text-left">URL</th></tr></thead>
+                            <tbody>
+                                <tr class="border-t border-emerald-200"><td class="px-2 py-1">Qdrant HTTP</td><td class="px-2 py-1"><code>http://127.0.0.1:50008</code></td></tr>
+                                <tr class="border-t border-emerald-200"><td class="px-2 py-1">Qdrant gRPC</td><td class="px-2 py-1"><code>127.0.0.1:50009</code></td></tr>
+                                <tr class="border-t border-emerald-200"><td class="px-2 py-1">Nomic Embed</td><td class="px-2 py-1"><code>http://127.0.0.1:50012</code></td></tr>
+                            </tbody>
+                        </table>
+
+                        <p class="font-medium mb-1" data-i18n="gettingStarted.step1.memory.layoutTitle">0. Directory layout</p>
+                        <p class="mb-2 text-text-secondary" data-i18n="gettingStarted.step1.memory.layoutText">Create two folders anywhere on your machine (example: ~/mcp-memory/):</p>
+                        <pre class="code-block mb-4 p-3 text-sm text-slate-200 bg-slate-900 rounded overflow-x-auto"><code>mcp-memory/
+├── qdrant/
+│   ├── docker-compose.yml
+│   ├── .env
+│   ├── data/
+│   └── snapshots/
+└── nomic-embed/
+    ├── docker-compose.yml
+    └── .env</code></pre>
+
+                        <!-- Qdrant -->
+                        <p class="font-semibold mb-2" data-i18n="gettingStarted.step1.memory.qdrantTitle">1. Qdrant (vector DB, port 50008)</p>
+                        <p class="text-xs text-text-secondary mb-1" data-i18n="gettingStarted.step1.memory.qdrantCompose">qdrant/docker-compose.yml</p>
+                        <div class="bg-slate-900 rounded-lg overflow-hidden mb-3">
+                            <div class="flex items-center justify-between px-3 py-2 bg-slate-800">
+                                <span class="text-xs text-slate-300 font-medium">docker-compose.yml</span>
+                                <button type="button" onclick="copyCode(this)" class="text-xs text-slate-300 hover:text-white transition-colors" data-i18n="gettingStarted.common.copy">Copy</button>
                             </div>
-                            <div>
-                                <p class="font-medium mb-2" data-i18n="gettingStarted.step1.memory.optionB.title">Option B: Qdrant + OpenAI-Compatible Embedding API</p>
-                                <pre class="code-block mb-2 p-3 text-sm text-slate-200 bg-slate-900 rounded overflow-x-auto"><code>docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant</code></pre>
-                                <pre class="code-block p-3 text-sm text-slate-200 bg-slate-900 rounded overflow-x-auto"><code>{
+                            <pre class="code-block p-4 text-sm text-slate-200 overflow-x-auto"><code>services:
+  qdrant:
+    image: qdrant/qdrant:latest
+    container_name: qdrant
+    restart: always
+    env_file:
+      - .env
+    ports:
+      - "50008:6333"
+      - "50009:6334"
+    volumes:
+      - ./data:/qdrant/storage
+      - ./snapshots:/qdrant/snapshots
+    environment:
+      - QDRANT__SERVICE__HTTP_PORT=6333
+      - QDRANT__SERVICE__GRPC_PORT=6334
+      - QDRANT__LOG_LEVEL=INFO
+      - QDRANT__SERVICE__API_KEY=${QDRANT_API_KEY}
+    healthcheck:
+      test:
+        - "CMD"
+        - "bash"
+        - "-c"
+        - "exec 3&lt;&gt;/dev/tcp/127.0.0.1/6333 &amp;&amp; printf 'GET /collections HTTP/1.1\r\nHost: localhost\r\napi-key: ${QDRANT_API_KEY}\r\nConnection: close\r\n\r\n' &gt;&amp;3 &amp;&amp; IFS= read -r line &lt;&amp;3 &amp;&amp; [[ \"$$line\" == *\"200\"* ]]"
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 30s</code></pre>
+                        </div>
+                        <p class="text-xs text-text-secondary mb-1" data-i18n="gettingStarted.step1.memory.qdrantEnv">qdrant/.env</p>
+                        <div class="bg-slate-900 rounded-lg overflow-hidden mb-3">
+                            <div class="flex items-center justify-between px-3 py-2 bg-slate-800">
+                                <span class="text-xs text-slate-300 font-medium">.env</span>
+                                <button type="button" onclick="copyCode(this)" class="text-xs text-slate-300 hover:text-white transition-colors" data-i18n="gettingStarted.common.copy">Copy</button>
+                            </div>
+                            <pre class="code-block p-4 text-sm text-slate-200 overflow-x-auto"><code># Generate: python -c "import secrets; print(secrets.token_urlsafe(32))"
+QDRANT_API_KEY=change-me-to-a-long-random-string
+QDRANT_URL=http://127.0.0.1:50008</code></pre>
+                        </div>
+                        <p class="text-xs font-medium mb-1" data-i18n="gettingStarted.step1.memory.qdrantDeploy">Start Qdrant</p>
+                        <div class="bg-slate-900 rounded-lg overflow-hidden mb-3">
+                            <div class="flex items-center justify-between px-3 py-2 bg-slate-800">
+                                <span class="text-xs text-slate-300 font-medium">PowerShell / Bash</span>
+                                <button type="button" onclick="copyCode(this)" class="text-xs text-slate-300 hover:text-white transition-colors" data-i18n="gettingStarted.common.copy">Copy</button>
+                            </div>
+                            <pre class="code-block p-4 text-sm text-slate-200 overflow-x-auto"><code>cd qdrant
+mkdir data snapshots 2&gt;$null; mkdir -p data snapshots
+docker compose up -d
+docker compose ps</code></pre>
+                        </div>
+                        <p class="text-xs font-medium mb-1" data-i18n="gettingStarted.step1.memory.qdrantVerify">Verify Qdrant</p>
+                        <div class="bg-slate-900 rounded-lg overflow-hidden mb-2">
+                            <div class="flex items-center justify-between px-3 py-2 bg-slate-800">
+                                <span class="text-xs text-slate-300 font-medium">curl</span>
+                                <button type="button" onclick="copyCode(this)" class="text-xs text-slate-300 hover:text-white transition-colors" data-i18n="gettingStarted.common.copy">Copy</button>
+                            </div>
+                            <pre class="code-block p-4 text-sm text-slate-200 overflow-x-auto"><code>curl http://127.0.0.1:50008/collections \
+  -H "api-key: YOUR_QDRANT_API_KEY"</code></pre>
+                        </div>
+                        <p class="mb-4 text-xs text-text-secondary" data-i18n="gettingStarted.step1.memory.qdrantNote">When API key is enabled, all requests need header api-key. Dashboard: http://127.0.0.1:50008/dashboard</p>
+
+                        <!-- Nomic Embed -->
+                        <p class="font-semibold mb-2" data-i18n="gettingStarted.step1.memory.nomicTitle">2. Nomic Embed / Infinity (embeddings, port 50012)</p>
+                        <p class="text-xs text-text-secondary mb-1" data-i18n="gettingStarted.step1.memory.nomicCompose">nomic-embed/docker-compose.yml</p>
+                        <div class="bg-slate-900 rounded-lg overflow-hidden mb-3">
+                            <div class="flex items-center justify-between px-3 py-2 bg-slate-800">
+                                <span class="text-xs text-slate-300 font-medium">docker-compose.yml</span>
+                                <button type="button" onclick="copyCode(this)" class="text-xs text-slate-300 hover:text-white transition-colors" data-i18n="gettingStarted.common.copy">Copy</button>
+                            </div>
+                            <pre class="code-block p-4 text-sm text-slate-200 overflow-x-auto"><code>services:
+  nomic-embed:
+    image: michaelf34/infinity:0.0.70
+    container_name: nomic-embed
+    restart: unless-stopped
+    ports:
+      - "50012:7997"
+    volumes:
+      - hf_cache:/app/.cache
+    environment:
+      INFINITY_API_KEY: ${INFINITY_API_KEY}
+    command:
+      - v2
+      - --model-id
+      - nomic-ai/nomic-embed-text-v1.5
+      - --revision
+      - main
+      - --dtype
+      - float32
+      - --batch-size
+      - "8"
+      - --engine
+      - torch
+      - --port
+      - "7997"
+      - --no-bettertransformer
+    healthcheck:
+      test:
+        - "CMD"
+        - "curl"
+        - "-f"
+        - "http://127.0.0.1:7997/health"
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 120s
+
+volumes:
+  hf_cache:</code></pre>
+                        </div>
+                        <p class="text-xs text-text-secondary mb-1" data-i18n="gettingStarted.step1.memory.nomicEnv">nomic-embed/.env</p>
+                        <div class="bg-slate-900 rounded-lg overflow-hidden mb-3">
+                            <div class="flex items-center justify-between px-3 py-2 bg-slate-800">
+                                <span class="text-xs text-slate-300 font-medium">.env</span>
+                                <button type="button" onclick="copyCode(this)" class="text-xs text-slate-300 hover:text-white transition-colors" data-i18n="gettingStarted.common.copy">Copy</button>
+                            </div>
+                            <pre class="code-block p-4 text-sm text-slate-200 overflow-x-auto"><code># Generate: python -c "import secrets; print(secrets.token_urlsafe(32))"
+INFINITY_API_KEY=change-me-to-a-long-random-string</code></pre>
+                        </div>
+                        <p class="text-xs font-medium mb-1" data-i18n="gettingStarted.step1.memory.nomicDeploy">Start embedding service</p>
+                        <div class="bg-slate-900 rounded-lg overflow-hidden mb-3">
+                            <div class="flex items-center justify-between px-3 py-2 bg-slate-800">
+                                <span class="text-xs text-slate-300 font-medium">PowerShell / Bash</span>
+                                <button type="button" onclick="copyCode(this)" class="text-xs text-slate-300 hover:text-white transition-colors" data-i18n="gettingStarted.common.copy">Copy</button>
+                            </div>
+                            <pre class="code-block p-4 text-sm text-slate-200 overflow-x-auto"><code>cd nomic-embed
+docker compose up -d
+docker logs -f nomic-embed
+# Wait for: ready to batch requests</code></pre>
+                        </div>
+                        <p class="text-xs font-medium mb-1" data-i18n="gettingStarted.step1.memory.nomicVerify">Verify embeddings</p>
+                        <div class="bg-slate-900 rounded-lg overflow-hidden mb-2">
+                            <div class="flex items-center justify-between px-3 py-2 bg-slate-800">
+                                <span class="text-xs text-slate-300 font-medium">curl</span>
+                                <button type="button" onclick="copyCode(this)" class="text-xs text-slate-300 hover:text-white transition-colors" data-i18n="gettingStarted.common.copy">Copy</button>
+                            </div>
+                            <pre class="code-block p-4 text-sm text-slate-200 overflow-x-auto"><code>curl http://127.0.0.1:50012/health
+
+curl http://127.0.0.1:50012/embeddings \
+  -H "Authorization: Bearer YOUR_INFINITY_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"nomic-ai/nomic-embed-text-v1.5","input":"hello world"}'
+# Expect data[0].embedding length = 768</code></pre>
+                        </div>
+                        <p class="mb-4 text-xs text-text-secondary" data-i18n="gettingStarted.step1.memory.nomicNote">First start downloads the model (~2–5 min). Use POST /embeddings (not /v1/embeddings). Returns 768-dim vectors.</p>
+
+                        <!-- MCP -->
+                        <p class="font-semibold mb-2" data-i18n="gettingStarted.step1.memory.mcpTitle">3. MCP client configuration</p>
+                        <div class="bg-slate-900 rounded-lg overflow-hidden mb-2">
+                            <div class="flex items-center justify-between px-3 py-2 bg-slate-800">
+                                <span class="text-xs text-slate-300 font-medium">Cursor / Claude Desktop mcpServers</span>
+                                <button type="button" onclick="copyCode(this)" class="text-xs text-slate-300 hover:text-white transition-colors" data-i18n="gettingStarted.common.copy">Copy</button>
+                            </div>
+                            <pre class="code-block p-4 text-sm text-slate-200 overflow-x-auto"><code>{
   "mcpServers": {
     "mcp-probe-kit": {
       "command": "npx",
       "args": ["-y", "mcp-probe-kit@latest"],
       "env": {
-        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+        "MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
+        "MEMORY_QDRANT_API_KEY": "same-as-qdrant-.env-QDRANT_API_KEY",
         "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
-        "MEMORY_QDRANT_API_KEY": "",
         "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
-        "MEMORY_EMBEDDING_URL": "https://your-embedding-endpoint/v1/embeddings",
-        "MEMORY_EMBEDDING_API_KEY": "your-api-key",
-        "MEMORY_EMBEDDING_MODEL": "text-embedding-3-small",
+        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:50012/embeddings",
+        "MEMORY_EMBEDDING_MODEL": "nomic-ai/nomic-embed-text-v1.5",
+        "MEMORY_EMBEDDING_API_KEY": "same-as-nomic-embed-.env-INFINITY_API_KEY",
         "MEMORY_SEARCH_LIMIT": "3",
         "MEMORY_SUMMARY_MAX_CHARS": "280"
       }
     }
   }
 }</code></pre>
+                        </div>
+                        <p class="mb-4 text-xs text-text-secondary" data-i18n="gettingStarted.step1.memory.mcpNote">Use the same keys as in qdrant/.env and nomic-embed/.env. Restart Cursor after saving.</p>
+
+                        <p class="font-medium mb-2" data-i18n="gettingStarted.step1.memory.alternativesTitle">Other embedding options</p>
+                        <div class="space-y-3">
+                            <div>
+                                <p class="font-medium mb-2" data-i18n="gettingStarted.step1.memory.optionB.title">Option B: Qdrant + Ollama</p>
+                                <pre class="code-block mb-2 p-3 text-sm text-slate-200 bg-slate-900 rounded overflow-x-auto"><code>docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
+ollama pull nomic-embed-text</code></pre>
+                                <pre class="code-block p-3 text-sm text-slate-200 bg-slate-900 rounded overflow-x-auto"><code>"MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+"MEMORY_EMBEDDING_PROVIDER": "ollama",
+"MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
+"MEMORY_EMBEDDING_MODEL": "nomic-embed-text"</code></pre>
+                            </div>
+                            <div>
+                                <p class="font-medium mb-2" data-i18n="gettingStarted.step1.memory.optionC.title">Option C: Qdrant + hosted OpenAI-compatible API</p>
+                                <pre class="code-block p-3 text-sm text-slate-200 bg-slate-900 rounded overflow-x-auto"><code>"MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
+"MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
+"MEMORY_EMBEDDING_URL": "https://your-embedding-endpoint/v1/embeddings",
+"MEMORY_EMBEDDING_API_KEY": "your-api-key",
+"MEMORY_EMBEDDING_MODEL": "text-embedding-3-small"</code></pre>
                             </div>
                         </div>
                         <div class="mt-3">
@@ -511,6 +695,40 @@ npm run build</code></pre>
                             </div>
                         </div>
                     </div>
+
+                    <!-- OpenCode -->
+                    <div class="border border-border rounded-lg overflow-hidden">
+                        <button onclick="toggleClient('opencode')" class="w-full px-4 py-3 bg-bg-page flex items-center justify-between text-left hover:bg-gray-100 transition-colors">
+                            <div class="flex items-center gap-2">
+                                <span class="text-lg">🤖</span>
+                                <span class="font-medium text-text-primary" data-i18n="gettingStarted.step2.opencode.title">OpenCode</span>
+                            </div>
+                            <svg class="w-5 h-5 text-text-tertiary transition-transform" id="opencode-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"/>
+                            </svg>
+                        </button>
+                        <div id="opencode-content" class="hidden p-4 border-t border-border">
+                            <p class="text-text-secondary text-sm mb-3"><span data-i18n="gettingStarted.step2.opencode.description">Create or edit</span> <code class="bg-gray-200 px-1 rounded text-xs">opencode.json</code> <span data-i18n="gettingStarted.step2.opencode.description2">in project root, or globally at</span> <code class="bg-gray-200 px-1 rounded text-xs">~/.config/opencode/opencode.json</code></p>
+                            <div class="bg-slate-900 rounded-lg overflow-hidden">
+                                <div class="flex items-center justify-between px-3 py-2 bg-slate-800">
+                                    <span class="text-xs text-slate-300 font-medium">opencode.json</span>
+                                    <button onclick="copyCode(this)" class="text-xs text-slate-300 hover:text-white transition-colors" data-i18n="gettingStarted.common.copy">Copy</button>
+                                </div>
+                                <pre class="code-block p-4 text-sm text-slate-200 overflow-x-auto"><code>{
+  "mcp": {
+    "mcp-probe-kit": {
+      "type": "local",
+      "command": ["npx", "-y", "mcp-probe-kit@latest"],
+      "enabled": true
+    }
+  }
+}</code></pre>
+                            </div>
+                            <div class="p-3 mt-3 bg-blue-50 border-l-3 border-blue-500 rounded-r text-sm text-text-primary">
+                                <strong>💡 <span data-i18n="gettingStarted.step2.opencode.note">Note:</span></strong><span data-i18n="gettingStarted.step2.opencode.noteText">OpenCode uses <code>"environment"</code> (not <code>"env"</code>) for env vars, <code>"mcp"</code> (not <code>"mcpServers"</code>), and <code>"command"</code> as an array with <code>"type": "local"</code> required. See <a href="https://opencode.ai/docs/mcp" target="_blank" rel="noopener" class="text-primary hover:underline">OpenCode MCP docs</a>.</span>
+                            </div>
+                        </div>
+                    </div>
                 </div>
             </section>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-probe-kit",
-  "version": "3.0.17",
+  "version": "3.0.19",
   "description": "AI-Powered Development Toolkit - MCP Server with 28 tools covering code quality, development efficiency, project management, and UI/UX design. Features: Structured Output, Workflow Orchestration, UI/UX Pro Max, and Requirements Interview.",
   "mcpName": "io.github.mybolide/mcp-probe-kit",
   "type": "module",