chore: add MCP registry metadata

Author: ZengLiangYi

docs/MCP.md

@@ -16,13 +16,34 @@ The Core layer is the trusted boundary. Skills can provide guidance, but MCP/Cor
 
 ## Start the MCP Server
 
+Recommended for registry and zero-install setups:
+
+```bash
+npx -y chatcrystal mcp
+```
+
+If ChatCrystal is installed globally, you can also run:
+
 ```bash
 crystal mcp
 ```
 
 ChatCrystal MCP uses stdio transport. Configure it with `command` and `args`, not as an HTTP/SSE MCP URL.
 
-Example agent configuration:
+Recommended agent configuration:
+
+```json
+{
+  "mcpServers": {
+    "chatcrystal": {
+      "command": "npx",
+      "args": ["-y", "chatcrystal", "mcp"]
+    }
+  }
+}
+```
+
+Global install configuration:
 
 ```json
 {
@@ -35,7 +56,7 @@ Example agent configuration:
 }
 ```
 
-If a tool separately asks for an HTTP API endpoint, use `http://localhost:3721`. Do not use a bare `http://127.0.0.1` URL without a port because HTTP defaults to port 80.
+Local mode connects to or auto-starts ChatCrystal Core at `http://localhost:3721` and uses `~/.chatcrystal/data` by default. If a tool separately asks for an HTTP API endpoint, use `http://localhost:3721`. Do not use a bare `http://127.0.0.1` URL without a port because HTTP defaults to port 80.
 
 ### Cloud Mode
 
@@ -52,14 +73,14 @@ If a tool separately asks for an HTTP API endpoint, use `http://localhost:3721`.
 }
 ```
 
-You can also pass environment variables from the MCP client:
+You can also pass environment variables from the MCP client. Set `CHATCRYSTAL_BASE_URL` for a cloud or remote instance, and set `CHATCRYSTAL_API_TOKEN` when that instance requires authentication:
 
 ```json
 {
   "mcpServers": {
     "chatcrystal": {
-      "command": "crystal",
-      "args": ["mcp"],
+      "command": "npx",
+      "args": ["-y", "chatcrystal", "mcp"],
       "env": {
         "CHATCRYSTAL_BASE_URL": "https://chatcrystal.example.com",
         "CHATCRYSTAL_API_TOKEN": "your-long-token"
@@ -71,7 +92,7 @@ You can also pass environment variables from the MCP client:
 
 ## MCP Tools
 
-ChatCrystal exposes six MCP tools:
+ChatCrystal exposes seven MCP tools:
 
 | Tool | Purpose |
 |---|---|
@@ -80,6 +101,7 @@ ChatCrystal exposes six MCP tools:
 | `list_notes` | Browse notes with optional filters |
 | `get_relations` | Read related notes and relation metadata |
 | `recall_for_task` | Recall project-first memories before substantive work |
+| `validate_task_memory` | Preflight a task memory candidate without side effects |
 | `write_task_memory` | Persist reusable task experience after meaningful work |
 
 ## Memory Loop
@@ -88,8 +110,9 @@ The intended loop is:
 
 1. Before substantive implementation, debugging, migration, configuration, or optimization work, the agent calls `recall_for_task`.
 2. The agent applies relevant prior patterns, pitfalls, and decisions.
-3. After meaningful work completes, the agent calls `write_task_memory`.
-4. Core validates the candidate, filters low-signal content, and creates or merges a memory.
+3. After meaningful work completes, the agent calls `validate_task_memory` when available.
+4. If the candidate passes validation, the agent calls `write_task_memory`.
+5. Core validates again, filters low-signal content, and creates or merges a memory.
 
 The loop prioritizes reusable experience over raw conversation storage.
 

docs/MCP.zh-CN.md

@@ -16,13 +16,34 @@ Core 层是可信边界。Skill 可以提供指导，但 MCP/Core 必须执行
 
 ## 启动 MCP Server
 
+推荐用于 Registry 和免安装场景：
+
+```bash
+npx -y chatcrystal mcp
+```
+
+如果已经全局安装 ChatCrystal，也可以运行：
+
 ```bash
 crystal mcp
 ```
 
 ChatCrystal MCP 使用 stdio transport。请用 `command` 和 `args` 配置，不要配置成 HTTP/SSE MCP URL。
 
-Agent 配置示例：
+推荐的 Agent 配置：
+
+```json
+{
+  "mcpServers": {
+    "chatcrystal": {
+      "command": "npx",
+      "args": ["-y", "chatcrystal", "mcp"]
+    }
+  }
+}
+```
+
+全局安装后的配置：
 
 ```json
 {
@@ -35,7 +56,7 @@ Agent 配置示例：
 }
 ```
 
-如果某个工具另外要求填写 HTTP API endpoint，请使用 `http://localhost:3721`。不要填写没有端口的裸 `http://127.0.0.1`，因为 HTTP 会默认落到 80 端口。
+本地模式会连接或自动启动 `http://localhost:3721` 上的 ChatCrystal Core，默认数据目录为 `~/.chatcrystal/data`。如果某个工具另外要求填写 HTTP API endpoint，请使用 `http://localhost:3721`。不要填写没有端口的裸 `http://127.0.0.1`，因为 HTTP 会默认落到 80 端口。
 
 ### 云端模式
 
@@ -52,14 +73,14 @@ Agent 配置示例：
 }
 ```
 
-也可以在 MCP 客户端配置中直接传入环境变量：
+也可以在 MCP 客户端配置中直接传入环境变量。连接云端或远程实例时设置 `CHATCRYSTAL_BASE_URL`，如果该实例需要认证，再设置 `CHATCRYSTAL_API_TOKEN`：
 
 ```json
 {
   "mcpServers": {
     "chatcrystal": {
-      "command": "crystal",
-      "args": ["mcp"],
+      "command": "npx",
+      "args": ["-y", "chatcrystal", "mcp"],
       "env": {
         "CHATCRYSTAL_BASE_URL": "https://chatcrystal.example.com",
         "CHATCRYSTAL_API_TOKEN": "your-long-token"
@@ -71,7 +92,7 @@ Agent 配置示例：
 
 ## MCP 工具
 
-ChatCrystal 暴露六个 MCP 工具：
+ChatCrystal 暴露七个 MCP 工具：
 
 | Tool | 用途 |
 |---|---|
@@ -80,6 +101,7 @@ ChatCrystal 暴露六个 MCP 工具：
 | `list_notes` | 浏览笔记，可带过滤条件 |
 | `get_relations` | 读取关联笔记和关系元数据 |
 | `recall_for_task` | 在实质任务前召回项目优先的经验 |
+| `validate_task_memory` | 无副作用预检待写入的任务记忆候选 |
 | `write_task_memory` | 在有结果的任务后持久化可复用经验 |
 
 ## Memory Loop
@@ -88,8 +110,9 @@ ChatCrystal 暴露六个 MCP 工具：
 
 1. 在实质性的实现、调试、迁移、配置或优化任务前，Agent 调用 `recall_for_task`。
 2. Agent 应用相关的历史模式、坑点和决策。
-3. 有意义的工作完成后，Agent 调用 `write_task_memory`。
-4. Core 校验候选内容，过滤低信号内容，并创建或合并记忆。
+3. 有意义的工作完成后，如果可用，Agent 先调用 `validate_task_memory`。
+4. 如果候选内容通过预检，Agent 再调用 `write_task_memory`。
+5. Core 再次校验候选内容，过滤低信号内容，并创建或合并记忆。
 
 这个循环优先沉淀可复用经验，而不是保存原始对话。
 

scripts/release.mjs

@@ -58,16 +58,32 @@ function writePkgVersion(path, version) {
 	writeFileSync(path, `${JSON.stringify(pkg, null, 2)}\n`);
 }
 
+function writeServerJsonVersion(path, version) {
+	const serverJson = readPkg(path);
+	serverJson.version = version;
+	if (Array.isArray(serverJson.packages)) {
+		for (const pkg of serverJson.packages) {
+			if (pkg.registryType === "npm" && pkg.identifier === "chatcrystal") {
+				pkg.version = version;
+			}
+		}
+	}
+	writeFileSync(path, `${JSON.stringify(serverJson, null, 2)}\n`);
+}
+
 const rootPkgPath = resolve(root, "package.json");
 const serverPkgPath = resolve(root, "server/package.json");
+const serverJsonPath = resolve(root, "server/server.json");
 const filesToStage = [];
 let tag;
 
 if (target === "npm" || target === "all") {
 	const serverPkg = readPkg(serverPkgPath);
 	const npmVersion = bumpVersion(serverPkg.version, arg);
 	writePkgVersion(serverPkgPath, npmVersion);
+	writeServerJsonVersion(serverJsonPath, npmVersion);
 	filesToStage.push("server/package.json");
+	filesToStage.push("server/server.json");
 	console.log(`  npm: ${serverPkg.version} → ${npmVersion}`);
 
 	if (target === "npm") {

server/package.json

@@ -1,6 +1,7 @@
 {
   "name": "chatcrystal",
   "version": "0.5.1",
+  "mcpName": "io.github.zengliangyi/chatcrystal",
   "private": false,
   "license": "Apache-2.0",
   "repository": {
@@ -34,7 +35,8 @@
   "files": [
     "dist/server/",
     "dist/shared/",
-    "README.md"
+    "README.md",
+    "server.json"
   ],
   "scripts": {
     "dev": "tsx watch src/index.ts",

server/scripts/check-npm-package.mjs

@@ -1,8 +1,12 @@
 import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import process from 'node:process';
 import { resolve } from 'node:path';
 
 const root = resolve(import.meta.dirname, '../..');
+const serverRoot = resolve(root, 'server');
+const packageJson = JSON.parse(readFileSync(resolve(serverRoot, 'package.json'), 'utf-8'));
+const serverJson = JSON.parse(readFileSync(resolve(serverRoot, 'server.json'), 'utf-8'));
 
 const output = execSync('npm pack -w server --dry-run --json', {
   cwd: root,
@@ -16,6 +20,7 @@ const files = pack.files.map((file) => file.path).sort();
 const requiredFiles = [
   'README.md',
   'package.json',
+  'server.json',
   'dist/server/src/index.js',
   'dist/server/src/cli/index.js',
   'dist/server/src/data/seed-notes.json',
@@ -49,6 +54,30 @@ for (const { name, pattern } of forbiddenPatterns) {
   }
 }
 
+if (serverJson.name !== packageJson.mcpName) {
+  failures.push(`server.json name (${serverJson.name}) must match package.json mcpName (${packageJson.mcpName}).`);
+}
+
+if (serverJson.version !== packageJson.version) {
+  failures.push(`server.json version (${serverJson.version}) must match package.json version (${packageJson.version}).`);
+}
+
+const npmPackage = Array.isArray(serverJson.packages)
+  ? serverJson.packages.find((pkg) => pkg.registryType === 'npm' && pkg.identifier === packageJson.name)
+  : undefined;
+
+if (!npmPackage) {
+  failures.push(`server.json must include an npm package entry for ${packageJson.name}.`);
+} else {
+  if (npmPackage.version !== packageJson.version) {
+    failures.push(`server.json npm package version (${npmPackage.version}) must match package.json version (${packageJson.version}).`);
+  }
+
+  if (npmPackage.transport?.type !== 'stdio') {
+    failures.push('server.json npm package transport must be stdio.');
+  }
+}
+
 if (files.length > 300) {
   failures.push(`Package contains ${files.length} files; expected at most 300 runtime files.`);
 }

server/server.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.zengliangyi/chatcrystal",
+  "title": "ChatCrystal",
+  "description": "Local-first AI PKM memory for coding conversations.",
+  "version": "0.5.1",
+  "websiteUrl": "https://zengliangyi.github.io/ChatCrystal/",
+  "repository": {
+    "url": "https://github.com/ZengLiangYi/ChatCrystal",
+    "source": "github",
+    "id": "1193284630",
+    "subfolder": "server"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "chatcrystal",
+      "version": "0.5.1",
+      "runtimeHint": "npx",
+      "runtimeArguments": [
+        {
+          "type": "positional",
+          "value": "-y"
+        }
+      ],
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "mcp"
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "CHATCRYSTAL_BASE_URL",
+          "description": "Optional ChatCrystal Core URL. Leave empty to use the local default at http://localhost:3721.",
+          "placeholder": "https://chatcrystal.example.com"
+        },
+        {
+          "name": "CHATCRYSTAL_API_TOKEN",
+          "description": "Optional token for a protected ChatCrystal Cloud or remote instance.",
+          "isSecret": true
+        }
+      ],
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}