@zhin.js/mcp-feature 1.0.2 → 1.0.4

package/README.md

@@ -34,6 +34,9 @@ export default defineMcp({
 
 `create()` 在 projection prepare 中执行，只能构造 inert client；网络连接必须放在 `start()`。具体 stdio/HTTP transport 和 MCP SDK 由 Plugin Resource 或可选 adapter 提供，本包没有相关第三方依赖。
 
+单文件插件可用 `setup({ addMcp })` 注册 `defineMcp(...)`。它仍走相同的连接 handoff、
+owner 继承和 generation 回收。
+
 ## 生命周期
 
 ```text

package/lib/definition.d.ts

@@ -16,6 +16,11 @@ export interface McpDefinition<TConfig = unknown> {
     readonly description?: string;
     create(context: CapabilityContext<TConfig>): McpClientInstance | Promise<McpClientInstance>;
 }
+declare module '@zhin.js/plugin-runtime' {
+    interface PluginSetupContext<TConfig> {
+        addMcp(localName: string, definition: McpDefinition<TConfig>): void;
+    }
+}
 export declare function defineMcp<TConfig = unknown>(definition: Omit<McpDefinition<TConfig>, '$feature'>): Readonly<McpDefinition<TConfig>>;
 export declare function parseMcpDefinition(value: unknown): McpDefinition;
 export declare function assertMcpClient(value: unknown, source: string): asserts value is McpClientInstance;

package/lib/mcp-index.js

@@ -37,11 +37,12 @@ export class McpIndex {
         const started = [];
         try {
             for (const record of this.#order) {
-                if (record.started || record.stopped)
+                if (record.started)
                     continue;
                 started.push(record);
                 await record.client.start?.();
                 record.started = true;
+                record.stopped = false;
             }
         }
         catch (error) {
@@ -90,8 +91,11 @@ async function stopRecords(records, primary) {
         if (record.stopped)
             continue;
         stack.add(async () => {
-            record.stopped = true;
+            // 先 await stop 成功再标记 stopped：stop 失败时保持未标记，
+            // 下次 stop()（或代际 resume 后的再次 quiesce）可重试，不会永久泄漏。
             await record.client.stop?.();
+            record.started = false;
+            record.stopped = true;
         });
     }
     try {

package/lib/provider.js

@@ -7,6 +7,7 @@ const mcpFeature = defineFeatureProvider({
     protocol: 1,
     id: mcpFeatureId,
     authoring: {
+        setupMethod: 'addMcp',
         conventions: [typeScriptModules({
                 id: 'mcp-ts',
                 directory: 'mcp',
@@ -17,16 +18,28 @@ const mcpFeature = defineFeatureProvider({
     runtime: {
         async project(slots, context) {
             const index = await McpIndex.create(slots, context.snapshot);
+            let previousIndex;
             return {
                 value: index,
                 dispose: () => index.stop(),
                 handoff: {
+                    // 先停旧代连接再激活新代：独占端口型 server 热重载不会新旧并存。
+                    quiescePrevious(previous) {
+                        previousIndex = previousMcpIndex(previous);
+                        return previousIndex?.stop();
+                    },
                     activateNext: () => index.start(),
                     deactivateNext: () => index.stop(),
+                    resumePrevious() {
+                        return previousIndex?.start();
+                    },
                 },
             };
         },
     },
 });
+function previousMcpIndex(snapshot) {
+    return snapshot.projections.get(mcpFeatureId);
+}
 export { mcpFeature };
 export default mcpFeature;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/mcp-feature",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Convention-based MCP client Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,8 +17,8 @@
     "src"
   ],
   "dependencies": {
-    "@zhin.js/feature-kit": "1.0.2",
-    "@zhin.js/plugin-runtime": "1.1.0"
+    "@zhin.js/feature-kit": "1.0.4",
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",

package/src/definition.ts

@@ -21,6 +21,12 @@ export interface McpDefinition<TConfig = unknown> {
   create(context: CapabilityContext<TConfig>): McpClientInstance | Promise<McpClientInstance>;
 }
 
+declare module '@zhin.js/plugin-runtime' {
+  interface PluginSetupContext<TConfig> {
+    addMcp(localName: string, definition: McpDefinition<TConfig>): void;
+  }
+}
+
 export function defineMcp<TConfig = unknown>(
   definition: Omit<McpDefinition<TConfig>, '$feature'>,
 ): Readonly<McpDefinition<TConfig>> {

package/src/mcp-index.ts

@@ -78,10 +78,11 @@ export class McpIndex {
     const started: McpRecord[] = [];
     try {
       for (const record of this.#order) {
-        if (record.started || record.stopped) continue;
+        if (record.started) continue;
         started.push(record);
         await record.client.start?.();
         record.started = true;
+        record.stopped = false;
       }
     } catch (error) {
       await stopRecords(started, error);
@@ -137,8 +138,11 @@ async function stopRecords(records: readonly McpRecord[], primary?: unknown): Pr
   for (const record of records) {
     if (record.stopped) continue;
     stack.add(async () => {
-      record.stopped = true;
+      // 先 await stop 成功再标记 stopped：stop 失败时保持未标记，
+      // 下次 stop()（或代际 resume 后的再次 quiesce）可重试，不会永久泄漏。
       await record.client.stop?.();
+      record.started = false;
+      record.stopped = true;
     });
   }
   try {

package/src/provider.ts

@@ -1,4 +1,4 @@
-import { featureId } from '@zhin.js/plugin-runtime';
+import { featureId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import { defineFeatureProvider, typeScriptModules } from '@zhin.js/feature-kit';
 import { parseMcpDefinition } from './definition.js';
 import { McpIndex } from './mcp-index.js';
@@ -9,6 +9,7 @@ const mcpFeature = defineFeatureProvider({
   protocol: 1,
   id: mcpFeatureId,
   authoring: {
+    setupMethod: 'addMcp',
     conventions: [typeScriptModules({
       id: 'mcp-ts',
       directory: 'mcp',
@@ -19,17 +20,30 @@ const mcpFeature = defineFeatureProvider({
   runtime: {
     async project(slots, context) {
       const index = await McpIndex.create(slots, context.snapshot);
+      let previousIndex: McpIndex | undefined;
       return {
         value: index,
         dispose: () => index.stop(),
         handoff: {
+          // 先停旧代连接再激活新代：独占端口型 server 热重载不会新旧并存。
+          quiescePrevious(previous) {
+            previousIndex = previousMcpIndex(previous);
+            return previousIndex?.stop();
+          },
           activateNext: () => index.start(),
           deactivateNext: () => index.stop(),
+          resumePrevious() {
+            return previousIndex?.start();
+          },
         },
       };
     },
   },
 });
 
+function previousMcpIndex(snapshot: RuntimeSnapshot): McpIndex | undefined {
+  return snapshot.projections.get(mcpFeatureId) as McpIndex | undefined;
+}
+
 export { mcpFeature };
 export default mcpFeature;