`@codesoul-co/hypha-mcp` / `contracts`

模块用法

用于声明并运行时校验契约。Contracts 模块公开 14 常量、9 接口、2 类型。

从包入口导入

import {
  governedMCPIntegrationDefinition,
  governedMCPIntegrationExample,
  governedMCPIntegrationJsonSchema,
  governedMCPIntegrationJsonSchemas,
  governedMCPIntegrationSpecSchema,
  mcpCapabilityDriftPolicySpecSchema,
  mcpServerProfileSchema,
  mcpTransportSpecSchema,
} from '@codesoul-co/hypha-mcp';

import type {
  GovernedMCPIntegrationSpec,
  MCPAllowDenyRule,
  MCPCapabilityDriftPolicySpec,
  MCPCapabilityTrustRecord,
  MCPContractSnapshotPolicySpec,
  MCPImportPolicySpec,
  MCPServerProfile,
  MCPTrustPolicySpec,
} from '@codesoul-co/hypha-mcp';

// 完整导出列表见下方。

使用要点

11 个类型/接口用于应用代码、Adapter 或测试中的静态契约；请使用 import type，运行时不应依赖它们。
14 个常量/枚举提供稳定值、Schema、Definition 或默认配置；应复用这些导出，避免在应用中复制内部值。

运行时校验示例

import { governedMCPIntegrationSpecSchema } from '@codesoul-co/hypha-mcp';

declare function loadExternalInput(): unknown;
const input: unknown = loadExternalInput();
const parsed = governedMCPIntegrationSpecSchema.parse(input);

配置、网络请求或持久化数据等不可信输入应先通过 Runtime Schema，再传给只接受已校验契约的函数或类。

公共导出

Symbol	种类	签名	说明
`governedMCPIntegrationDefinition`	常量	`const governedMCPIntegrationDefinition: SpecSchemaDefinition<GovernedMCPIntegrationSpec>`	由 `contracts` 模块导出的 Governed MCP Integration Definition 常量。
`governedMCPIntegrationExample`	常量	`const governedMCPIntegrationExample: GovernedMCPIntegrationSpec`	Governed MCP Integration 的有效示例值。
`governedMCPIntegrationJsonSchema`	常量	`const governedMCPIntegrationJsonSchema: JsonSchema`	Governed MCP Integration 的 JSON Schema。
`governedMCPIntegrationJsonSchemas`	常量	`const governedMCPIntegrationJsonSchemas: Record<string, JsonSchema>`	由 `contracts` 模块导出的 Governed MCP Integration JSON Schemas 常量。
`governedMCPIntegrationSpecSchema`	常量	`const governedMCPIntegrationSpecSchema: z.ZodObject<{ id: z.ZodString; version: z.ZodString; revision: z.ZodOptional<z.ZodString>; name: z.ZodOptional<z.ZodString>; description: z.ZodOptional<z.ZodString>; servers: z.ZodArray<z.ZodObject<{ id: z.ZodString; version: z.ZodOptional<z.ZodString>; displayName: z.ZodOptional<z.ZodString>; mode: z.ZodEnum<["fixture", "local", "remote"]>; transport: z.ZodType<MCPTransport...`	Governed MCP Integration Spec 的运行时 Schema。
`mcpCapabilityDriftPolicySpecSchema`	常量	`const mcpCapabilityDriftPolicySpecSchema: z.ZodObject<{ onDescriptionChange: z.ZodEnum<["accept", "snapshot_next_run", "quarantine"]>; onSchemaChange: z.ZodEnum<["snapshot_next_run", "quarantine", "require_approval"]>; onRemoval: z.ZodEnum<["mark_unavailable", "allow_existing_run", "fail_existing_run"]>; onServerIdentityChange: z.ZodEnum<["disconnect", "quarantine"]>; notifyRuntime: z.ZodOptional<z.ZodBoolean>; in...`	MCP Capability Drift Policy Spec 的运行时 Schema。
`mcpServerProfileSchema`	常量	`const mcpServerProfileSchema: z.ZodObject<{ id: z.ZodString; version: z.ZodOptional<z.ZodString>; displayName: z.ZodOptional<z.ZodString>; mode: z.ZodEnum<["fixture", "local", "remote"]>; transport: z.ZodType<MCPTransportSpec, z.ZodTypeDef, MCPTransportSpec>; authRef: z.ZodOptional<z.ZodString>; environmentRefs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; workingDirectoryRef: z.ZodOptional<z.ZodString>; autoCo...`	MCP Server Profile 的运行时 Schema。
`mcpTransportSpecSchema`	常量	`const mcpTransportSpecSchema: z.ZodType<MCPTransportSpec, z.ZodTypeDef, MCPTransportSpec>`	MCP Transport Spec 的运行时 Schema。
`mcpTrustPolicySpecSchema`	常量	`const mcpTrustPolicySpecSchema: z.ZodObject<{ defaultTrustLevel: z.ZodEnum<["untrusted", "restricted", "trusted"]>; trustedSourceRefs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; requireAdminApprovalForNewServer: z.ZodOptional<z.ZodBoolean>; requireApprovalForNewCapability: z.ZodOptional<z.ZodBoolean>; requireApprovalForSchemaChange: z.ZodOptional<z.ZodBoolean>; allowServerDeclaredSideEffectHints: z.ZodOptiona...`	MCP Trust Policy Spec 的运行时 Schema。
`NORMALIZED_MCP_ERROR_CODES`	常量	`const NORMALIZED_MCP_ERROR_CODES: readonly ["MCP_SERVER_NOT_FOUND", "MCP_CONNECTION_FAILED", "MCP_INITIALIZATION_FAILED", "MCP_PROTOCOL_MISMATCH", "MCP_REQUEST_TIMEOUT", "MCP_REQUEST_CANCELLED", "MCP_CAPABILITY_NOT_FOUND", "MCP_CAPABILITY_QUARANTINED", "MCP_CAPABILITY_DRIFT", "MCP_SCHEMA_INVALID", "MCP_AUTH_FAILED", "MCP_BULKHEAD_REJECTED", "MCP_RATE_LIMITED", "MCP_CIRCUIT_OPEN", "MCP_EGRESS_DENIED", "MCP_CONTENT_...`	由 `contracts` 模块导出的 NORMALIZED MCP ERROR CODES 常量。
`normalizedMCPErrorDefinition`	常量	`const normalizedMCPErrorDefinition: SpecSchemaDefinition<NormalizedMCPError>`	由 `contracts` 模块导出的 Normalized MCP Error Definition 常量。
`normalizedMCPErrorExample`	常量	`const normalizedMCPErrorExample: NormalizedMCPError`	Normalized MCP Error 的有效示例值。
`normalizedMCPErrorJsonSchema`	常量	`const normalizedMCPErrorJsonSchema: JsonSchema`	Normalized MCP Error 的 JSON Schema。
`normalizedMCPErrorSchema`	常量	`const normalizedMCPErrorSchema: z.ZodObject<{ code: z.ZodEnum<["MCP_SERVER_NOT_FOUND", "MCP_CONNECTION_FAILED", "MCP_INITIALIZATION_FAILED", "MCP_PROTOCOL_MISMATCH", "MCP_REQUEST_TIMEOUT", "MCP_REQUEST_CANCELLED", "MCP_CAPABILITY_NOT_FOUND", "MCP_CAPABILITY_QUARANTINED", "MCP_CAPABILITY_DRIFT", "MCP_SCHEMA_INVALID", "MCP_AUTH_FAILED", "MCP_BULKHEAD_REJECTED", "MCP_RATE_LIMITED", "MCP_CIRCUIT_OPEN", "MCP_EGRESS_DEN...`	Normalized MCP Error 的运行时 Schema。
`GovernedMCPIntegrationSpec`	接口	`interface GovernedMCPIntegrationSpec`	Governed MCP Integration Spec 接口，共包含 16 个公开字段或方法。
`MCPAllowDenyRule`	接口	`interface MCPAllowDenyRule`	MCP Allow Deny Rule 接口，共包含 4 个公开字段或方法。
`MCPCapabilityDriftPolicySpec`	接口	`interface MCPCapabilityDriftPolicySpec`	MCP Capability Drift Policy Spec 接口，共包含 6 个公开字段或方法。
`MCPCapabilityTrustRecord`	接口	`interface MCPCapabilityTrustRecord`	MCP Capability Trust Record 接口，共包含 7 个公开字段或方法。
`MCPContractSnapshotPolicySpec`	接口	`interface MCPContractSnapshotPolicySpec`	MCP Contract Snapshot Policy Spec 接口，共包含 3 个公开字段或方法。
`MCPImportPolicySpec`	接口	`interface MCPImportPolicySpec`	MCP Import Policy Spec 接口，共包含 4 个公开字段或方法。
`MCPServerProfile`	接口	`interface MCPServerProfile`	MCP Server Profile 接口，共包含 22 个公开字段或方法。
`MCPTrustPolicySpec`	接口	`interface MCPTrustPolicySpec`	MCP Trust Policy Spec 接口，共包含 9 个公开字段或方法。
`NormalizedMCPError`	接口	`interface NormalizedMCPError`	Normalized MCP Error 接口，共包含 7 个公开字段或方法。
`MCPTransportSpec`	类型	`type MCPTransportSpec = { type: 'stdio'; command: string; args?: string[]; envAllowList?: string[]; stderrMode?: 'inherit' \| 'capture' \| 'artifact'; } \| { type: 'streamable_http'; endpoint: string; headersRef?: string; authorizationRef?: string; sessionMode?: 'protocol_default' \| 'stateless'; } \| { type: 'custom'; adapterRef: string; config?: Record<string, unknown>; }`	MCP Transport Spec 公共类型别名；完整类型表达式见声明。
`NormalizedMCPErrorCode`	类型	`type NormalizedMCPErrorCode = (typeof NORMALIZED_MCP_ERROR_CODES)[number]`	Normalized MCP Error Code 公共类型别名；完整类型表达式见声明。

`governedMCPIntegrationDefinition`

由 contracts 模块导出的 Governed MCP Integration Definition 常量。

种类: 常量
导入: import { governedMCPIntegrationDefinition } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export declare const governedMCPIntegrationDefinition: SpecSchemaDefinition<GovernedMCPIntegrationSpec>;

`governedMCPIntegrationExample`

Governed MCP Integration 的有效示例值。

种类: 常量
导入: import { governedMCPIntegrationExample } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export declare const governedMCPIntegrationExample: GovernedMCPIntegrationSpec;

`governedMCPIntegrationJsonSchema`

Governed MCP Integration 的 JSON Schema。

种类: 常量
导入: import { governedMCPIntegrationJsonSchema } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export declare const governedMCPIntegrationJsonSchema: JsonSchema;

`governedMCPIntegrationJsonSchemas`

由 contracts 模块导出的 Governed MCP Integration JSON Schemas 常量。

种类: 常量
导入: import { governedMCPIntegrationJsonSchemas } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export declare const governedMCPIntegrationJsonSchemas: Record<string, JsonSchema>;

`governedMCPIntegrationSpecSchema`

Governed MCP Integration Spec 的运行时 Schema。

种类: 常量
导入: import { governedMCPIntegrationSpecSchema } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

// 精确类型由包入口解析；完整编译器展开定义见源码链接。
export declare const governedMCPIntegrationSpecSchema: (typeof import('@codesoul-co/hypha-mcp'))['governedMCPIntegrationSpecSchema'];

该常量的编译器展开类型已压缩；它的公共名称、顶层类型与源码位置仍保留在本条目中。相关输入/输出字段请使用同模块导出的接口、类型或 Runtime Schema。

`mcpCapabilityDriftPolicySpecSchema`

MCP Capability Drift Policy Spec 的运行时 Schema。

种类: 常量
导入: import { mcpCapabilityDriftPolicySpecSchema } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export declare const mcpCapabilityDriftPolicySpecSchema: z.ZodObject<{ onDescriptionChange: z.ZodEnum<["accept", "snapshot_next_run", "quarantine"]>; onSchemaChange: z.ZodEnum<["snapshot_next_run", "quarantine", "require_approval"]>; onRemoval: z.ZodEnum<["mark_unavailable", "allow_existing_run", "fail_existing_run"]>; onServerIdentityChange: z.ZodEnum<["disconnect", "quarantine"]>; notifyRuntime: z.ZodOptional<z.ZodBoolean>; invalidateSchemaCache: z.ZodOptional<z.ZodBoolean>; }, "strip", z.ZodTypeAny, { onDescriptionChange: "quarantine" | "accept" | "snapshot_next_run"; onSchemaChange: "quarantine" | "snapshot_next_run" | "require_approval"; onRemoval: "mark_unavailable" | "allow_existing_run" | "fail_existing_run"; onServerIdentityChange: "quarantine" | "disconnect"; notifyRuntime?: boolean | undefined; invalidateSchemaCache?: boolean | undefined; }, { onDescriptionChange: "quarantine" | "accept" | "snapshot_next_run"; onSchemaChange: "quarantine" | "snapshot_next_run" | "require_approval"; onRemoval: "mark_unavailable" | "allow_existing_run" | "fail_existing_run"; onServerIdentityChange: "quarantine" | "disconnect"; notifyRuntime?: boolean | undefined; invalidateSchemaCache?: boolean | undefined; }>;

`mcpServerProfileSchema`

MCP Server Profile 的运行时 Schema。

种类: 常量
导入: import { mcpServerProfileSchema } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

// 精确类型由包入口解析；完整编译器展开定义见源码链接。
export declare const mcpServerProfileSchema: (typeof import('@codesoul-co/hypha-mcp'))['mcpServerProfileSchema'];

该常量的编译器展开类型已压缩；它的公共名称、顶层类型与源码位置仍保留在本条目中。相关输入/输出字段请使用同模块导出的接口、类型或 Runtime Schema。

`mcpTransportSpecSchema`

MCP Transport Spec 的运行时 Schema。

种类: 常量
导入: import { mcpTransportSpecSchema } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export declare const mcpTransportSpecSchema: z.ZodType<MCPTransportSpec, z.ZodTypeDef, MCPTransportSpec>;

`mcpTrustPolicySpecSchema`

MCP Trust Policy Spec 的运行时 Schema。

种类: 常量
导入: import { mcpTrustPolicySpecSchema } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export declare const mcpTrustPolicySpecSchema: z.ZodObject<{ defaultTrustLevel: z.ZodEnum<["untrusted", "restricted", "trusted"]>; trustedSourceRefs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; requireAdminApprovalForNewServer: z.ZodOptional<z.ZodBoolean>; requireApprovalForNewCapability: z.ZodOptional<z.ZodBoolean>; requireApprovalForSchemaChange: z.ZodOptional<z.ZodBoolean>; allowServerDeclaredSideEffectHints: z.ZodOptional<z.ZodBoolean>; pinServerIdentity: z.ZodOptional<z.ZodBoolean>; pinProtocolVersion: z.ZodOptional<z.ZodBoolean>; pinCapabilityHashes: z.ZodOptional<z.ZodBoolean>; }, "strip", z.ZodTypeAny, { defaultTrustLevel: "trusted" | "untrusted" | "restricted"; trustedSourceRefs?: string[] | undefined; requireAdminApprovalForNewServer?: boolean | undefined; requireApprovalForNewCapability?: boolean | undefined; requireApprovalForSchemaChange?: boolean | undefined; allowServerDeclaredSideEffectHints?: boolean | undefined; pinServerIdentity?: boolean | undefined; pinProtocolVersion?: boolean | undefined; pinCapabilityHashes?: boolean | undefined; }, { defaultTrustLevel: "trusted" | "untrusted" | "restricted"; trustedSourceRefs?: string[] | undefined; requireAdminApprovalForNewServer?: boolean | undefined; requireApprovalForNewCapability?: boolean | undefined; requireApprovalForSchemaChange?: boolean | undefined; allowServerDeclaredSideEffectHints?: boolean | undefined; pinServerIdentity?: boolean | undefined; pinProtocolVersion?: boolean | undefined; pinCapabilityHashes?: boolean | undefined; }>;

`NORMALIZED_MCP_ERROR_CODES`

由 contracts 模块导出的 NORMALIZED MCP ERROR CODES 常量。

种类: 常量
导入: import { NORMALIZED_MCP_ERROR_CODES } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export declare const NORMALIZED_MCP_ERROR_CODES: readonly ["MCP_SERVER_NOT_FOUND", "MCP_CONNECTION_FAILED", "MCP_INITIALIZATION_FAILED", "MCP_PROTOCOL_MISMATCH", "MCP_REQUEST_TIMEOUT", "MCP_REQUEST_CANCELLED", "MCP_CAPABILITY_NOT_FOUND", "MCP_CAPABILITY_QUARANTINED", "MCP_CAPABILITY_DRIFT", "MCP_SCHEMA_INVALID", "MCP_AUTH_FAILED", "MCP_BULKHEAD_REJECTED", "MCP_RATE_LIMITED", "MCP_CIRCUIT_OPEN", "MCP_EGRESS_DENIED", "MCP_CONTENT_TOO_LARGE", "MCP_REMOTE_ERROR", "MCP_TRANSPORT_CLOSED", "MCP_INTERNAL_ERROR"];

`normalizedMCPErrorDefinition`

由 contracts 模块导出的 Normalized MCP Error Definition 常量。

种类: 常量
导入: import { normalizedMCPErrorDefinition } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export declare const normalizedMCPErrorDefinition: SpecSchemaDefinition<NormalizedMCPError>;

`normalizedMCPErrorExample`

Normalized MCP Error 的有效示例值。

种类: 常量
导入: import { normalizedMCPErrorExample } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export declare const normalizedMCPErrorExample: NormalizedMCPError;

`normalizedMCPErrorJsonSchema`

Normalized MCP Error 的 JSON Schema。

种类: 常量
导入: import { normalizedMCPErrorJsonSchema } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export declare const normalizedMCPErrorJsonSchema: JsonSchema;

`normalizedMCPErrorSchema`

Normalized MCP Error 的运行时 Schema。

种类: 常量
导入: import { normalizedMCPErrorSchema } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export declare const normalizedMCPErrorSchema: z.ZodObject<{ code: z.ZodEnum<["MCP_SERVER_NOT_FOUND", "MCP_CONNECTION_FAILED", "MCP_INITIALIZATION_FAILED", "MCP_PROTOCOL_MISMATCH", "MCP_REQUEST_TIMEOUT", "MCP_REQUEST_CANCELLED", "MCP_CAPABILITY_NOT_FOUND", "MCP_CAPABILITY_QUARANTINED", "MCP_CAPABILITY_DRIFT", "MCP_SCHEMA_INVALID", "MCP_AUTH_FAILED", "MCP_BULKHEAD_REJECTED", "MCP_RATE_LIMITED", "MCP_CIRCUIT_OPEN", "MCP_EGRESS_DENIED", "MCP_CONTENT_TOO_LARGE", "MCP_REMOTE_ERROR", "MCP_TRANSPORT_CLOSED", "MCP_INTERNAL_ERROR"]>; message: z.ZodString; retryable: z.ZodBoolean; serverId: z.ZodOptional<z.ZodString>; capabilityId: z.ZodOptional<z.ZodString>; remoteCode: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>; details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, "strict", z.ZodTypeAny, { code: "MCP_SERVER_NOT_FOUND" | "MCP_CONNECTION_FAILED" | "MCP_INITIALIZATION_FAILED" | "MCP_PROTOCOL_MISMATCH" | "MCP_REQUEST_TIMEOUT" | "MCP_REQUEST_CANCELLED" | "MCP_CAPABILITY_NOT_FOUND" | "MCP_CAPABILITY_QUARANTINED" | "MCP_CAPABILITY_DRIFT" | "MCP_SCHEMA_INVALID" | "MCP_AUTH_FAILED" | "MCP_BULKHEAD_REJECTED" | "MCP_RATE_LIMITED" | "MCP_CIRCUIT_OPEN" | "MCP_EGRESS_DENIED" | "MCP_CONTENT_TOO_LARGE" | "MCP_REMOTE_ERROR" | "MCP_TRANSPORT_CLOSED" | "MCP_INTERNAL_ERROR"; message: string; retryable: boolean; serverId?: string | undefined; capabilityId?: string | undefined; remoteCode?: string | number | undefined; details?: Record<string, unknown> | undefined; }, { code: "MCP_SERVER_NOT_FOUND" | "MCP_CONNECTION_FAILED" | "MCP_INITIALIZATION_FAILED" | "MCP_PROTOCOL_MISMATCH" | "MCP_REQUEST_TIMEOUT" | "MCP_REQUEST_CANCELLED" | "MCP_CAPABILITY_NOT_FOUND" | "MCP_CAPABILITY_QUARANTINED" | "MCP_CAPABILITY_DRIFT" | "MCP_SCHEMA_INVALID" | "MCP_AUTH_FAILED" | "MCP_BULKHEAD_REJECTED" | "MCP_RATE_LIMITED" | "MCP_CIRCUIT_OPEN" | "MCP_EGRESS_DENIED" | "MCP_CONTENT_TOO_LARGE" | "MCP_REMOTE_ERROR" | "MCP_TRANSPORT_CLOSED" | "MCP_INTERNAL_ERROR"; message: string; retryable: boolean; serverId?: string | undefined; capabilityId?: string | undefined; remoteCode?: string | number | undefined; details?: Record<string, unknown> | undefined; }>;

`GovernedMCPIntegrationSpec`

Governed MCP Integration Spec 接口，共包含 16 个公开字段或方法。

种类: 接口
导入: import type { GovernedMCPIntegrationSpec } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export interface GovernedMCPIntegrationSpec {
    id: string;
    version: string;
    revision?: string;
    name?: string;
    description?: string;
    servers: MCPServerProfile[];
    allowCapabilities?: MCPAllowDenyRule[];
    denyCapabilities?: MCPAllowDenyRule[];
    trustPolicy: MCPTrustPolicySpec;
    importPolicy: MCPImportPolicySpec;
    driftPolicy: MCPCapabilityDriftPolicySpec;
    snapshotPolicy: MCPContractSnapshotPolicySpec;
    toolPolicyRefs?: Array<{
        id: string;
        version?: string;
        revision?: string;
    }>;
    resourcePolicyRefs?: Array<{
        id: string;
        version?: string;
        revision?: string;
    }>;
    promptPolicyRefs?: Array<{
        id: string;
        version?: string;
        revision?: string;
    }>;
    metadata?: Record<string, unknown>;
}

契约成员

成员	种类	签名	说明
`allowCapabilities`	属性	`allowCapabilities?: MCPAllowDenyRule[]`	公开属性；类型、只读和可选状态以签名列为准。
`denyCapabilities`	属性	`denyCapabilities?: MCPAllowDenyRule[]`	公开属性；类型、只读和可选状态以签名列为准。
`description`	属性	`description?: string`	公开属性；类型、只读和可选状态以签名列为准。
`driftPolicy`	属性	`driftPolicy: MCPCapabilityDriftPolicySpec`	公开属性；类型、只读和可选状态以签名列为准。
`id`	属性	`id: string`	公开属性；类型、只读和可选状态以签名列为准。
`importPolicy`	属性	`importPolicy: MCPImportPolicySpec`	公开属性；类型、只读和可选状态以签名列为准。
`metadata`	属性	`metadata?: Record<string, unknown>`	公开属性；类型、只读和可选状态以签名列为准。
`name`	属性	`name?: string`	公开属性；类型、只读和可选状态以签名列为准。
`promptPolicyRefs`	属性	`promptPolicyRefs?: { id: string; version?: string; revision?: string; }[]`	公开属性；类型、只读和可选状态以签名列为准。
`resourcePolicyRefs`	属性	`resourcePolicyRefs?: { id: string; version?: string; revision?: string; }[]`	公开属性；类型、只读和可选状态以签名列为准。
`revision`	属性	`revision?: string`	公开属性；类型、只读和可选状态以签名列为准。
`servers`	属性	`servers: MCPServerProfile[]`	公开属性；类型、只读和可选状态以签名列为准。
`snapshotPolicy`	属性	`snapshotPolicy: MCPContractSnapshotPolicySpec`	公开属性；类型、只读和可选状态以签名列为准。
`toolPolicyRefs`	属性	`toolPolicyRefs?: { id: string; version?: string; revision?: string; }[]`	公开属性；类型、只读和可选状态以签名列为准。
`trustPolicy`	属性	`trustPolicy: MCPTrustPolicySpec`	公开属性；类型、只读和可选状态以签名列为准。
`version`	属性	`version: string`	公开属性；类型、只读和可选状态以签名列为准。

`MCPAllowDenyRule`

MCP Allow Deny Rule 接口，共包含 4 个公开字段或方法。

种类: 接口
导入: import type { MCPAllowDenyRule } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export interface MCPAllowDenyRule {
    serverId?: string;
    capabilityId?: string;
    kind?: 'tool' | 'resource' | 'prompt';
    tags?: string[];
}

契约成员

成员	种类	签名	说明
`capabilityId`	属性	`capabilityId?: string`	公开属性；类型、只读和可选状态以签名列为准。
`kind`	属性	`kind?: "tool" \| "prompt" \| "resource"`	公开属性；类型、只读和可选状态以签名列为准。
`serverId`	属性	`serverId?: string`	公开属性；类型、只读和可选状态以签名列为准。
`tags`	属性	`tags?: string[]`	公开属性；类型、只读和可选状态以签名列为准。

`MCPCapabilityDriftPolicySpec`

MCP Capability Drift Policy Spec 接口，共包含 6 个公开字段或方法。

种类: 接口
导入: import type { MCPCapabilityDriftPolicySpec } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export interface MCPCapabilityDriftPolicySpec {
    onDescriptionChange: 'accept' | 'snapshot_next_run' | 'quarantine';
    onSchemaChange: 'snapshot_next_run' | 'quarantine' | 'require_approval';
    onRemoval: 'mark_unavailable' | 'allow_existing_run' | 'fail_existing_run';
    onServerIdentityChange: 'disconnect' | 'quarantine';
    notifyRuntime?: boolean;
    invalidateSchemaCache?: boolean;
}

契约成员

成员	种类	签名	说明
`invalidateSchemaCache`	属性	`invalidateSchemaCache?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`notifyRuntime`	属性	`notifyRuntime?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`onDescriptionChange`	属性	`onDescriptionChange: "quarantine" \| "accept" \| "snapshot_next_run"`	公开属性；类型、只读和可选状态以签名列为准。
`onRemoval`	属性	`onRemoval: "mark_unavailable" \| "allow_existing_run" \| "fail_existing_run"`	公开属性；类型、只读和可选状态以签名列为准。
`onSchemaChange`	属性	`onSchemaChange: "quarantine" \| "snapshot_next_run" \| "require_approval"`	公开属性；类型、只读和可选状态以签名列为准。
`onServerIdentityChange`	属性	`onServerIdentityChange: "quarantine" \| "disconnect"`	公开属性；类型、只读和可选状态以签名列为准。

`MCPCapabilityTrustRecord`

MCP Capability Trust Record 接口，共包含 7 个公开字段或方法。

种类: 接口
导入: import type { MCPCapabilityTrustRecord } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export interface MCPCapabilityTrustRecord {
    level: 'untrusted' | 'restricted' | 'trusted';
    source: 'admin' | 'domain_pack' | 'runtime_discovery' | 'signed_manifest' | 'import';
    sourceRef?: string;
    approvedBy?: string;
    approvedAt?: string;
    restrictions?: string[];
    metadata?: Record<string, unknown>;
}

契约成员

成员	种类	签名	说明
`approvedAt`	属性	`approvedAt?: string`	公开属性；类型、只读和可选状态以签名列为准。
`approvedBy`	属性	`approvedBy?: string`	公开属性；类型、只读和可选状态以签名列为准。
`level`	属性	`level: "trusted" \| "untrusted" \| "restricted"`	公开属性；类型、只读和可选状态以签名列为准。
`metadata`	属性	`metadata?: Record<string, unknown>`	公开属性；类型、只读和可选状态以签名列为准。
`restrictions`	属性	`restrictions?: string[]`	公开属性；类型、只读和可选状态以签名列为准。
`source`	属性	`source: "import" \| "admin" \| "domain_pack" \| "runtime_discovery" \| "signed_manifest"`	公开属性；类型、只读和可选状态以签名列为准。
`sourceRef`	属性	`sourceRef?: string`	公开属性；类型、只读和可选状态以签名列为准。

`MCPContractSnapshotPolicySpec`

MCP Contract Snapshot Policy Spec 接口，共包含 3 个公开字段或方法。

种类: 接口
导入: import type { MCPContractSnapshotPolicySpec } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export interface MCPContractSnapshotPolicySpec {
    mode: 'run' | 'state';
    preserveRemovedForExistingRuns?: boolean;
    requireApprovedRevision?: boolean;
}

契约成员

成员	种类	签名	说明
`mode`	属性	`mode: "run" \| "state"`	公开属性；类型、只读和可选状态以签名列为准。
`preserveRemovedForExistingRuns`	属性	`preserveRemovedForExistingRuns?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`requireApprovedRevision`	属性	`requireApprovedRevision?: boolean`	公开属性；类型、只读和可选状态以签名列为准。

`MCPImportPolicySpec`

MCP Import Policy Spec 接口，共包含 4 个公开字段或方法。

种类: 接口
导入: import type { MCPImportPolicySpec } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export interface MCPImportPolicySpec {
    kinds: Array<'tool' | 'resource' | 'prompt'>;
    lazyLoad?: boolean;
    maxLoadedCapabilities?: number;
    schemaTokenBudget?: number;
}

契约成员

成员	种类	签名	说明
`kinds`	属性	`kinds: ("tool" \| "prompt" \| "resource")[]`	公开属性；类型、只读和可选状态以签名列为准。
`lazyLoad`	属性	`lazyLoad?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`maxLoadedCapabilities`	属性	`maxLoadedCapabilities?: number`	公开属性；类型、只读和可选状态以签名列为准。
`schemaTokenBudget`	属性	`schemaTokenBudget?: number`	公开属性；类型、只读和可选状态以签名列为准。

`MCPServerProfile`

MCP Server Profile 接口，共包含 22 个公开字段或方法。

种类: 接口
导入: import type { MCPServerProfile } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export interface MCPServerProfile {
    id: string;
    version?: string;
    displayName?: string;
    mode: 'fixture' | 'local' | 'remote';
    transport: MCPTransportSpec;
    authRef?: string;
    environmentRefs?: string[];
    workingDirectoryRef?: string;
    autoConnect?: boolean;
    lazyConnect?: boolean;
    singleStart?: boolean;
    initializationTimeoutMs?: number;
    requestTimeoutMs?: number;
    shutdownTimeoutMs?: number;
    reconnectPolicy?: RetryPolicySpec;
    healthCheckPolicy?: {
        intervalMs?: number;
        timeoutMs?: number;
        unhealthyThreshold?: number;
    };
    expectedServerInfo?: Record<string, unknown>;
    protocolVersionPolicy?: {
        allowedVersions?: string[];
        preferLatest?: boolean;
        rejectUnknown?: boolean;
    };
    egressPolicy?: {
        allowedHosts?: string[];
        denyPrivateNetworks?: boolean;
        requireTls?: boolean;
        maxRedirects?: number;
        allowCrossOriginRedirects?: boolean;
    };
    requestGuardPolicy?: {
        maxConcurrentRequests?: number;
        rateLimit?: {
            maxRequests: number;
            windowMs: number;
        };
        circuitBreaker?: {
            failureThreshold: number;
            resetAfterMs: number;
        };
    };
    contentPolicy?: {
        maxToolResultBytes?: number;
        maxResourceBytes?: number;
        maxPromptBytes?: number;
        maxPromptTokens?: number;
        oversizeAction?: 'reject' | 'artifact';
    };
    metadata?: Record<string, unknown>;
}

契约成员

成员	种类	签名	说明
`authRef`	属性	`authRef?: string`	公开属性；类型、只读和可选状态以签名列为准。
`autoConnect`	属性	`autoConnect?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`contentPolicy`	属性	`contentPolicy?: { maxToolResultBytes?: number; maxResourceBytes?: number; maxPromptBytes?: number; maxPromptTokens?: number; oversizeAction?: "reject" \| "artifact"; }`	公开属性；类型、只读和可选状态以签名列为准。
`displayName`	属性	`displayName?: string`	公开属性；类型、只读和可选状态以签名列为准。
`egressPolicy`	属性	`egressPolicy?: { allowedHosts?: string[]; denyPrivateNetworks?: boolean; requireTls?: boolean; maxRedirects?: number; allowCrossOriginRedirects?: boolean; }`	公开属性；类型、只读和可选状态以签名列为准。
`environmentRefs`	属性	`environmentRefs?: string[]`	公开属性；类型、只读和可选状态以签名列为准。
`expectedServerInfo`	属性	`expectedServerInfo?: Record<string, unknown>`	公开属性；类型、只读和可选状态以签名列为准。
`healthCheckPolicy`	属性	`healthCheckPolicy?: { intervalMs?: number; timeoutMs?: number; unhealthyThreshold?: number; }`	公开属性；类型、只读和可选状态以签名列为准。
`id`	属性	`id: string`	公开属性；类型、只读和可选状态以签名列为准。
`initializationTimeoutMs`	属性	`initializationTimeoutMs?: number`	公开属性；类型、只读和可选状态以签名列为准。
`lazyConnect`	属性	`lazyConnect?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`metadata`	属性	`metadata?: Record<string, unknown>`	公开属性；类型、只读和可选状态以签名列为准。
`mode`	属性	`mode: "local" \| "remote" \| "fixture"`	公开属性；类型、只读和可选状态以签名列为准。
`protocolVersionPolicy`	属性	`protocolVersionPolicy?: { allowedVersions?: string[]; preferLatest?: boolean; rejectUnknown?: boolean; }`	公开属性；类型、只读和可选状态以签名列为准。
`reconnectPolicy`	属性	`reconnectPolicy?: RetryPolicySpec`	公开属性；类型、只读和可选状态以签名列为准。
`requestGuardPolicy`	属性	`requestGuardPolicy?: { maxConcurrentRequests?: number; rateLimit?: { maxRequests: number; windowMs: number; }; circuitBreaker?: { failureThreshold: number; resetAfterMs: number; }; }`	公开属性；类型、只读和可选状态以签名列为准。
`requestTimeoutMs`	属性	`requestTimeoutMs?: number`	公开属性；类型、只读和可选状态以签名列为准。
`shutdownTimeoutMs`	属性	`shutdownTimeoutMs?: number`	公开属性；类型、只读和可选状态以签名列为准。
`singleStart`	属性	`singleStart?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`transport`	属性	`transport: MCPTransportSpec`	公开属性；类型、只读和可选状态以签名列为准。
`version`	属性	`version?: string`	公开属性；类型、只读和可选状态以签名列为准。
`workingDirectoryRef`	属性	`workingDirectoryRef?: string`	公开属性；类型、只读和可选状态以签名列为准。

`MCPTrustPolicySpec`

MCP Trust Policy Spec 接口，共包含 9 个公开字段或方法。

种类: 接口
导入: import type { MCPTrustPolicySpec } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export interface MCPTrustPolicySpec {
    defaultTrustLevel: 'untrusted' | 'restricted' | 'trusted';
    trustedSourceRefs?: string[];
    requireAdminApprovalForNewServer?: boolean;
    requireApprovalForNewCapability?: boolean;
    requireApprovalForSchemaChange?: boolean;
    allowServerDeclaredSideEffectHints?: boolean;
    pinServerIdentity?: boolean;
    pinProtocolVersion?: boolean;
    pinCapabilityHashes?: boolean;
}

契约成员

成员	种类	签名	说明
`allowServerDeclaredSideEffectHints`	属性	`allowServerDeclaredSideEffectHints?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`defaultTrustLevel`	属性	`defaultTrustLevel: "trusted" \| "untrusted" \| "restricted"`	公开属性；类型、只读和可选状态以签名列为准。
`pinCapabilityHashes`	属性	`pinCapabilityHashes?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`pinProtocolVersion`	属性	`pinProtocolVersion?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`pinServerIdentity`	属性	`pinServerIdentity?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`requireAdminApprovalForNewServer`	属性	`requireAdminApprovalForNewServer?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`requireApprovalForNewCapability`	属性	`requireApprovalForNewCapability?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`requireApprovalForSchemaChange`	属性	`requireApprovalForSchemaChange?: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`trustedSourceRefs`	属性	`trustedSourceRefs?: string[]`	公开属性；类型、只读和可选状态以签名列为准。

`NormalizedMCPError`

Normalized MCP Error 接口，共包含 7 个公开字段或方法。

种类: 接口
导入: import type { NormalizedMCPError } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export interface NormalizedMCPError {
    code: NormalizedMCPErrorCode;
    message: string;
    retryable: boolean;
    serverId?: string;
    capabilityId?: string;
    remoteCode?: string | number;
    details?: Record<string, unknown>;
}

契约成员

成员	种类	签名	说明
`capabilityId`	属性	`capabilityId?: string`	公开属性；类型、只读和可选状态以签名列为准。
`code`	属性	`code: "MCP_SERVER_NOT_FOUND" \| "MCP_CONNECTION_FAILED" \| "MCP_INITIALIZATION_FAILED" \| "MCP_PROTOCOL_MISMATCH" \| "MCP_REQUEST_TIMEOUT" \| "MCP_REQUEST_CANCELLED" \| "MCP_CAPABILITY_NOT_FOUND" \| "MCP_CAPABILITY_QUARANTINED" \| "MCP_CAPABILITY_DRIFT" \| "MCP_SCHEMA_INVALID" \| "MCP_AUTH_FAILED" \| "MCP_BULKHEAD_REJECTED" \| "MCP_RATE_LIMITED" \| "MCP_CIRCUIT_OPEN" \| "MCP_EGRESS_DENIED" \| "MCP_CONTENT_TOO_LARGE" \| "MCP_REMOT...`	公开属性；类型、只读和可选状态以签名列为准。
`details`	属性	`details?: Record<string, unknown>`	公开属性；类型、只读和可选状态以签名列为准。
`message`	属性	`message: string`	公开属性；类型、只读和可选状态以签名列为准。
`remoteCode`	属性	`remoteCode?: string \| number`	公开属性；类型、只读和可选状态以签名列为准。
`retryable`	属性	`retryable: boolean`	公开属性；类型、只读和可选状态以签名列为准。
`serverId`	属性	`serverId?: string`	公开属性；类型、只读和可选状态以签名列为准。

`MCPTransportSpec`

MCP Transport Spec 公共类型别名；完整类型表达式见声明。

种类: 类型
导入: import type { MCPTransportSpec } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export type MCPTransportSpec = {
    type: 'stdio';
    command: string;
    args?: string[];
    envAllowList?: string[];
    stderrMode?: 'inherit' | 'capture' | 'artifact';
} | {
    type: 'streamable_http';
    endpoint: string;
    headersRef?: string;
    authorizationRef?: string;
    sessionMode?: 'protocol_default' | 'stateless';
} | {
    type: 'custom';
    adapterRef: string;
    config?: Record<string, unknown>;
};

`NormalizedMCPErrorCode`

Normalized MCP Error Code 公共类型别名；完整类型表达式见声明。

种类: 类型
导入: import type { NormalizedMCPErrorCode } from '@codesoul-co/hypha-mcp';
源码模块: contracts

声明

text

export type NormalizedMCPErrorCode = (typeof NORMALIZED_MCP_ERROR_CODES)[number];

@codesoul-co/hypha-mcp / contracts ​

模块用法 ​

从包入口导入 ​

使用要点 ​

运行时校验示例 ​

公共导出 ​

governedMCPIntegrationDefinition ​

声明 ​

governedMCPIntegrationExample ​

声明 ​

governedMCPIntegrationJsonSchema ​

声明 ​

governedMCPIntegrationJsonSchemas ​

声明 ​

governedMCPIntegrationSpecSchema ​

声明 ​

mcpCapabilityDriftPolicySpecSchema ​

声明 ​

mcpServerProfileSchema ​

声明 ​

mcpTransportSpecSchema ​

声明 ​

mcpTrustPolicySpecSchema ​

声明 ​

NORMALIZED_MCP_ERROR_CODES ​

声明 ​

normalizedMCPErrorDefinition ​

声明 ​

normalizedMCPErrorExample ​

声明 ​

normalizedMCPErrorJsonSchema ​

声明 ​

normalizedMCPErrorSchema ​

声明 ​

GovernedMCPIntegrationSpec ​

声明 ​

契约成员 ​

MCPAllowDenyRule ​

声明 ​

契约成员 ​

MCPCapabilityDriftPolicySpec ​

声明 ​

契约成员 ​

MCPCapabilityTrustRecord ​

声明 ​

契约成员 ​

MCPContractSnapshotPolicySpec ​

声明 ​

契约成员 ​

MCPImportPolicySpec ​

声明 ​

契约成员 ​

MCPServerProfile ​

声明 ​

契约成员 ​

MCPTrustPolicySpec ​

声明 ​

契约成员 ​

NormalizedMCPError ​

声明 ​

契约成员 ​

MCPTransportSpec ​

声明 ​

NormalizedMCPErrorCode ​

声明 ​

`@codesoul-co/hypha-mcp` / `contracts`

模块用法

从包入口导入

使用要点

运行时校验示例

公共导出

`governedMCPIntegrationDefinition`

声明

`governedMCPIntegrationExample`

声明

`governedMCPIntegrationJsonSchema`

声明

`governedMCPIntegrationJsonSchemas`

声明

`governedMCPIntegrationSpecSchema`

声明

`mcpCapabilityDriftPolicySpecSchema`

声明

`mcpServerProfileSchema`

声明

`mcpTransportSpecSchema`

声明

`mcpTrustPolicySpecSchema`

声明

`NORMALIZED_MCP_ERROR_CODES`

声明

`normalizedMCPErrorDefinition`

声明

`normalizedMCPErrorExample`

声明

`normalizedMCPErrorJsonSchema`

声明

`normalizedMCPErrorSchema`

声明

`GovernedMCPIntegrationSpec`

声明

契约成员

`MCPAllowDenyRule`

声明

契约成员

`MCPCapabilityDriftPolicySpec`

声明

契约成员

`MCPCapabilityTrustRecord`

声明

契约成员

`MCPContractSnapshotPolicySpec`

声明

契约成员

`MCPImportPolicySpec`

声明

契约成员

`MCPServerProfile`

声明

契约成员

`MCPTrustPolicySpec`

声明

契约成员

`NormalizedMCPError`

声明

契约成员

`MCPTransportSpec`

声明

`NormalizedMCPErrorCode`

声明