@zhin.js/mcp-feature 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+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.

package/README.md

@@ -0,0 +1,56 @@
+# @zhin.js/mcp-feature
+
+下一代 MCP Client Feature。它从 `mcp/<name>.ts` 发现 provider-neutral client definition，并将连接实例的创建、启动、调用和销毁绑定到 Plugin owner 与 generation lease。
+
+## 目录约定
+
+```text
+mcp/
+├── filesystem.ts
+└── memory.ts
+```
+
+只发现一级 `.ts` 文件。连接参数、URL、command 和 secret 应从 owner config/resource 读取，不写入另一份全局 MCP 配置 registry。
+
+## 定义 MCP Client
+
+```ts
+import { defineMcp } from '@zhin.js/mcp-feature';
+import { mcpTransportFactoryToken } from '../plugin.js';
+
+export default defineMcp({
+  description: 'Workspace filesystem tools',
+  create(context) {
+    const client = context.use(mcpTransportFactoryToken).create(context.config);
+    return {
+      start: () => client.connect(),
+      stop: () => client.close(),
+      listTools: () => client.listTools(),
+      callTool: (name, input) => client.callTool(name, input),
+    };
+  },
+});
+```
+
+`create()` 在 projection prepare 中执行，只能构造 inert client；网络连接必须放在 `start()`。具体 stdio/HTTP transport 和 MCP SDK 由 Plugin Resource 或可选 adapter 提供，本包没有相关第三方依赖。
+
+## 生命周期
+
+```text
+prepare candidate: create()
+before commit:     candidate.start()
+commit:            publish new McpIndex
+old lease = 0:     previous.stop()
+rollback:          candidate.stop()
+```
+
+MCP 没有入站 admission，因此候选连接不 quiesce 旧 client。旧 turn 可继续通过旧 projection 完成在途调用；新 turn 只看到已启动并已提交的新 client。要求排他连接时，应把连接资源提升到 Plugin Resource handoff。
+
+`McpIndex` 对连接使用 owner inheritance。动态工具名由 client 返回；orchestrator 可投影为 `{connection}__{tool}`，但该模型命名不改变 Capability identity。
+
+## 验证
+
+```bash
+pnpm --filter @zhin.js/mcp-feature test
+pnpm --filter @zhin.js/mcp-feature build
+```

package/lib/definition.d.ts

@@ -0,0 +1,22 @@
+import type { CapabilityContext } from '@zhin.js/feature-kit';
+declare const mcpBrand: "zhin.mcp/1";
+export interface McpToolDescriptor {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema?: unknown;
+}
+export interface McpClientInstance {
+    start?(): void | Promise<void>;
+    stop?(): void | Promise<void>;
+    listTools(): readonly McpToolDescriptor[] | Promise<readonly McpToolDescriptor[]>;
+    callTool(name: string, input: unknown): unknown | Promise<unknown>;
+}
+export interface McpDefinition<TConfig = unknown> {
+    readonly $feature: typeof mcpBrand;
+    readonly description?: string;
+    create(context: CapabilityContext<TConfig>): McpClientInstance | Promise<McpClientInstance>;
+}
+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;
+export {};

package/lib/definition.js

@@ -0,0 +1,30 @@
+const mcpBrand = 'zhin.mcp/1';
+export function defineMcp(definition) {
+    if (typeof definition.create !== 'function') {
+        throw new TypeError('MCP create must be a function');
+    }
+    return Object.freeze({ ...definition, $feature: mcpBrand });
+}
+export function parseMcpDefinition(value) {
+    if (!value || typeof value !== 'object')
+        throw invalidMcp();
+    const definition = value;
+    if (definition.$feature !== mcpBrand || typeof definition.create !== 'function') {
+        throw invalidMcp();
+    }
+    return definition;
+}
+export function assertMcpClient(value, source) {
+    if (!value || typeof value !== 'object')
+        throw invalidClient(source);
+    const client = value;
+    if (typeof client.listTools !== 'function' || typeof client.callTool !== 'function') {
+        throw invalidClient(source);
+    }
+}
+function invalidMcp() {
+    return new TypeError('MCP module must default-export defineMcp(...)');
+}
+function invalidClient(source) {
+    return new TypeError(`MCP ${source} create() must return a client instance`);
+}

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export * from './definition.js';
+export * from './mcp-index.js';
+export * from './provider.js';
+export { default } from './provider.js';

package/lib/index.js

@@ -0,0 +1,4 @@
+export * from './definition.js';
+export * from './mcp-index.js';
+export * from './provider.js';
+export { default } from './provider.js';

package/lib/mcp-index.d.ts

@@ -0,0 +1,20 @@
+import { type CapabilitySlot, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type McpDefinition, type McpToolDescriptor } from './definition.js';
+export interface McpDescriptor {
+    readonly owner: PluginId;
+    readonly name: string;
+    readonly qualifiedName: string;
+    readonly description?: string;
+    readonly source: string;
+}
+export declare class McpIndex {
+    #private;
+    private constructor();
+    static create(slots: readonly Readonly<CapabilitySlot<McpDefinition>>[], snapshot: RuntimeSnapshot): Promise<McpIndex>;
+    list(): readonly McpDescriptor[];
+    visible(requester: PluginId): readonly McpDescriptor[];
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    listTools(requester: PluginId, name: string): Promise<readonly McpToolDescriptor[]>;
+    callTool<TResult = unknown>(requester: PluginId, connection: string, tool: string, input: unknown): Promise<TResult>;
+}

package/lib/mcp-index.js

@@ -0,0 +1,106 @@
+import { DisposeStack, } from '@zhin.js/plugin-runtime';
+import { OwnerCapabilityIndex, createCapabilityContext, } from '@zhin.js/feature-kit';
+import { assertMcpClient, } from './definition.js';
+export class McpIndex {
+    #index;
+    #records = new Map();
+    #order;
+    constructor(index, records) {
+        this.#index = index;
+        this.#order = Object.freeze([...records]);
+        for (const record of records)
+            this.#records.set(record.entry.slot.id, record);
+    }
+    static async create(slots, snapshot) {
+        const index = new OwnerCapabilityIndex(slots, snapshot);
+        const records = [];
+        try {
+            for (const entry of index.entries()) {
+                const client = await entry.slot.definition.create(createCapabilityContext(snapshot, entry.owner));
+                assertMcpClient(client, entry.source);
+                records.push({ entry, client, started: false, stopped: false });
+            }
+            return new McpIndex(index, records);
+        }
+        catch (error) {
+            await stopRecords(records, error);
+            throw error;
+        }
+    }
+    list() {
+        return this.#index.entries().map(toDescriptor);
+    }
+    visible(requester) {
+        return this.#index.visible(requester).map(toDescriptor);
+    }
+    async start() {
+        const started = [];
+        try {
+            for (const record of this.#order) {
+                if (record.started || record.stopped)
+                    continue;
+                started.push(record);
+                await record.client.start?.();
+                record.started = true;
+            }
+        }
+        catch (error) {
+            await stopRecords(started, error);
+            throw error;
+        }
+    }
+    async stop() {
+        await stopRecords(this.#order);
+    }
+    async listTools(requester, name) {
+        const record = this.#resolve(requester, name);
+        return Object.freeze((await record.client.listTools()).map((tool) => {
+            if (!tool.name.trim())
+                throw new TypeError(`MCP ${name} returned a Tool without a name`);
+            return Object.freeze({ ...tool });
+        }));
+    }
+    async callTool(requester, connection, tool, input) {
+        const record = this.#resolve(requester, connection);
+        return record.client.callTool(tool, input);
+    }
+    #resolve(requester, name) {
+        const entry = this.#index.resolve(requester, name);
+        if (!entry)
+            throw new Error(`Unknown MCP connection ${name} for ${requester}`);
+        const record = this.#records.get(entry.slot.id);
+        if (!record || !record.started || record.stopped) {
+            throw new Error(`MCP connection is not active: ${entry.qualifiedName}`);
+        }
+        return record;
+    }
+}
+function toDescriptor(entry) {
+    return Object.freeze({
+        owner: entry.owner,
+        name: entry.name,
+        qualifiedName: entry.qualifiedName,
+        description: entry.slot.definition.description,
+        source: entry.source,
+    });
+}
+async function stopRecords(records, primary) {
+    const stack = new DisposeStack();
+    for (const record of records) {
+        if (record.stopped)
+            continue;
+        stack.add(async () => {
+            record.stopped = true;
+            await record.client.stop?.();
+        });
+    }
+    try {
+        await stack.dispose();
+    }
+    catch (stopError) {
+        if (primary !== undefined) {
+            throw new AggregateError([primary, stopError], 'MCP prepare and client cleanup both failed', { cause: stopError });
+        }
+        throw stopError;
+    }
+}

package/lib/provider.d.ts

@@ -0,0 +1,5 @@
+import { McpIndex } from './mcp-index.js';
+export declare const mcpFeatureId: import("@zhin.js/plugin-runtime").FeatureId;
+declare const mcpFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").McpDefinition<unknown>, McpIndex>>;
+export { mcpFeature };
+export default mcpFeature;

package/lib/provider.js

@@ -0,0 +1,32 @@
+import { featureId } from '@zhin.js/plugin-runtime';
+import { defineFeatureProvider, typeScriptModules } from '@zhin.js/feature-kit';
+import { parseMcpDefinition } from './definition.js';
+import { McpIndex } from './mcp-index.js';
+export const mcpFeatureId = featureId('zhin.mcp');
+const mcpFeature = defineFeatureProvider({
+    protocol: 1,
+    id: mcpFeatureId,
+    authoring: {
+        conventions: [typeScriptModules({
+                id: 'mcp-ts',
+                directory: 'mcp',
+                recursive: false,
+            })],
+        validate: parseMcpDefinition,
+    },
+    runtime: {
+        async project(slots, context) {
+            const index = await McpIndex.create(slots, context.snapshot);
+            return {
+                value: index,
+                dispose: () => index.stop(),
+                handoff: {
+                    activateNext: () => index.start(),
+                    deactivateNext: () => index.stop(),
+                },
+            };
+        },
+    },
+});
+export { mcpFeature };
+export default mcpFeature;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@zhin.js/mcp-feature",
+  "version": "1.0.0",
+  "description": "Convention-based MCP client Feature for Zhin Plugin Runtime",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@zhin.js/feature-kit": "1.0.0",
+    "@zhin.js/plugin-runtime": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "feature",
+    "entry": "./lib/provider.js",
+    "engine": "^1.0.0",
+    "featureApi": "1.0.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/im/mcp-feature"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/im/mcp-feature/tests"
+  }
+}

package/src/definition.ts

@@ -0,0 +1,56 @@
+import type { CapabilityContext } from '@zhin.js/feature-kit';
+
+const mcpBrand = 'zhin.mcp/1' as const;
+
+export interface McpToolDescriptor {
+  readonly name: string;
+  readonly description?: string;
+  readonly inputSchema?: unknown;
+}
+
+export interface McpClientInstance {
+  start?(): void | Promise<void>;
+  stop?(): void | Promise<void>;
+  listTools(): readonly McpToolDescriptor[] | Promise<readonly McpToolDescriptor[]>;
+  callTool(name: string, input: unknown): unknown | Promise<unknown>;
+}
+
+export interface McpDefinition<TConfig = unknown> {
+  readonly $feature: typeof mcpBrand;
+  readonly description?: string;
+  create(context: CapabilityContext<TConfig>): McpClientInstance | Promise<McpClientInstance>;
+}
+
+export function defineMcp<TConfig = unknown>(
+  definition: Omit<McpDefinition<TConfig>, '$feature'>,
+): Readonly<McpDefinition<TConfig>> {
+  if (typeof definition.create !== 'function') {
+    throw new TypeError('MCP create must be a function');
+  }
+  return Object.freeze({ ...definition, $feature: mcpBrand });
+}
+
+export function parseMcpDefinition(value: unknown): McpDefinition {
+  if (!value || typeof value !== 'object') throw invalidMcp();
+  const definition = value as Partial<McpDefinition>;
+  if (definition.$feature !== mcpBrand || typeof definition.create !== 'function') {
+    throw invalidMcp();
+  }
+  return definition as McpDefinition;
+}
+
+export function assertMcpClient(value: unknown, source: string): asserts value is McpClientInstance {
+  if (!value || typeof value !== 'object') throw invalidClient(source);
+  const client = value as Partial<McpClientInstance>;
+  if (typeof client.listTools !== 'function' || typeof client.callTool !== 'function') {
+    throw invalidClient(source);
+  }
+}
+
+function invalidMcp(): TypeError {
+  return new TypeError('MCP module must default-export defineMcp(...)');
+}
+
+function invalidClient(source: string): TypeError {
+  return new TypeError(`MCP ${source} create() must return a client instance`);
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './definition.js';
+export * from './mcp-index.js';
+export * from './provider.js';
+export { default } from './provider.js';

package/src/mcp-index.ts

@@ -0,0 +1,156 @@
+import {
+  DisposeStack,
+  type CapabilitySlot,
+  type PluginId,
+  type RuntimeSnapshot,
+} from '@zhin.js/plugin-runtime';
+import {
+  OwnerCapabilityIndex,
+  createCapabilityContext,
+  type OwnerCapabilityEntry,
+} from '@zhin.js/feature-kit';
+import {
+  assertMcpClient,
+  type McpClientInstance,
+  type McpDefinition,
+  type McpToolDescriptor,
+} from './definition.js';
+
+export interface McpDescriptor {
+  readonly owner: PluginId;
+  readonly name: string;
+  readonly qualifiedName: string;
+  readonly description?: string;
+  readonly source: string;
+}
+
+interface McpRecord {
+  readonly entry: OwnerCapabilityEntry<McpDefinition>;
+  readonly client: McpClientInstance;
+  started: boolean;
+  stopped: boolean;
+}
+
+export class McpIndex {
+  readonly #index: OwnerCapabilityIndex<McpDefinition>;
+  readonly #records = new Map<string, McpRecord>();
+  readonly #order: readonly McpRecord[];
+
+  private constructor(
+    index: OwnerCapabilityIndex<McpDefinition>,
+    records: readonly McpRecord[],
+  ) {
+    this.#index = index;
+    this.#order = Object.freeze([...records]);
+    for (const record of records) this.#records.set(record.entry.slot.id, record);
+  }
+
+  static async create(
+    slots: readonly Readonly<CapabilitySlot<McpDefinition>>[],
+    snapshot: RuntimeSnapshot,
+  ): Promise<McpIndex> {
+    const index = new OwnerCapabilityIndex(slots, snapshot);
+    const records: McpRecord[] = [];
+    try {
+      for (const entry of index.entries()) {
+        const client = await entry.slot.definition.create(
+          createCapabilityContext(snapshot, entry.owner),
+        );
+        assertMcpClient(client, entry.source);
+        records.push({ entry, client, started: false, stopped: false });
+      }
+      return new McpIndex(index, records);
+    } catch (error) {
+      await stopRecords(records, error);
+      throw error;
+    }
+  }
+
+  list(): readonly McpDescriptor[] {
+    return this.#index.entries().map(toDescriptor);
+  }
+
+  visible(requester: PluginId): readonly McpDescriptor[] {
+    return this.#index.visible(requester).map(toDescriptor);
+  }
+
+  async start(): Promise<void> {
+    const started: McpRecord[] = [];
+    try {
+      for (const record of this.#order) {
+        if (record.started || record.stopped) continue;
+        started.push(record);
+        await record.client.start?.();
+        record.started = true;
+      }
+    } catch (error) {
+      await stopRecords(started, error);
+      throw error;
+    }
+  }
+
+  async stop(): Promise<void> {
+    await stopRecords(this.#order);
+  }
+
+  async listTools(requester: PluginId, name: string): Promise<readonly McpToolDescriptor[]> {
+    const record = this.#resolve(requester, name);
+    return Object.freeze((await record.client.listTools()).map((tool) => {
+      if (!tool.name.trim()) throw new TypeError(`MCP ${name} returned a Tool without a name`);
+      return Object.freeze({ ...tool });
+    }));
+  }
+
+  async callTool<TResult = unknown>(
+    requester: PluginId,
+    connection: string,
+    tool: string,
+    input: unknown,
+  ): Promise<TResult> {
+    const record = this.#resolve(requester, connection);
+    return record.client.callTool(tool, input) as TResult | Promise<TResult>;
+  }
+
+  #resolve(requester: PluginId, name: string): McpRecord {
+    const entry = this.#index.resolve(requester, name);
+    if (!entry) throw new Error(`Unknown MCP connection ${name} for ${requester}`);
+    const record = this.#records.get(entry.slot.id);
+    if (!record || !record.started || record.stopped) {
+      throw new Error(`MCP connection is not active: ${entry.qualifiedName}`);
+    }
+    return record;
+  }
+}
+
+function toDescriptor(entry: OwnerCapabilityEntry<McpDefinition>): McpDescriptor {
+  return Object.freeze({
+    owner: entry.owner,
+    name: entry.name,
+    qualifiedName: entry.qualifiedName,
+    description: entry.slot.definition.description,
+    source: entry.source,
+  });
+}
+
+async function stopRecords(records: readonly McpRecord[], primary?: unknown): Promise<void> {
+  const stack = new DisposeStack();
+  for (const record of records) {
+    if (record.stopped) continue;
+    stack.add(async () => {
+      record.stopped = true;
+      await record.client.stop?.();
+    });
+  }
+  try {
+    await stack.dispose();
+  } catch (stopError) {
+    if (primary !== undefined) {
+      throw new AggregateError(
+        [primary, stopError],
+        'MCP prepare and client cleanup both failed',
+        { cause: stopError },
+      );
+    }
+    throw stopError;
+  }
+}

package/src/provider.ts

@@ -0,0 +1,35 @@
+import { featureId } from '@zhin.js/plugin-runtime';
+import { defineFeatureProvider, typeScriptModules } from '@zhin.js/feature-kit';
+import { parseMcpDefinition } from './definition.js';
+import { McpIndex } from './mcp-index.js';
+
+export const mcpFeatureId = featureId('zhin.mcp');
+
+const mcpFeature = defineFeatureProvider({
+  protocol: 1,
+  id: mcpFeatureId,
+  authoring: {
+    conventions: [typeScriptModules({
+      id: 'mcp-ts',
+      directory: 'mcp',
+      recursive: false,
+    })],
+    validate: parseMcpDefinition,
+  },
+  runtime: {
+    async project(slots, context) {
+      const index = await McpIndex.create(slots, context.snapshot);
+      return {
+        value: index,
+        dispose: () => index.stop(),
+        handoff: {
+          activateNext: () => index.start(),
+          deactivateNext: () => index.stop(),
+        },
+      };
+    },
+  },
+});
+
+export { mcpFeature };
+export default mcpFeature;