@zhin.js/mcp-feature 1.1.16 → 1.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/mcp-feature",
-  "version": "1.1.16",
+  "version": "1.1.17",
   "description": "Convention-based MCP client Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -12,12 +12,11 @@
     }
   },
   "files": [
-    "lib",
-    "src"
+    "lib"
   ],
   "dependencies": {
-    "@zhin.js/feature-kit": "1.1.15",
-    "@zhin.js/plugin-runtime": "1.1.23"
+    "@zhin.js/plugin-runtime": "1.2.0",
+    "@zhin.js/feature-kit": "1.1.16"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/definition.ts

@@ -1,73 +0,0 @@
-import type { ConstructionContext } 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?(signal: AbortSignal): 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: ConstructionContext<TConfig>): McpClientInstance | Promise<McpClientInstance>;
-}
-
-declare module '@zhin.js/plugin-runtime' {
-  interface PluginSetupContext<TConfig = unknown> {
-    addMcp(localName: string, definition: McpDefinition<TConfig>): void;
-  }
-}
-
-export type McpDefiner<TConfig> = (
-  definition: Omit<McpDefinition<TConfig>, '$feature'>,
-) => Readonly<McpDefinition<TConfig>>;
-
-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 });
-}
-
-/**
- * Fix the plugin config type first, then define the MCP client.
- */
-defineMcp.withConfig = function withConfig<TConfig = unknown>(): McpDefiner<TConfig> {
-  return (definition) => defineMcp(definition);
-};
-
-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

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

package/src/mcp-index.ts

@@ -1,172 +0,0 @@
-import {
-  DisposeStack,
-  type CapabilitySlot,
-  type PluginId,
-  type RuntimeSnapshot,
-} from '@zhin.js/plugin-runtime';
-import {
-  OwnerCapabilityIndex,
-  createConstructionContext,
-  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 $projection = 'zhin.mcp-index/1' as const;
-  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,
-    signal: AbortSignal,
-  ): Promise<McpIndex> {
-    const index = new OwnerCapabilityIndex(slots, snapshot);
-    const records: McpRecord[] = [];
-    try {
-      for (const entry of index.entries()) {
-        signal.throwIfAborted();
-        const client = await entry.slot.definition.create(
-          createConstructionContext(snapshot, entry.owner, undefined, signal),
-        );
-        signal.throwIfAborted();
-        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(signal: AbortSignal): Promise<void> {
-    const started: McpRecord[] = [];
-    try {
-      for (const record of this.#order) {
-        if (record.started) continue;
-        signal.throwIfAborted();
-        started.push(record);
-        await record.client.start?.(signal);
-        signal.throwIfAborted();
-        record.started = true;
-        record.stopped = false;
-      }
-    } 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 () => {
-      // 先 await stop 成功再标记 stopped：stop 失败时保持未标记，
-      // 下次 stop() 可重试，不会因一次失败永久泄漏。
-      await record.client.stop?.();
-      record.started = false;
-      record.stopped = true;
-    });
-  }
-  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;
-  }
-}
-
-/** Recognize the versioned projection across generation module identities. */
-export function isMcpIndex(value: unknown): value is McpIndex {
-  return !!value && typeof value === 'object'
-    && (value as { readonly $projection?: unknown }).$projection === 'zhin.mcp-index/1';
-}

package/src/provider.ts

@@ -1,38 +0,0 @@
-import { featureId } from '@zhin.js/plugin-runtime';
-import { capture, captured, defineFeatureProvider, directoryModules } 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: {
-    setupMethod: 'addMcp',
-    conventions: [directoryModules({
-      id: 'mcps-index',
-      layouts: [{ segments: ['mcps', capture('name')], localName: (values) => captured(values, 'name') }],
-    })],
-    validate: parseMcpDefinition,
-  },
-  runtime: {
-    retain: 'when-owner-unchanged',
-    async project(slots, context) {
-      const index = await McpIndex.create(slots, context.snapshot, context.signal);
-      return {
-        value: index,
-        dispose: () => index.stop(),
-        handoff: {
-          // Candidate connections become ready before publication. The old
-          // index stays usable until its snapshot's final lease drains.
-          activateNext: (signal) => index.start(signal),
-          deactivateNext: () => index.stop(),
-        },
-      };
-    },
-  },
-});
-
-export { mcpFeature };
-export default mcpFeature;