mcp-probe-kit 3.0.18 → 3.0.19

package/docs/.mcp-probe/layout.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "projectRootEnv": "MCP_PROJECT_ROOT",
+  "indexPath": "AGENTS.md",
+  "contextRoot": "docs",
+  "modularDir": "docs/project-context",
+  "graphDir": "docs/graph-insights",
+  "indexStyle": "agents",
+  "generatedBy": "init_project_context",
+  "generatedAt": "2026-05-26T07:57:19.543Z"
+}

package/docs/i18n/en.json

@@ -14,14 +14,14 @@
   "hero": {
     "title": "🚀 MCP Probe Kit",
     "subtitle": "AI Development Enhancement Toolkit · Documentation Center",
-    "version": "v3.0.18",
+    "version": "v3.0.19",
     "quickStart": "Quick Start",
     "visitMainSite": "Visit ByteZoneX"
   },
   "sections": {
     "quickStart": {
       "title": "Quick Start",
-      "description": "Get started with MCP Probe Kit v3.0.18 in 5 minutes",
+      "description": "Get started with MCP Probe Kit v3.0.19 in 5 minutes",
       "installConfig": "Installation & Configuration"
     },
     "tools": {
@@ -63,7 +63,7 @@
   },
   "gettingStarted": {
     "title": "Installation & Configuration",
-    "subtitle": "Get started with MCP Probe Kit v3.0.18 in 5 minutes. Supports Cursor, Cline, and Claude Desktop",
+    "subtitle": "Get started with MCP Probe Kit v3.0.19 in 5 minutes. Supports Cursor, Cline, and Claude Desktop",
     "breadcrumb": {
       "home": "Documentation",
       "quickStart": "Quick Start",
@@ -91,11 +91,35 @@
         "title": "Memory System Setup (Qdrant + Embedding)",
         "descriptionPrefix": "If you want to use",
         "descriptionSuffix": ", you need to configure both a vector database and an embedding service.",
+        "guideLink": "Extended guide (troubleshooting, performance):",
+        "guidePath": "docs/memory-local-setup.md",
+        "deployIntro": "Copy the files below into two folders, start both services, then paste the MCP config. No Ollama required.",
+        "portTitle": "Ports",
+        "layoutTitle": "0. Directory layout",
+        "layoutText": "Create two folders anywhere on your machine (example: ~/mcp-memory/):",
+        "qdrantTitle": "1. Qdrant (vector DB, port 50008)",
+        "qdrantCompose": "qdrant/docker-compose.yml",
+        "qdrantEnv": "qdrant/.env",
+        "qdrantDeploy": "Start Qdrant",
+        "qdrantVerify": "Verify Qdrant",
+        "qdrantNote": "When API key is enabled, all requests need header api-key. Dashboard: http://127.0.0.1:50008/dashboard",
+        "nomicTitle": "2. Nomic Embed / Infinity (embeddings, port 50012)",
+        "nomicCompose": "nomic-embed/docker-compose.yml",
+        "nomicEnv": "nomic-embed/.env",
+        "nomicDeploy": "Start embedding service",
+        "nomicVerify": "Verify embeddings",
+        "nomicNote": "First start downloads the model (~2–5 min). Use POST /embeddings (not /v1/embeddings). Returns 768-dim vectors.",
+        "mcpTitle": "3. MCP client configuration",
+        "mcpNote": "Use the same keys as in qdrant/.env and nomic-embed/.env. Restart Cursor after saving.",
+        "alternativesTitle": "Other embedding options",
         "optionA": {
-          "title": "Option A: Qdrant + Ollama (recommended)"
+          "title": "Recommended stack (steps above)"
         },
         "optionB": {
-          "title": "Option B: Qdrant + OpenAI-Compatible Embedding API"
+          "title": "Option B: Qdrant + Ollama"
+        },
+        "optionC": {
+          "title": "Option C: Qdrant + hosted OpenAI-compatible API"
         },
         "env": {
           "title": "Environment Variables",
@@ -165,6 +189,13 @@
       "claudeMac": {
         "title": "Claude Desktop (macOS)",
         "path": "Configuration file path:"
+      },
+      "opencode": {
+        "title": "OpenCode",
+        "description": "Create or edit",
+        "description2": "in project root, or globally at",
+        "note": "Note:",
+        "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>."
       }
     },
     "step3": {

package/docs/i18n/ja.json

@@ -14,14 +14,14 @@
   "hero": {
     "title": "🚀 MCP Probe Kit",
     "subtitle": "AI開発強化ツールキット · ドキュメントセンター",
-    "version": "v3.0.18",
+    "version": "v3.0.19",
     "quickStart": "クイックスタート",
     "visitMainSite": "ByteZoneXを訪問"
   },
   "sections": {
     "quickStart": {
       "title": "クイックスタート",
-      "description": "5分でMCP Probe Kit v3.0.18を始める",
+      "description": "5分でMCP Probe Kit v3.0.19を始める",
       "installConfig": "インストールと設定"
     },
     "tools": {
@@ -165,6 +165,13 @@
       "claudeMac": {
         "title": "Claude Desktop (macOS)",
         "path": "設定ファイルパス："
+      },
+      "opencode": {
+        "title": "OpenCode",
+        "description": "プロジェクトルートに作成・編集",
+        "description2": "、またはグローバルパス：",
+        "note": "注意：",
+        "noteText": "OpenCode は <code>\"environment\"</code>（<code>\"env\"</code> ではありません）で環境変数を指定し、<code>\"mcp\"</code>（<code>\"mcpServers\"</code> ではありません）、<code>\"command\"</code> は配列で <code>\"type\": \"local\"</code> が必須です。詳しくは <a href=\"https://opencode.ai/docs/mcp\" target=\"_blank\" rel=\"noopener\" class=\"text-primary hover:underline\">OpenCode MCP ドキュメント</a> を参照。"
       }
     },
     "step3": {

package/docs/i18n/ko.json

@@ -14,14 +14,14 @@
   "hero": {
     "title": "🚀 MCP Probe Kit",
     "subtitle": "AI 개발 강화 툴킷 · 문서 센터",
-    "version": "v3.0.18",
+    "version": "v3.0.19",
     "quickStart": "빠른 시작",
     "visitMainSite": "ByteZoneX 방문"
   },
   "sections": {
     "quickStart": {
       "title": "빠른 시작",
-      "description": "5분 안에 MCP Probe Kit v3.0.18 시작하기",
+      "description": "5분 안에 MCP Probe Kit v3.0.19 시작하기",
       "installConfig": "설치 및 구성"
     },
     "tools": {
@@ -165,6 +165,13 @@
       "claudeMac": {
         "title": "Claude Desktop (macOS)",
         "path": "구성 파일 경로："
+      },
+      "opencode": {
+        "title": "OpenCode",
+        "description": "프로젝트 루트에서 생성 또는 편집",
+        "description2": ", 또는 전역 경로：",
+        "note": "참고：",
+        "noteText": "OpenCode는 <code>\"environment\"</code>（<code>\"env\"</code>가 아님）로 환경 변수를 지정하고, <code>\"mcp\"</code>（<code>\"mcpServers\"</code>가 아님）, <code>\"command\"</code>는 배열이며 <code>\"type\": \"local\"</code>이 필수입니다. 자세한 내용은 <a href=\"https://opencode.ai/docs/mcp\" target=\"_blank\" rel=\"noopener\" class=\"text-primary hover:underline\">OpenCode MCP 문서</a>를 참조하세요."
       }
     },
     "step3": {

package/docs/i18n/zh-CN.json

@@ -14,14 +14,14 @@
   "hero": {
     "title": "🚀 MCP Probe Kit",
     "subtitle": "AI 开发增强工具集 · 文档中心",
-    "version": "v3.0.18",
+    "version": "v3.0.19",
     "quickStart": "快速开始",
     "visitMainSite": "访问主站 ByteZoneX"
   },
   "sections": {
     "quickStart": {
       "title": "快速开始",
-      "description": "5 分钟快速上手 MCP Probe Kit v3.0.18",
+      "description": "5 分钟快速上手 MCP Probe Kit v3.0.19",
       "installConfig": "安装配置"
     },
     "tools": {
@@ -63,7 +63,7 @@
   },
   "gettingStarted": {
     "title": "安装配置",
-    "subtitle": "5 分钟快速上手 MCP Probe Kit v3.0.18，支持 Cursor、Cline 和 Claude Desktop",
+    "subtitle": "5 分钟快速上手 MCP Probe Kit v3.0.19，支持 Cursor、Cline 和 Claude Desktop",
     "breadcrumb": {
       "home": "文档首页",
       "quickStart": "快速开始",
@@ -91,11 +91,35 @@
         "title": "记忆系统安装配置（Qdrant + Embedding）",
         "descriptionPrefix": "如果你要使用",
         "descriptionSuffix": "，需要同时配置向量数据库和 embedding 服务。",
+        "guideLink": "扩展说明（排错、性能）：",
+        "guidePath": "docs/memory-local-setup.zh-CN.md",
+        "deployIntro": "按下面创建两个目录、复制 compose 与 .env、启动服务，再配置 MCP。无需安装 Ollama。",
+        "portTitle": "端口",
+        "layoutTitle": "0. 目录结构",
+        "layoutText": "在任意路径创建两个文件夹（示例 ~/mcp-memory/）：",
+        "qdrantTitle": "1. Qdrant（向量库，端口 50008）",
+        "qdrantCompose": "qdrant/docker-compose.yml",
+        "qdrantEnv": "qdrant/.env",
+        "qdrantDeploy": "启动 Qdrant",
+        "qdrantVerify": "验证 Qdrant",
+        "qdrantNote": "开启 API Key 后，请求须带 api-key 头。面板：http://127.0.0.1:50008/dashboard",
+        "nomicTitle": "2. Nomic Embed / Infinity（向量生成，端口 50012）",
+        "nomicCompose": "nomic-embed/docker-compose.yml",
+        "nomicEnv": "nomic-embed/.env",
+        "nomicDeploy": "启动 Embedding 服务",
+        "nomicVerify": "验证 Embedding",
+        "nomicNote": "首次启动会下载模型（约 2–5 分钟）。路径为 POST /embeddings（不是 /v1/embeddings），向量维度 768。",
+        "mcpTitle": "3. MCP 客户端配置",
+        "mcpNote": "密钥与 qdrant/.env、nomic-embed/.env 保持一致。保存后请完全重启 Cursor。",
+        "alternativesTitle": "其它 Embedding 方案",
         "optionA": {
-          "title": "方案 A：Qdrant + Ollama（默认推荐）"
+          "title": "推荐方案（见上文步骤）"
         },
         "optionB": {
-          "title": "方案 B：Qdrant + OpenAI-Compatible Embedding API"
+          "title": "方案 B：Qdrant + Ollama"
+        },
+        "optionC": {
+          "title": "方案 C：Qdrant + 云端 OpenAI 兼容 Embedding API"
         },
         "env": {
           "title": "环境变量说明",
@@ -165,6 +189,13 @@
       "claudeMac": {
         "title": "Claude Desktop (macOS)",
         "path": "配置文件路径："
+      },
+      "opencode": {
+        "title": "OpenCode",
+        "description": "在项目根目录创建或编辑",
+        "description2": "，或全局路径：",
+        "note": "注意：",
+        "noteText": "OpenCode 使用 <code>\"environment\"</code>（非 <code>\"env\"</code>）配置环境变量，使用 <code>\"mcp\"</code>（非 <code>\"mcpServers\"</code>），<code>\"command\"</code> 为数组且需指定 <code>\"type\": \"local\"</code>。详见 <a href=\"https://opencode.ai/docs/mcp\" target=\"_blank\" rel=\"noopener\" class=\"text-primary hover:underline\">OpenCode MCP 文档</a>。"
       }
     },
     "step3": {

package/docs/memory-local-setup.md

@@ -0,0 +1,314 @@
+# Local Memory Stack (Qdrant + Nomic Embed)
+
+This guide documents a **lightweight local setup** for mcp-probe-kit memory tools (`memorize_asset`, `read_memory_asset`, `scan_and_extract_patterns`):
+
+- **Qdrant** — vector database (port `50008`)
+- **Infinity (nomic-embed)** — embedding API (port `50012`), replaces Ollama for users who want a smaller footprint
+
+Both services are typically deployed with Docker Compose under a shared `docker-start` layout. Ports use the `500xx` convention to avoid conflicts.
+
+| Service | Host port | Container port | Purpose |
+|---------|-----------|----------------|---------|
+| Qdrant HTTP | `50008` | `6333` | REST API, dashboard |
+| Qdrant gRPC | `50009` | `6334` | gRPC API |
+| Nomic Embed (Infinity) | `50012` | `7997` | OpenAI-compatible embeddings |
+
+---
+
+## 1. Qdrant
+
+### Service info
+
+| Item | Value |
+|------|-------|
+| Image | `qdrant/qdrant:latest` |
+| Container name | `qdrant` |
+| HTTP | `http://127.0.0.1:50008` |
+| gRPC | `127.0.0.1:50009` |
+| Data | `./data` → `/qdrant/storage` |
+| Snapshots | `./snapshots` → `/qdrant/snapshots` |
+| Auth | `QDRANT_API_KEY` in `.env` (header `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: cp .env.example .env
+# generate key: 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
+```
+
+### First deploy
+
+```powershell
+cd qdrant
+copy .env.example .env
+# Edit .env — set a long random QDRANT_API_KEY
+docker compose up -d
+```
+
+### Verify
+
+```bash
+# Health / collections (requires api-key when API_KEY is enabled)
+curl http://127.0.0.1:50008/collections \
+  -H "api-key: YOUR_QDRANT_API_KEY"
+
+# Web UI (enter the same key in the dashboard)
+# http://127.0.0.1:50008/dashboard
+```
+
+### Common commands
+
+```powershell
+docker compose up -d          # start
+docker compose down           # stop
+docker compose logs -f qdrant # logs
+docker compose restart qdrant # restart
+```
+
+### Notes
+
+- After enabling `QDRANT__SERVICE__API_KEY`, **all** REST/gRPC requests must include header `api-key`.
+- mcp-probe-kit sends this via `MEMORY_QDRANT_API_KEY`.
+- Collection `mcp_probe_memory` is created automatically on first `memorize_asset` write (Cosine distance; vector size inferred from the first embedding).
+
+---
+
+## 2. Nomic Embed (Infinity)
+
+Lightweight embedding server based on [Infinity](https://github.com/michaelfeil/infinity). Model: `nomic-ai/nomic-embed-text-v1.5` (768 dimensions). No Ollama required.
+
+### Service info
+
+| Item | Value |
+|------|-------|
+| Image | `michaelf34/infinity:0.0.70` |
+| Container name | `nomic-embed` |
+| Host port | `50012` → container `7997` |
+| Model | `nomic-ai/nomic-embed-text-v1.5` |
+| Vector dim | **768** |
+| Engine | `torch` (CPU if no GPU) |
+| Auth | `INFINITY_API_KEY` → `Authorization: Bearer <key>` |
+| Model cache | Docker volume `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:
+```
+
+### `.env.example`
+
+```bash
+INFINITY_API_KEY=change-me-to-a-long-random-string
+```
+
+### First deploy
+
+```powershell
+cd nomic-embed
+copy .env.example .env
+# Edit .env — set INFINITY_API_KEY (long random string)
+docker compose up -d
+docker logs -f nomic-embed   # wait for "ready to batch requests"
+```
+
+First start downloads the HuggingFace model (**~2–5 minutes** cold start).
+
+### Verify
+
+```bash
+curl http://127.0.0.1:50012/health
+
+curl http://127.0.0.1:50012/models \
+  -H "Authorization: Bearer YOUR_INFINITY_API_KEY"
+
+# Important: path is /embeddings — NOT /v1/embeddings
+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"}'
+```
+
+Response: `data[0].embedding` is a **768**-float array.
+
+Swagger: `http://127.0.0.1:50012/docs`
+
+### Performance (CPU, indicative)
+
+| Scenario | ~Latency |
+|----------|----------|
+| Single short text (warm) | 30–50 ms |
+| First request | ~150 ms |
+| Batch 8 | ~150 ms |
+| Resident memory | ~1 GB |
+
+Suitable for MCP memory and occasional writes; not for high-concurrency bulk indexing.
+
+---
+
+## 3. mcp-probe-kit MCP configuration
+
+**Recommended:** Qdrant on `50008` + Infinity on `50012` with `openai-compatible` provider.
+
+```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": "YOUR_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": "YOUR_INFINITY_API_KEY",
+        "MEMORY_SEARCH_LIMIT": "3",
+        "MEMORY_SUMMARY_MAX_CHARS": "280"
+      }
+    }
+  }
+}
+```
+
+Claude Code: put the same keys under `mcpServers.mcp-probe-kit.env` in `.mcp.json`.
+
+After changing env, **fully restart** your MCP client (e.g. quit and reopen Cursor).
+
+### Environment variable reference
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MEMORY_QDRANT_URL` | Yes (read/write) | Qdrant base URL, e.g. `http://127.0.0.1:50008` |
+| `MEMORY_QDRANT_API_KEY` | If Qdrant auth enabled | Sent as `api-key` header |
+| `MEMORY_QDRANT_COLLECTION` | No | Default `mcp_probe_memory` |
+| `MEMORY_EMBEDDING_URL` | Yes (write/search) | e.g. `http://127.0.0.1:50012/embeddings` |
+| `MEMORY_EMBEDDING_MODEL` | Yes (write/search) | `nomic-ai/nomic-embed-text-v1.5` |
+| `MEMORY_EMBEDDING_PROVIDER` | No | Must be `openai-compatible` for Infinity |
+| `MEMORY_EMBEDDING_API_KEY` | Yes for Infinity | Bearer token = `INFINITY_API_KEY` |
+| `MEMORY_SEARCH_LIMIT` | No | Default `3` |
+| `MEMORY_SUMMARY_MAX_CHARS` | No | Default `280` |
+
+---
+
+## 4. End-to-end smoke test
+
+```bash
+# 1) Qdrant
+curl -s http://127.0.0.1:50008/collections -H "api-key: YOUR_QDRANT_API_KEY"
+
+# 2) Embedding
+curl -s -X POST 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":"mcp-probe-kit test"}' \
+  | jq '.data[0].embedding | length'
+# Expected: 768
+```
+
+Then in the IDE, call `memorize_asset` once and `read_memory_asset` / semantic search via orchestration tools.
+
+---
+
+## 5. Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| Qdrant `401` | Set `MEMORY_QDRANT_API_KEY` to match `qdrant/.env` |
+| Embedding `401` | Use `Authorization: Bearer` + correct `INFINITY_API_KEY` |
+| Embedding `404` | URL must be `http://127.0.0.1:50012/embeddings`, not `/v1/embeddings` |
+| `nomic-embed` health stuck on `starting` | First model download; check `docker logs nomic-embed` |
+| Log `No CUDA runtime` | Normal on CPU |
+| Dimension mismatch in Qdrant | Collection was created with another model; delete collection or use a new `MEMORY_QDRANT_COLLECTION` name |
+| Memory write disabled | Ensure all three are set: `MEMORY_QDRANT_URL`, `MEMORY_EMBEDDING_URL`, `MEMORY_EMBEDDING_MODEL` |
+
+---
+
+## 6. Alternatives
+
+| Stack | When to use |
+|-------|-------------|
+| **Qdrant + Infinity (this guide)** | Default for local dev; lighter than Ollama |
+| Qdrant + Ollama | If you already run Ollama for chat models |
+| Qdrant + hosted OpenAI-compatible API | No local embedding container |
+
+See also [README — Optional Memory System Setup](../README.md#optional-memory-system-setup).
+
+---
+
+**中文说明**: 同内容中文版见 [memory-local-setup.zh-CN.md](./memory-local-setup.zh-CN.md).