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

Using this module

Use the Contracts module for declaring and runtime-validating contracts. It exports 14 constants, 9 interfaces, 2 types.

Import from the package entrypoint

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';

// The complete export list is documented below.

Usage patterns

Use the 11 type/interface exports as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.
The 14 constant/enum exports provide stable values, schemas, definitions, or defaults. Reuse these exports instead of copying internal values into an application.

Runtime validation example

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

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

Parse untrusted configuration, network, or persisted input with the runtime schema before passing it to functions or classes that expect a validated contract.

Public exports

Symbol	Kind	Signature	Description
`governedMCPIntegrationDefinition`	constant	`const governedMCPIntegrationDefinition: SpecSchemaDefinition<GovernedMCPIntegrationSpec>`	Governed MCP Integration Definition constant exported by the `contracts` module.
`governedMCPIntegrationExample`	constant	`const governedMCPIntegrationExample: GovernedMCPIntegrationSpec`	Valid example value for Governed MCP Integration.
`governedMCPIntegrationJsonSchema`	constant	`const governedMCPIntegrationJsonSchema: JsonSchema`	JSON Schema for Governed MCP Integration.
`governedMCPIntegrationJsonSchemas`	constant	`const governedMCPIntegrationJsonSchemas: Record<string, JsonSchema>`	Governed MCP Integration JSON Schemas constant exported by the `contracts` module.
`governedMCPIntegrationSpecSchema`	constant	`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...`	Runtime schema for Governed MCP Integration Spec.
`mcpCapabilityDriftPolicySpecSchema`	constant	`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...`	Runtime schema for MCP Capability Drift Policy Spec.
`mcpServerProfileSchema`	constant	`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...`	Runtime schema for MCP Server Profile.
`mcpTransportSpecSchema`	constant	`const mcpTransportSpecSchema: z.ZodType<MCPTransportSpec, z.ZodTypeDef, MCPTransportSpec>`	Runtime schema for MCP Transport Spec.
`mcpTrustPolicySpecSchema`	constant	`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...`	Runtime schema for MCP Trust Policy Spec.
`NORMALIZED_MCP_ERROR_CODES`	constant	`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_...`	NORMALIZED MCP ERROR CODES constant exported by the `contracts` module.
`normalizedMCPErrorDefinition`	constant	`const normalizedMCPErrorDefinition: SpecSchemaDefinition<NormalizedMCPError>`	Normalized MCP Error Definition constant exported by the `contracts` module.
`normalizedMCPErrorExample`	constant	`const normalizedMCPErrorExample: NormalizedMCPError`	Valid example value for Normalized MCP Error.
`normalizedMCPErrorJsonSchema`	constant	`const normalizedMCPErrorJsonSchema: JsonSchema`	JSON Schema for Normalized MCP Error.
`normalizedMCPErrorSchema`	constant	`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...`	Runtime schema for Normalized MCP Error.
`GovernedMCPIntegrationSpec`	interface	`interface GovernedMCPIntegrationSpec`	Governed MCP Integration Spec interface with 16 public fields or methods.
`MCPAllowDenyRule`	interface	`interface MCPAllowDenyRule`	MCP Allow Deny Rule interface with 4 public fields or methods.
`MCPCapabilityDriftPolicySpec`	interface	`interface MCPCapabilityDriftPolicySpec`	MCP Capability Drift Policy Spec interface with 6 public fields or methods.
`MCPCapabilityTrustRecord`	interface	`interface MCPCapabilityTrustRecord`	MCP Capability Trust Record interface with 7 public fields or methods.
`MCPContractSnapshotPolicySpec`	interface	`interface MCPContractSnapshotPolicySpec`	MCP Contract Snapshot Policy Spec interface with 3 public fields or methods.
`MCPImportPolicySpec`	interface	`interface MCPImportPolicySpec`	MCP Import Policy Spec interface with 4 public fields or methods.
`MCPServerProfile`	interface	`interface MCPServerProfile`	MCP Server Profile interface with 22 public fields or methods.
`MCPTrustPolicySpec`	interface	`interface MCPTrustPolicySpec`	MCP Trust Policy Spec interface with 9 public fields or methods.
`NormalizedMCPError`	interface	`interface NormalizedMCPError`	Normalized MCP Error interface with 7 public fields or methods.
`MCPTransportSpec`	type	`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>; }`	Public type alias for MCP Transport Spec; the declaration contains its complete type expression.
`NormalizedMCPErrorCode`	type	`type NormalizedMCPErrorCode = (typeof NORMALIZED_MCP_ERROR_CODES)[number]`	Public type alias for Normalized MCP Error Code; the declaration contains its complete type expression.

`governedMCPIntegrationDefinition`

Governed MCP Integration Definition constant exported by the contracts module.

Kind: constant
Import: import { governedMCPIntegrationDefinition } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

export declare const governedMCPIntegrationDefinition: SpecSchemaDefinition<GovernedMCPIntegrationSpec>;

`governedMCPIntegrationExample`

Valid example value for Governed MCP Integration.

Kind: constant
Import: import { governedMCPIntegrationExample } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

export declare const governedMCPIntegrationExample: GovernedMCPIntegrationSpec;

`governedMCPIntegrationJsonSchema`

JSON Schema for Governed MCP Integration.

Kind: constant
Import: import { governedMCPIntegrationJsonSchema } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

export declare const governedMCPIntegrationJsonSchema: JsonSchema;

`governedMCPIntegrationJsonSchemas`

Governed MCP Integration JSON Schemas constant exported by the contracts module.

Kind: constant
Import: import { governedMCPIntegrationJsonSchemas } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

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

`governedMCPIntegrationSpecSchema`

Runtime schema for Governed MCP Integration Spec.

Kind: constant
Import: import { governedMCPIntegrationSpecSchema } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

// Exact type resolved from the package entrypoint; see source for the compiler expansion.
export declare const governedMCPIntegrationSpecSchema: (typeof import('@codesoul-co/hypha-mcp'))['governedMCPIntegrationSpecSchema'];

This compiler-expanded constant type is compacted. Its public name, top-level type, and source location remain here; use the module’s exported interfaces, types, or runtime schema for input/output fields.

`mcpCapabilityDriftPolicySpecSchema`

Runtime schema for MCP Capability Drift Policy Spec.

Kind: constant
Import: import { mcpCapabilityDriftPolicySpecSchema } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

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`

Runtime schema for MCP Server Profile.

Kind: constant
Import: import { mcpServerProfileSchema } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

// Exact type resolved from the package entrypoint; see source for the compiler expansion.
export declare const mcpServerProfileSchema: (typeof import('@codesoul-co/hypha-mcp'))['mcpServerProfileSchema'];

This compiler-expanded constant type is compacted. Its public name, top-level type, and source location remain here; use the module’s exported interfaces, types, or runtime schema for input/output fields.

`mcpTransportSpecSchema`

Runtime schema for MCP Transport Spec.

Kind: constant
Import: import { mcpTransportSpecSchema } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

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

`mcpTrustPolicySpecSchema`

Runtime schema for MCP Trust Policy Spec.

Kind: constant
Import: import { mcpTrustPolicySpecSchema } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

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`

NORMALIZED MCP ERROR CODES constant exported by the contracts module.

Kind: constant
Import: import { NORMALIZED_MCP_ERROR_CODES } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

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`

Normalized MCP Error Definition constant exported by the contracts module.

Kind: constant
Import: import { normalizedMCPErrorDefinition } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

export declare const normalizedMCPErrorDefinition: SpecSchemaDefinition<NormalizedMCPError>;

`normalizedMCPErrorExample`

Valid example value for Normalized MCP Error.

Kind: constant
Import: import { normalizedMCPErrorExample } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

export declare const normalizedMCPErrorExample: NormalizedMCPError;

`normalizedMCPErrorJsonSchema`

JSON Schema for Normalized MCP Error.

Kind: constant
Import: import { normalizedMCPErrorJsonSchema } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

export declare const normalizedMCPErrorJsonSchema: JsonSchema;

`normalizedMCPErrorSchema`

Runtime schema for Normalized MCP Error.

Kind: constant
Import: import { normalizedMCPErrorSchema } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

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 interface with 16 public fields or methods.

Kind: interface
Import: import type { GovernedMCPIntegrationSpec } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

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>;
}

Contract members

Member	Kind	Signature	Description
`allowCapabilities`	property	`allowCapabilities?: MCPAllowDenyRule[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`denyCapabilities`	property	`denyCapabilities?: MCPAllowDenyRule[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`description`	property	`description?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`driftPolicy`	property	`driftPolicy: MCPCapabilityDriftPolicySpec`	Public property; its type, readonly modifier and optionality are shown in the signature.
`id`	property	`id: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`importPolicy`	property	`importPolicy: MCPImportPolicySpec`	Public property; its type, readonly modifier and optionality are shown in the signature.
`metadata`	property	`metadata?: Record<string, unknown>`	Public property; its type, readonly modifier and optionality are shown in the signature.
`name`	property	`name?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`promptPolicyRefs`	property	`promptPolicyRefs?: { id: string; version?: string; revision?: string; }[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`resourcePolicyRefs`	property	`resourcePolicyRefs?: { id: string; version?: string; revision?: string; }[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`revision`	property	`revision?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`servers`	property	`servers: MCPServerProfile[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`snapshotPolicy`	property	`snapshotPolicy: MCPContractSnapshotPolicySpec`	Public property; its type, readonly modifier and optionality are shown in the signature.
`toolPolicyRefs`	property	`toolPolicyRefs?: { id: string; version?: string; revision?: string; }[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`trustPolicy`	property	`trustPolicy: MCPTrustPolicySpec`	Public property; its type, readonly modifier and optionality are shown in the signature.
`version`	property	`version: string`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MCPAllowDenyRule`

MCP Allow Deny Rule interface with 4 public fields or methods.

Kind: interface
Import: import type { MCPAllowDenyRule } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

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

Contract members

Member	Kind	Signature	Description
`capabilityId`	property	`capabilityId?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`kind`	property	`kind?: "tool" \| "prompt" \| "resource"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`serverId`	property	`serverId?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`tags`	property	`tags?: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MCPCapabilityDriftPolicySpec`

MCP Capability Drift Policy Spec interface with 6 public fields or methods.

Kind: interface
Import: import type { MCPCapabilityDriftPolicySpec } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

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;
}

Contract members

Member	Kind	Signature	Description
`invalidateSchemaCache`	property	`invalidateSchemaCache?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`notifyRuntime`	property	`notifyRuntime?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`onDescriptionChange`	property	`onDescriptionChange: "quarantine" \| "accept" \| "snapshot_next_run"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`onRemoval`	property	`onRemoval: "mark_unavailable" \| "allow_existing_run" \| "fail_existing_run"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`onSchemaChange`	property	`onSchemaChange: "quarantine" \| "snapshot_next_run" \| "require_approval"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`onServerIdentityChange`	property	`onServerIdentityChange: "quarantine" \| "disconnect"`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MCPCapabilityTrustRecord`

MCP Capability Trust Record interface with 7 public fields or methods.

Kind: interface
Import: import type { MCPCapabilityTrustRecord } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

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>;
}

Contract members

Member	Kind	Signature	Description
`approvedAt`	property	`approvedAt?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`approvedBy`	property	`approvedBy?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`level`	property	`level: "trusted" \| "untrusted" \| "restricted"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`metadata`	property	`metadata?: Record<string, unknown>`	Public property; its type, readonly modifier and optionality are shown in the signature.
`restrictions`	property	`restrictions?: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`source`	property	`source: "import" \| "admin" \| "domain_pack" \| "runtime_discovery" \| "signed_manifest"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceRef`	property	`sourceRef?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MCPContractSnapshotPolicySpec`

MCP Contract Snapshot Policy Spec interface with 3 public fields or methods.

Kind: interface
Import: import type { MCPContractSnapshotPolicySpec } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

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

Contract members

Member	Kind	Signature	Description
`mode`	property	`mode: "run" \| "state"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`preserveRemovedForExistingRuns`	property	`preserveRemovedForExistingRuns?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`requireApprovedRevision`	property	`requireApprovedRevision?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MCPImportPolicySpec`

MCP Import Policy Spec interface with 4 public fields or methods.

Kind: interface
Import: import type { MCPImportPolicySpec } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

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

Contract members

Member	Kind	Signature	Description
`kinds`	property	`kinds: ("tool" \| "prompt" \| "resource")[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`lazyLoad`	property	`lazyLoad?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`maxLoadedCapabilities`	property	`maxLoadedCapabilities?: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`schemaTokenBudget`	property	`schemaTokenBudget?: number`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MCPServerProfile`

MCP Server Profile interface with 22 public fields or methods.

Kind: interface
Import: import type { MCPServerProfile } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

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>;
}

Contract members

Member	Kind	Signature	Description
`authRef`	property	`authRef?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`autoConnect`	property	`autoConnect?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`contentPolicy`	property	`contentPolicy?: { maxToolResultBytes?: number; maxResourceBytes?: number; maxPromptBytes?: number; maxPromptTokens?: number; oversizeAction?: "reject" \| "artifact"; }`	Public property; its type, readonly modifier and optionality are shown in the signature.
`displayName`	property	`displayName?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`egressPolicy`	property	`egressPolicy?: { allowedHosts?: string[]; denyPrivateNetworks?: boolean; requireTls?: boolean; maxRedirects?: number; allowCrossOriginRedirects?: boolean; }`	Public property; its type, readonly modifier and optionality are shown in the signature.
`environmentRefs`	property	`environmentRefs?: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`expectedServerInfo`	property	`expectedServerInfo?: Record<string, unknown>`	Public property; its type, readonly modifier and optionality are shown in the signature.
`healthCheckPolicy`	property	`healthCheckPolicy?: { intervalMs?: number; timeoutMs?: number; unhealthyThreshold?: number; }`	Public property; its type, readonly modifier and optionality are shown in the signature.
`id`	property	`id: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`initializationTimeoutMs`	property	`initializationTimeoutMs?: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`lazyConnect`	property	`lazyConnect?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`metadata`	property	`metadata?: Record<string, unknown>`	Public property; its type, readonly modifier and optionality are shown in the signature.
`mode`	property	`mode: "local" \| "remote" \| "fixture"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`protocolVersionPolicy`	property	`protocolVersionPolicy?: { allowedVersions?: string[]; preferLatest?: boolean; rejectUnknown?: boolean; }`	Public property; its type, readonly modifier and optionality are shown in the signature.
`reconnectPolicy`	property	`reconnectPolicy?: RetryPolicySpec`	Public property; its type, readonly modifier and optionality are shown in the signature.
`requestGuardPolicy`	property	`requestGuardPolicy?: { maxConcurrentRequests?: number; rateLimit?: { maxRequests: number; windowMs: number; }; circuitBreaker?: { failureThreshold: number; resetAfterMs: number; }; }`	Public property; its type, readonly modifier and optionality are shown in the signature.
`requestTimeoutMs`	property	`requestTimeoutMs?: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`shutdownTimeoutMs`	property	`shutdownTimeoutMs?: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`singleStart`	property	`singleStart?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`transport`	property	`transport: MCPTransportSpec`	Public property; its type, readonly modifier and optionality are shown in the signature.
`version`	property	`version?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`workingDirectoryRef`	property	`workingDirectoryRef?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MCPTrustPolicySpec`

MCP Trust Policy Spec interface with 9 public fields or methods.

Kind: interface
Import: import type { MCPTrustPolicySpec } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

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

Contract members

Member	Kind	Signature	Description
`allowServerDeclaredSideEffectHints`	property	`allowServerDeclaredSideEffectHints?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`defaultTrustLevel`	property	`defaultTrustLevel: "trusted" \| "untrusted" \| "restricted"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`pinCapabilityHashes`	property	`pinCapabilityHashes?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`pinProtocolVersion`	property	`pinProtocolVersion?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`pinServerIdentity`	property	`pinServerIdentity?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`requireAdminApprovalForNewServer`	property	`requireAdminApprovalForNewServer?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`requireApprovalForNewCapability`	property	`requireApprovalForNewCapability?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`requireApprovalForSchemaChange`	property	`requireApprovalForSchemaChange?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`trustedSourceRefs`	property	`trustedSourceRefs?: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.

`NormalizedMCPError`

Normalized MCP Error interface with 7 public fields or methods.

Kind: interface
Import: import type { NormalizedMCPError } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

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

Contract members

Member	Kind	Signature	Description
`capabilityId`	property	`capabilityId?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`code`	property	`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...`	Public property; its type, readonly modifier and optionality are shown in the signature.
`details`	property	`details?: Record<string, unknown>`	Public property; its type, readonly modifier and optionality are shown in the signature.
`message`	property	`message: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`remoteCode`	property	`remoteCode?: string \| number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`retryable`	property	`retryable: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`serverId`	property	`serverId?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MCPTransportSpec`

Public type alias for MCP Transport Spec; the declaration contains its complete type expression.

Kind: type
Import: import type { MCPTransportSpec } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

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`

Public type alias for Normalized MCP Error Code; the declaration contains its complete type expression.

Kind: type
Import: import type { NormalizedMCPErrorCode } from '@codesoul-co/hypha-mcp';
Source module: contracts

Declaration

text

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

@codesoul-co/hypha-mcp / contracts ​

Using this module ​

Import from the package entrypoint ​

Usage patterns ​

Runtime validation example ​

Public exports ​

governedMCPIntegrationDefinition ​

Declaration ​

governedMCPIntegrationExample ​

Declaration ​

governedMCPIntegrationJsonSchema ​

Declaration ​

governedMCPIntegrationJsonSchemas ​

Declaration ​

governedMCPIntegrationSpecSchema ​

Declaration ​

mcpCapabilityDriftPolicySpecSchema ​

Declaration ​

mcpServerProfileSchema ​

Declaration ​

mcpTransportSpecSchema ​

Declaration ​

mcpTrustPolicySpecSchema ​

Declaration ​

NORMALIZED_MCP_ERROR_CODES ​

Declaration ​

normalizedMCPErrorDefinition ​

Declaration ​

normalizedMCPErrorExample ​

Declaration ​

normalizedMCPErrorJsonSchema ​

Declaration ​

normalizedMCPErrorSchema ​

Declaration ​

GovernedMCPIntegrationSpec ​

Declaration ​

Contract members ​

MCPAllowDenyRule ​

Declaration ​

Contract members ​

MCPCapabilityDriftPolicySpec ​

Declaration ​

Contract members ​

MCPCapabilityTrustRecord ​

Declaration ​

Contract members ​

MCPContractSnapshotPolicySpec ​

Declaration ​

Contract members ​

MCPImportPolicySpec ​

Declaration ​

Contract members ​

MCPServerProfile ​

Declaration ​

Contract members ​

MCPTrustPolicySpec ​

Declaration ​

Contract members ​

NormalizedMCPError ​

Declaration ​

Contract members ​

MCPTransportSpec ​

Declaration ​

NormalizedMCPErrorCode ​

Declaration ​

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

Using this module

Import from the package entrypoint

Usage patterns

Runtime validation example

Public exports

`governedMCPIntegrationDefinition`

Declaration

`governedMCPIntegrationExample`

Declaration

`governedMCPIntegrationJsonSchema`

Declaration

`governedMCPIntegrationJsonSchemas`

Declaration

`governedMCPIntegrationSpecSchema`

Declaration

`mcpCapabilityDriftPolicySpecSchema`

Declaration

`mcpServerProfileSchema`

Declaration

`mcpTransportSpecSchema`

Declaration

`mcpTrustPolicySpecSchema`

Declaration

`NORMALIZED_MCP_ERROR_CODES`

Declaration

`normalizedMCPErrorDefinition`

Declaration

`normalizedMCPErrorExample`

Declaration

`normalizedMCPErrorJsonSchema`

Declaration

`normalizedMCPErrorSchema`

Declaration

`GovernedMCPIntegrationSpec`

Declaration

Contract members

`MCPAllowDenyRule`

Declaration

Contract members

`MCPCapabilityDriftPolicySpec`

Declaration

Contract members

`MCPCapabilityTrustRecord`

Declaration

Contract members

`MCPContractSnapshotPolicySpec`

Declaration

Contract members

`MCPImportPolicySpec`

Declaration

Contract members

`MCPServerProfile`

Declaration

Contract members

`MCPTrustPolicySpec`

Declaration

Contract members

`NormalizedMCPError`

Declaration

Contract members

`MCPTransportSpec`

Declaration

`NormalizedMCPErrorCode`

Declaration