qdrant-memory-mcp 0.1.0__tar.gz

qdrant_memory_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kang Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qdrant_memory_mcp-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include server.json runtime-source.json README.zh-CN.md
+recursive-include schemas *.json
+include schemas/LICENSE schemas/README.md
+recursive-include scripts *.py
+recursive-include tests *.py
+recursive-include docs *.md

qdrant_memory_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: qdrant-memory-mcp
+Version: 0.1.0
+Summary: Metadata-only stdio MCP distribution of the Qdrant Memory Runtime
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cnkang/qdrant-memory-mcp
+Project-URL: Repository, https://github.com/cnkang/qdrant-memory-mcp
+Project-URL: Issues, https://github.com/cnkang/qdrant-memory-mcp/issues
+Project-URL: Changelog, https://github.com/cnkang/qdrant-memory-mcp/blob/main/CHANGELOG.md
+Project-URL: Runtime, https://github.com/cnkang/hermes-plugin-qdrant-memory
+Project-URL: Skill, https://github.com/cnkang/skills/tree/main/qdrant-memory
+Keywords: mcp,memory,qdrant,agents
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hermes-plugin-qdrant-memory[mcp]==0.2.0
+Dynamic: license-file
+
+# Qdrant Memory MCP
+
+<!-- mcp-name: io.github.cnkang/qdrant-memory -->
+
+[简体中文](README.zh-CN.md)
+
+Persistent, scoped memory for AI agents through four explicit **stdio MCP** tools.
+This repository distributes the existing [Python Runtime](https://github.com/cnkang/hermes-plugin-qdrant-memory).
+Its metadata-only wheel contains no Python business implementation. The console
+script points directly to `qdrant_memory.standalone:main` and depends on
+`hermes-plugin-qdrant-memory[mcp]==0.2.0`.
+
+**Versions:** MCP distribution 0.1.0 depends on Runtime 0.2.0. Release artifacts
+are available through the [distribution PyPI page](https://pypi.org/project/qdrant-memory-mcp/)
+and [Runtime PyPI page](https://pypi.org/project/hermes-plugin-qdrant-memory/).
+See [release checklist](docs/publishing.md) for the publishing sequence.
+
+Runtime, [optional Agent Skill](https://github.com/cnkang/skills/tree/main/qdrant-memory)
+and MCP distribution versions are independent. The Skill is usage guidance,
+not a runtime dependency. Hermes retains its native MemoryProvider, automatic
+extraction and prefetch. Ordinary MCP performs only explicitly requested memory
+operations; it does not automatically extract every conversation turn.
+
+## Install and initialize
+
+Requires Python 3.11+ and either [uv](https://docs.astral.sh/uv/) or a Python
+virtual environment. You must configure storage and an embedding service.
+For the example below, run Ollama and install `qwen3-embedding:4b` yourself.
+
+Create an operator-owned profile directory and save `qdrant-memory.json` inside:
+
+```json
+{
+  "schema_version": 1,
+  "scope": {"user_id": "my-user", "agent_id": "my-agent"},
+  "qdrant": {"mode": "embedded", "collection": "qdrant_memory"},
+  "embedding": {
+    "mode": "plugin", "provider": "ollama", "model": "qwen3-embedding:4b",
+    "base_url": "http://127.0.0.1:11434", "dimensions": 2560, "distance": "Cosine"
+  }
+}
+```
+
+Initialize, then launch (replace `/path/to/profile` with your absolute path):
+
+```bash
+uvx --from qdrant-memory-mcp==0.1.0 qdrant-memory-mcp --home /path/to/profile init
+uvx --from qdrant-memory-mcp==0.1.0 qdrant-memory-mcp --home /path/to/profile mcp
+```
+
+The command without `--home` uses `~/.qdrant-memory`, independent of Hermes.
+Configure and initialize that directory before letting a Registry client launch
+`uvx qdrant-memory-mcp==0.1.0 mcp`. The executable name matches the package name;
+the Registry's positional `mcp` selects protocol mode. Its optional named
+`--home` precedes `mcp` when a client supplies a custom profile.
+
+Alternatively:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install qdrant-memory-mcp==0.1.0
+.venv/bin/qdrant-memory-mcp --home /path/to/profile init
+.venv/bin/qdrant-memory-mcp --home /path/to/profile mcp
+```
+
+On Windows use `.venv\Scripts\python.exe` and
+`.venv\Scripts\qdrant-memory-mcp.exe`.
+
+Qdrant embedded, self-hosted server and Cloud, plus Ollama and OpenAI-compatible
+embeddings, are configured in the Runtime's [configuration reference](https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/docs/configuration.md).
+Keep credentials in operator environment variables (`QDRANT_API_KEY`,
+`EMBEDDING_API_KEY`, or configured names); never commit their values.
+Initialization against an existing collection requires explicit operator choice;
+do not use a production destination for a first test.
+
+## Connect a client
+
+Codex `config.toml` example:
+
+```toml
+[mcp_servers.qdrant_memory]
+command = "uvx"
+args = ["--from", "qdrant-memory-mcp==0.1.0", "qdrant-memory-mcp", "--home", "/path/to/profile", "mcp"]
+```
+
+OpenCode `opencode.json` example:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "qdrant_memory": {
+      "type": "local",
+      "command": ["uvx", "--from", "qdrant-memory-mcp==0.1.0", "qdrant-memory-mcp", "--home", "/path/to/profile", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Pi needs a separately installed MCP client/extension. In that extension, use
+`command: uvx` and the same argument list. No built-in Pi MCP support or universal
+extension config format is claimed. These are configuration examples; this
+distribution's acceptance tests use the official Python MCP SDK, not live agent
+applications. See the Runtime's [client evidence and limits](https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/docs/mcp.md).
+
+## Tools and boundaries
+
+| Tool | Input | Result |
+|---|---|---|
+| `qdrant_memory_search` | `query`, optional `category` | Scoped memories with IDs, scores and provenance |
+| `qdrant_memory_add` | `text` | Durable memory ID |
+| `qdrant_memory_update` | exact `id`, replacement `text` | Scoped replacement |
+| `qdrant_memory_delete` | exact `id` | Scoped deletion |
+
+Scope is fixed by the operator's profile (`user_id`, `agent_id`). Model inputs
+and MCP client identity cannot override it; knowing an ID does not grant access.
+Migration, export, reset and bulk deletion remain trusted operator CLI commands;
+see [standalone maintenance](https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/docs/standalone.md).
+No resources or prompts are advertised. This is a local subprocess, with no
+public HTTP/SSE listener or remote authentication service. Stdout is reserved
+for protocol messages, with sanitized diagnostics on stderr.
+
+Data flows from client → Runtime → embedding provider → Qdrant and the local
+SQLite ledger. With local Ollama and embedded Qdrant, memory processing stays
+local; cloud embedding receives memory/query text, and cloud Qdrant receives
+vectors and stored payloads. The client/model may also receive recalled text.
+The operator must authorize retention and access and protect the profile files.
+
+One writer lease coordinates a profile/destination. Do not overlap MCP, CLI
+or Hermes processes writing to it. Separate profiles or machines do not provide
+a distributed lock. This package does not support uncoordinated multiprocess
+writes, auto-extraction, an HTTP transport, or implicit credential discovery
+from Hermes. It preserves the Runtime's ledger, IDs and recovery semantics.
+
+## Verification and development
+
+CI builds wheel/sdist, checks metadata and ownership marker, and runs installed
+protocol tests with temporary profiles, embedded Qdrant and a deterministic
+loopback embedding fixture on Linux/macOS/Windows, Python 3.11 and 3.14.
+No test connects to personal Qdrant, Hermes profiles or memory data. These tests
+cover initialize, discovery, four tools, persistence, recovery, scope isolation,
+error redaction and protocol stdout. Provider/cloud compatibility evidence
+belongs to the [Runtime](https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/docs/validation.md).
+
+CI prefers the immutable Runtime PyPI release. Before Runtime 0.2.0 reaches PyPI,
+CI builds a wheel from an immutable candidate
+commit recorded in `runtime-source.json`. This is only a preparation fixture:
+published dependency metadata always uses the exact PyPI version. Release
+workflow acceptance requires installation from PyPI and never uses that fallback.
+
+See [CI and dependency maintenance](docs/ci.md), [publishing](docs/publishing.md), [architecture](docs/architecture.md), and
+the optional [Skill](https://github.com/cnkang/skills/tree/main/qdrant-memory).

qdrant_memory_mcp-0.1.0/README.md

@@ -0,0 +1,153 @@
+# Qdrant Memory MCP
+
+<!-- mcp-name: io.github.cnkang/qdrant-memory -->
+
+[简体中文](README.zh-CN.md)
+
+Persistent, scoped memory for AI agents through four explicit **stdio MCP** tools.
+This repository distributes the existing [Python Runtime](https://github.com/cnkang/hermes-plugin-qdrant-memory).
+Its metadata-only wheel contains no Python business implementation. The console
+script points directly to `qdrant_memory.standalone:main` and depends on
+`hermes-plugin-qdrant-memory[mcp]==0.2.0`.
+
+**Versions:** MCP distribution 0.1.0 depends on Runtime 0.2.0. Release artifacts
+are available through the [distribution PyPI page](https://pypi.org/project/qdrant-memory-mcp/)
+and [Runtime PyPI page](https://pypi.org/project/hermes-plugin-qdrant-memory/).
+See [release checklist](docs/publishing.md) for the publishing sequence.
+
+Runtime, [optional Agent Skill](https://github.com/cnkang/skills/tree/main/qdrant-memory)
+and MCP distribution versions are independent. The Skill is usage guidance,
+not a runtime dependency. Hermes retains its native MemoryProvider, automatic
+extraction and prefetch. Ordinary MCP performs only explicitly requested memory
+operations; it does not automatically extract every conversation turn.
+
+## Install and initialize
+
+Requires Python 3.11+ and either [uv](https://docs.astral.sh/uv/) or a Python
+virtual environment. You must configure storage and an embedding service.
+For the example below, run Ollama and install `qwen3-embedding:4b` yourself.
+
+Create an operator-owned profile directory and save `qdrant-memory.json` inside:
+
+```json
+{
+  "schema_version": 1,
+  "scope": {"user_id": "my-user", "agent_id": "my-agent"},
+  "qdrant": {"mode": "embedded", "collection": "qdrant_memory"},
+  "embedding": {
+    "mode": "plugin", "provider": "ollama", "model": "qwen3-embedding:4b",
+    "base_url": "http://127.0.0.1:11434", "dimensions": 2560, "distance": "Cosine"
+  }
+}
+```
+
+Initialize, then launch (replace `/path/to/profile` with your absolute path):
+
+```bash
+uvx --from qdrant-memory-mcp==0.1.0 qdrant-memory-mcp --home /path/to/profile init
+uvx --from qdrant-memory-mcp==0.1.0 qdrant-memory-mcp --home /path/to/profile mcp
+```
+
+The command without `--home` uses `~/.qdrant-memory`, independent of Hermes.
+Configure and initialize that directory before letting a Registry client launch
+`uvx qdrant-memory-mcp==0.1.0 mcp`. The executable name matches the package name;
+the Registry's positional `mcp` selects protocol mode. Its optional named
+`--home` precedes `mcp` when a client supplies a custom profile.
+
+Alternatively:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install qdrant-memory-mcp==0.1.0
+.venv/bin/qdrant-memory-mcp --home /path/to/profile init
+.venv/bin/qdrant-memory-mcp --home /path/to/profile mcp
+```
+
+On Windows use `.venv\Scripts\python.exe` and
+`.venv\Scripts\qdrant-memory-mcp.exe`.
+
+Qdrant embedded, self-hosted server and Cloud, plus Ollama and OpenAI-compatible
+embeddings, are configured in the Runtime's [configuration reference](https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/docs/configuration.md).
+Keep credentials in operator environment variables (`QDRANT_API_KEY`,
+`EMBEDDING_API_KEY`, or configured names); never commit their values.
+Initialization against an existing collection requires explicit operator choice;
+do not use a production destination for a first test.
+
+## Connect a client
+
+Codex `config.toml` example:
+
+```toml
+[mcp_servers.qdrant_memory]
+command = "uvx"
+args = ["--from", "qdrant-memory-mcp==0.1.0", "qdrant-memory-mcp", "--home", "/path/to/profile", "mcp"]
+```
+
+OpenCode `opencode.json` example:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "qdrant_memory": {
+      "type": "local",
+      "command": ["uvx", "--from", "qdrant-memory-mcp==0.1.0", "qdrant-memory-mcp", "--home", "/path/to/profile", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Pi needs a separately installed MCP client/extension. In that extension, use
+`command: uvx` and the same argument list. No built-in Pi MCP support or universal
+extension config format is claimed. These are configuration examples; this
+distribution's acceptance tests use the official Python MCP SDK, not live agent
+applications. See the Runtime's [client evidence and limits](https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/docs/mcp.md).
+
+## Tools and boundaries
+
+| Tool | Input | Result |
+|---|---|---|
+| `qdrant_memory_search` | `query`, optional `category` | Scoped memories with IDs, scores and provenance |
+| `qdrant_memory_add` | `text` | Durable memory ID |
+| `qdrant_memory_update` | exact `id`, replacement `text` | Scoped replacement |
+| `qdrant_memory_delete` | exact `id` | Scoped deletion |
+
+Scope is fixed by the operator's profile (`user_id`, `agent_id`). Model inputs
+and MCP client identity cannot override it; knowing an ID does not grant access.
+Migration, export, reset and bulk deletion remain trusted operator CLI commands;
+see [standalone maintenance](https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/docs/standalone.md).
+No resources or prompts are advertised. This is a local subprocess, with no
+public HTTP/SSE listener or remote authentication service. Stdout is reserved
+for protocol messages, with sanitized diagnostics on stderr.
+
+Data flows from client → Runtime → embedding provider → Qdrant and the local
+SQLite ledger. With local Ollama and embedded Qdrant, memory processing stays
+local; cloud embedding receives memory/query text, and cloud Qdrant receives
+vectors and stored payloads. The client/model may also receive recalled text.
+The operator must authorize retention and access and protect the profile files.
+
+One writer lease coordinates a profile/destination. Do not overlap MCP, CLI
+or Hermes processes writing to it. Separate profiles or machines do not provide
+a distributed lock. This package does not support uncoordinated multiprocess
+writes, auto-extraction, an HTTP transport, or implicit credential discovery
+from Hermes. It preserves the Runtime's ledger, IDs and recovery semantics.
+
+## Verification and development
+
+CI builds wheel/sdist, checks metadata and ownership marker, and runs installed
+protocol tests with temporary profiles, embedded Qdrant and a deterministic
+loopback embedding fixture on Linux/macOS/Windows, Python 3.11 and 3.14.
+No test connects to personal Qdrant, Hermes profiles or memory data. These tests
+cover initialize, discovery, four tools, persistence, recovery, scope isolation,
+error redaction and protocol stdout. Provider/cloud compatibility evidence
+belongs to the [Runtime](https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/docs/validation.md).
+
+CI prefers the immutable Runtime PyPI release. Before Runtime 0.2.0 reaches PyPI,
+CI builds a wheel from an immutable candidate
+commit recorded in `runtime-source.json`. This is only a preparation fixture:
+published dependency metadata always uses the exact PyPI version. Release
+workflow acceptance requires installation from PyPI and never uses that fallback.
+
+See [CI and dependency maintenance](docs/ci.md), [publishing](docs/publishing.md), [architecture](docs/architecture.md), and
+the optional [Skill](https://github.com/cnkang/skills/tree/main/qdrant-memory).

qdrant_memory_mcp-0.1.0/README.zh-CN.md

@@ -0,0 +1,117 @@
+# Qdrant Memory MCP
+
+这是 Qdrant Memory 的独立 PyPI 包装与 MCP Registry 分发仓库。
+所有业务逻辑来自唯一的 [Python Runtime](https://github.com/cnkang/hermes-plugin-qdrant-memory)，
+本仓库不复制 Runtime 或 [Agent Skill](https://github.com/cnkang/skills/tree/main/qdrant-memory)。
+`qdrant-memory-mcp` 直接引用 `qdrant_memory.standalone:main`，固定依赖
+`hermes-plugin-qdrant-memory[mcp]==0.2.0`，不需要安装 Hermes。
+
+**版本：** 分发 0.1.0 固定依赖 Runtime 0.2.0，发行产物见
+[分发 PyPI 页面](https://pypi.org/project/qdrant-memory-mcp/) 和
+[Runtime PyPI 页面](https://pypi.org/project/hermes-plugin-qdrant-memory/)。三个仓库的版本独立管理。
+Skill 仅提供可选指导，不是运行依赖。Hermes 的自动提取和 prefetch 仍属于
+原生集成；普通 MCP 仅执行明确请求的记忆操作，不自动提取每轮对话。
+
+## 安装与配置
+
+需要 Python 3.11+。用户必须自行配置 Qdrant 与 Embedding。
+在可信 profile 目录内创建 `qdrant-memory.json`：
+
+```json
+{
+  "schema_version": 1,
+  "scope": {"user_id": "my-user", "agent_id": "my-agent"},
+  "qdrant": {"mode": "embedded", "collection": "qdrant_memory"},
+  "embedding": {
+    "mode": "plugin", "provider": "ollama", "model": "qwen3-embedding:4b",
+    "base_url": "http://127.0.0.1:11434", "dimensions": 2560, "distance": "Cosine"
+  }
+}
+```
+
+示例要求自己启动 Ollama 并安装对应模型。将路径替换为自己的绝对路径：
+
+```bash
+uvx --from qdrant-memory-mcp==0.1.0 qdrant-memory-mcp --home /path/to/profile init
+uvx --from qdrant-memory-mcp==0.1.0 qdrant-memory-mcp --home /path/to/profile mcp
+```
+
+省略 `--home` 时使用 `~/.qdrant-memory`，与 Hermes profile 独立。
+Registry 默认运行 `uvx qdrant-memory-mcp==0.1.0 mcp`，应先配置、初始化默认目录。
+客户端可通过 `mcp` 前面的可选 `--home` 参数选择自定义 profile。
+
+也可以使用虚拟环境：
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install qdrant-memory-mcp==0.1.0
+.venv/bin/qdrant-memory-mcp --home /path/to/profile init
+.venv/bin/qdrant-memory-mcp --home /path/to/profile mcp
+```
+
+Windows 使用 `.venv\Scripts\python.exe` 和 `.venv\Scripts\qdrant-memory-mcp.exe`。
+Qdrant Embedded、Server、Cloud 和 OpenAI-compatible Embedding 的配置见
+[原始配置文档](https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/docs/configuration.md)。
+凭据由可信进程环境提供（如 `QDRANT_API_KEY`、`EMBEDDING_API_KEY`），不要提交密钥。
+首次测试请使用独立的临时存储，现有 collection 的复用必须由操作者明确选择。
+
+## 客户端示例
+
+Codex `config.toml`：
+
+```toml
+[mcp_servers.qdrant_memory]
+command = "uvx"
+args = ["--from", "qdrant-memory-mcp==0.1.0", "qdrant-memory-mcp", "--home", "/path/to/profile", "mcp"]
+```
+
+OpenCode `opencode.json`：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "qdrant_memory": {
+      "type": "local",
+      "command": ["uvx", "--from", "qdrant-memory-mcp==0.1.0", "qdrant-memory-mcp", "--home", "/path/to/profile", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Pi 需要另外安装 MCP 客户端扩展；将上述 command/args 填入该扩展支持的配置。
+本仓库不声称 Pi 内置 MCP，也不声称通用扩展配置格式。
+这些是配置示例；分发测试使用官方 Python MCP SDK，不把未实测的 Agent 应用列为已验证。
+
+## 工具、安全与限制
+
+| 工具 | 输入 | 用途 |
+|---|---|---|
+| `qdrant_memory_search` | `query`，可选 `category` | 作用域内检索，返回 ID、分数、来源 |
+| `qdrant_memory_add` | `text` | 持久化显式记忆 |
+| `qdrant_memory_update` | 精确 `id`、替换 `text` | 经过授权检查后更新 |
+| `qdrant_memory_delete` | 精确 `id` | 经过授权检查后删除 |
+
+profile 固定 user/agent scope；模型参数、客户端身份不能覆盖它，知道 ID 不等于获得权限。
+迁移、导出、重置、批量删除仍是可信操作者 CLI 命令，见
+[维护文档](https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/docs/standalone.md)。
+
+MCP 使用本地 **stdio**，不提供公网 HTTP/SSE 服务、远程认证、resources 或 prompts。
+stdout 只承载协议，错误经过脱敏。不支持无协调的多进程写入；一个 MCP 进程会
+持有 profile/destination 的 writer lease。不同 profile 或机器不共享分布式锁。
+
+数据流为客户端 → Runtime → Embedding → Qdrant 与本地 SQLite Ledger。
+本地模型与本地 Qdrant 可实现本地数据处理；云 Embedding 会接收记忆/查询文本，
+云 Qdrant 会接收向量和 payload，客户端或模型也会接收召回文本。
+操作者需要管理保留策略、权限与 profile 文件。
+
+CI 对 Linux/macOS/Windows、Python 3.11/3.14 的 wheel/sdist 安装运行真实协议测试，
+覆盖初始化、工具发现、四项操作、重启持久化与恢复、scope 拒绝、错误脱敏、stdout。
+使用临时目录、Embedded Qdrant、确定性本地 HTTP Embedding fixture，
+不访问私人 Qdrant、Hermes profile 或个人记忆。云服务兼容性参见 Runtime 的验证证据。
+
+CI 优先使用正式 PyPI Runtime。Runtime 尚未上 PyPI 时，准备阶段 CI 使用 `runtime-source.json` 固定的候选 commit
+构建本地 wheel；正式包元数据始终依赖固定 PyPI 版本，发布流程禁止这种回退。
+详见 [英文说明](README.md)、[发布清单](docs/publishing.md) 与
+[Runtime 验证](https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/docs/validation.md)。

qdrant_memory_mcp-0.1.0/docs/architecture.md

@@ -0,0 +1,19 @@
+# Distribution boundary
+
+`pyproject.toml` declares no packages or Python modules. Its console script
+references `qdrant_memory.standalone:main`, supplied by the exact upstream
+dependency `hermes-plugin-qdrant-memory[mcp]==0.2.0`. A wheel contains only
+dist-info metadata and the license. There is no shim or business implementation.
+
+Runtime source: https://github.com/cnkang/hermes-plugin-qdrant-memory
+
+Skill source: https://github.com/cnkang/skills/tree/main/qdrant-memory
+
+Version lines are independent: Runtime 0.2.0, Skill's own metadata version,
+distribution 0.1.0. Runtime source and schema snapshots used for preparation
+are immutable; publication requires the Runtime version to exist on PyPI.
+
+The only Python files in this repository are release/verification scripts and
+tests. They never implement Qdrant, embedding, ledger or MCP server behavior.
+The fixture responds to embedding HTTP requests exclusively in tests. Its
+temporary profiles never reference personal data or production services.

qdrant_memory_mcp-0.1.0/docs/ci.md

@@ -0,0 +1,27 @@
+# GitHub checks and dependency maintenance
+
+- Distribution CI builds metadata-only artifacts and verifies installed MCP
+  protocol behavior on Linux, macOS and Windows (Python 3.11/3.14).
+- Repository quality runs Ruff on release scripts/tests and actionlint on every
+  workflow, including shell steps. actionlint's archive is SHA256 verified.
+- CodeQL analyzes Python and GitHub Actions with `security-extended` queries
+  on PRs, main pushes and every Monday. The paired init/analyze actions use the
+  same immutable commit.
+- Dependency review blocks PRs that introduce high or critical dependency
+  vulnerabilities. It uses read-only access and does not post PR comments.
+- Dependabot checks pip manifests and GitHub Actions each Monday at 09:00
+  Asia/Singapore, grouping updates by ecosystem. Updates remain reviewed PRs;
+  there is no automatic merge or publication.
+
+Actions use immutable commit pins. Dependabot updates both occurrences of the
+CodeQL action together. Repository Dependabot security updates, secret scanning
+and push protection are enabled; no additional service token is required.
+
+The unpublished Runtime candidate remains the exact `0.2.0` dependency. Once
+Runtime is on PyPI, its updates must also adjust compatibility expectations and
+the preparation fixture deliberately; a dependency-only PR cannot bypass the
+distribution's metadata/protocol checks. This repository scans distribution
+scripts and workflows; Runtime business-code scanning belongs to its upstream.
+
+Publishing remains tag-only behind the existing protected environments and
+first-publication confirmation. Adding checks does not trigger a release.

qdrant_memory_mcp-0.1.0/docs/publishing.md

@@ -0,0 +1,56 @@
+# First publication checklist
+
+No publishing tag or workflow dispatch is executed before the operator gives
+explicit confirmation for the first Runtime/PyPI/Registry public publication.
+
+1. Merge the Runtime release PR after all checks pass. Create Runtime tag v0.2.0
+   on the merged commit, only after publication confirmation.
+2. Configure PyPI pending Trusted Publishers (PyPI account step):
+   - `hermes-plugin-qdrant-memory`: owner `cnkang`, repository
+     `hermes-plugin-qdrant-memory`, workflow `publish.yml`, environment `pypi`.
+   - `qdrant-memory-mcp`: owner `cnkang`, repository `qdrant-memory-mcp`,
+     workflow `publish.yml`, environment `pypi`.
+3. Approve protected GitHub environments when prompted. A version tag must point
+   to a main-branch commit and match package metadata. Releases cannot overwrite
+   an existing version. First publish Runtime 0.2.0 and verify its PyPI artifacts.
+4. Run distribution acceptance in public dependency mode. Build/test wheel and
+   sdist from a new environment using only the exact Runtime PyPI release.
+5. Create distribution tag v0.1.0 after confirmation. Its workflow builds and
+   tests before protected PyPI publication, verifies public metadata, validates
+   with the official publisher, then uses `github-oidc` for Registry publication.
+6. Verify PyPI ownership marker and the public Registry entry
+   `io.github.cnkang/qdrant-memory` version 0.1.0. Remove candidate wording in
+   documentation only when publication is confirmed by public endpoints.
+
+The distribution workflow has a tag-only manual `registry_only` retry mode.
+It downloads and verifies already-published PyPI artifacts and tests them,
+then reruns Registry validation/publication; no PyPI upload occurs. Normal retries
+also reuse a verified existing PyPI version. A mismatching package dependency,
+entrypoint, ownership marker or Registry payload fails closed.
+
+GitHub environments have already been configured with required reviewer
+`cnkang` and tag-only `v*` deployment policies: Runtime `pypi`; distribution
+`pypi` and `mcp-registry`. These approvals are never bypassed automatically.
+The remaining external account step is registering both PyPI pending Trusted
+Publishers at https://pypi.org/manage/account/publishing/.
+
+Official references checked on 2026-10-13:
+
+- [Publishing quickstart](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx)
+- [Package types](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/package-types.mdx)
+- [server.json](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md)
+- [Official requirements](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/official-registry-requirements.md)
+- [GitHub Actions/OIDC](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/github-actions.mdx)
+
+The current schema is 2025-12-11. PyPI ownership verification checks the package
+description for `mcp-name: io.github.cnkang/qdrant-memory`. The CLI name matches
+the PyPI identifier so uvx can run it directly; `mcp` remains a required positional
+package argument and optional `--home` precedes it. Profile configuration carries
+model/dimensions/scope, so environment declarations alone cannot initialize a
+server. Secrets have no defaults or committed values.
+
+Official publisher release v1.8.1 lists `validate` in help but reports
+`Unknown command: validate`. Build the official CLI at fixed source commit
+`11b7b0e274d518b6f449c5ee3518a6151d9848b9` instead. Do not accept the old
+binary's misleading zero exit status as validation. The official validator uses
+the Registry validation endpoint; local vendored schema validation complements it.

qdrant_memory_mcp-0.1.0/docs/superpowers/plans/2026-10-13-distribution.md

@@ -0,0 +1,15 @@
+# Qdrant Memory MCP Distribution Implementation Plan
+
+**Goal:** Build, verify and push a metadata-only MCP distribution, then obtain the required first-publication confirmation.
+
+**Architecture:** The console script references the upstream standalone entrypoint directly. Pin Runtime 0.2.0; prepare its release in a separate upstream PR because PyPI currently has no runtime release. Skills remain in cnkang/skills.
+
+**Tech Stack:** setuptools, Python 3.11+, official MCP Python SDK, embedded Qdrant, GitHub Actions OIDC, official MCP publisher.
+
+- [ ] Upstream: update pyproject.toml, version.py and both plugin manifests to 0.2.0; add release notes and gated Trusted Publishing. Run all tests and fresh-wheel standalone acceptance. Push codex/pypi-runtime-release and open PR.
+- [ ] Distribution: add pyproject.toml with packages=[] and hermes-plugin-qdrant-memory[mcp]==0.2.0; add server.json using current 2025-12-11 schema and mcp positional argument. Verify wheel contains metadata only and README ownership marker survives build.
+- [ ] Protocol acceptance: use a temporary profile, loopback deterministic HTTP embedding fixture and SDK stdio client. Exercise initialize, tools/list, all CRUD operations, restart, user/agent scope rejection, sanitized errors and stdout framing.
+- [ ] CI: test installed wheel and sdist on Linux/macOS/Windows. Before Runtime PyPI release, bootstrap its exact reviewed commit into a local wheel; never place a Git dependency in published metadata. Release jobs must resolve Runtime from PyPI only.
+- [ ] Release: tag-only publication through protected pypi and mcp-registry environments. Verify existing PyPI version metadata and artifact hashes before skipping uploads; allow Registry-only retry without repeating upload. Pin official publisher source if release binary lacks validate.
+- [ ] Docs: English/Chinese usage, configuration, client examples, privacy and limitations; link upstream Runtime and Skill. Mark public installation pending until release.
+- [ ] Delivery: create public repository, push code, wait for exact-SHA CI, save execution report and a concrete publication checklist. Do not push a publishing tag or dispatch publishing before explicit confirmation.

qdrant_memory_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=77,<85"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qdrant-memory-mcp"
+version = "0.1.0"
+description = "Metadata-only stdio MCP distribution of the Qdrant Memory Runtime"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = ["hermes-plugin-qdrant-memory[mcp]==0.2.0"]
+keywords = ["mcp", "memory", "qdrant", "agents"]
+classifiers = ["Programming Language :: Python :: 3", "Operating System :: OS Independent"]
+
+[project.scripts]
+qdrant-memory-mcp = "qdrant_memory.standalone:main"
+
+[project.urls]
+Homepage = "https://github.com/cnkang/qdrant-memory-mcp"
+Repository = "https://github.com/cnkang/qdrant-memory-mcp"
+Issues = "https://github.com/cnkang/qdrant-memory-mcp/issues"
+Changelog = "https://github.com/cnkang/qdrant-memory-mcp/blob/main/CHANGELOG.md"
+Runtime = "https://github.com/cnkang/hermes-plugin-qdrant-memory"
+Skill = "https://github.com/cnkang/skills/tree/main/qdrant-memory"
+
+[tool.setuptools]
+packages = []
+py-modules = []
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]