@graphorin/mcp 0.5.0

package/dist/registry/json-schema.js

@@ -0,0 +1,215 @@
+//#region src/registry/json-schema.ts
+/**
+* Build a {@link ZodLikeSchema} that validates `data` against
+* `schema`. The returned instance follows the structural Zod
+* contract from `@graphorin/core` (a `parse` method that throws + a
+* `safeParse` method that returns a `ZodLikeSafeParseResult`).
+*
+* @stable
+*/
+function buildJsonSchemaValidator(schema) {
+	function parse(data) {
+		const issues = validate(data, schema, []);
+		if (issues.length === 0) return data;
+		throw buildError(issues);
+	}
+	function safeParse(data) {
+		const issues = validate(data, schema, []);
+		if (issues.length === 0) return {
+			success: true,
+			data
+		};
+		return {
+			success: false,
+			error: buildError(issues)
+		};
+	}
+	return Object.freeze({
+		parse,
+		safeParse
+	});
+}
+function validate(value, schema, path) {
+	if (schema === true) return [];
+	if (schema === false) return [{
+		path,
+		message: "rejected by schema (false)"
+	}];
+	const issues = [];
+	if ("const" in schema && schema.const !== void 0) {
+		if (!equalsDeep(value, schema.const)) issues.push({
+			path,
+			message: `expected const ${formatValue(schema.const)}`
+		});
+	}
+	if (Array.isArray(schema.enum)) {
+		if (!schema.enum.some((candidate) => equalsDeep(value, candidate))) issues.push({
+			path,
+			message: "value does not match any enum entry"
+		});
+	}
+	if (Array.isArray(schema.allOf)) for (const sub of schema.allOf) issues.push(...validate(value, sub, path));
+	if (Array.isArray(schema.anyOf)) {
+		if (!schema.anyOf.some((sub) => validate(value, sub, path).length === 0)) issues.push({
+			path,
+			message: "value did not match any of the anyOf branches"
+		});
+	}
+	if (Array.isArray(schema.oneOf)) {
+		const matchCount = schema.oneOf.filter((sub) => validate(value, sub, path).length === 0).length;
+		if (matchCount !== 1) issues.push({
+			path,
+			message: `expected exactly one oneOf branch to match (got ${matchCount})`
+		});
+	}
+	if (schema.type !== void 0) {
+		const typeIssues = validateType(value, schema, path);
+		issues.push(...typeIssues);
+	}
+	return issues;
+}
+function validateType(value, schema, path) {
+	if (schema === true || schema === false) return [];
+	const types = Array.isArray(schema.type) ? schema.type : schema.type === void 0 ? [] : [schema.type];
+	if (types.length === 0) return [];
+	if (!types.some((t) => matchesType(value, t))) return [{
+		path,
+		message: `expected type ${types.join(" | ")}`
+	}];
+	if (matchesType(value, "object") && (schema.properties !== void 0 || schema.required !== void 0 || schema.additionalProperties !== void 0)) return validateObject(value, schema, path);
+	if (matchesType(value, "array")) return validateArray(value, schema, path);
+	if (matchesType(value, "string")) return validateString(value, schema, path);
+	if (matchesType(value, "number") || matchesType(value, "integer")) return validateNumber(value, schema, path);
+	return [];
+}
+function validateObject(value, schema, path) {
+	if (schema === true || schema === false) return [];
+	const issues = [];
+	const required = Array.isArray(schema.required) ? schema.required : [];
+	for (const key of required) if (!(key in value)) issues.push({
+		path: [...path, key],
+		message: "is required"
+	});
+	const properties = schema.properties ?? {};
+	for (const [key, subSchema] of Object.entries(properties)) {
+		if (!(key in value)) continue;
+		issues.push(...validate(value[key], subSchema, [...path, key]));
+	}
+	if (schema.additionalProperties === false) {
+		for (const key of Object.keys(value)) if (!(key in properties)) issues.push({
+			path: [...path, key],
+			message: "unexpected additional property"
+		});
+	} else if (typeof schema.additionalProperties === "object" && schema.additionalProperties !== null) for (const key of Object.keys(value)) {
+		if (key in properties) continue;
+		issues.push(...validate(value[key], schema.additionalProperties, [...path, key]));
+	}
+	return issues;
+}
+function validateArray(value, schema, path) {
+	if (schema === true || schema === false) return [];
+	const issues = [];
+	if (typeof schema.minItems === "number" && value.length < schema.minItems) issues.push({
+		path,
+		message: `expected at least ${schema.minItems} items`
+	});
+	if (typeof schema.maxItems === "number" && value.length > schema.maxItems) issues.push({
+		path,
+		message: `expected at most ${schema.maxItems} items`
+	});
+	const items = schema.items;
+	if (items === void 0) return issues;
+	if (Array.isArray(items)) for (let i = 0; i < items.length; i++) {
+		if (i >= value.length) break;
+		const sub = items[i];
+		if (sub === void 0) continue;
+		issues.push(...validate(value[i], sub, [...path, i]));
+	}
+	else for (let i = 0; i < value.length; i++) issues.push(...validate(value[i], items, [...path, i]));
+	return issues;
+}
+function validateString(value, schema, path) {
+	if (schema === true || schema === false) return [];
+	const issues = [];
+	if (typeof schema.minLength === "number" && value.length < schema.minLength) issues.push({
+		path,
+		message: `expected at least ${schema.minLength} characters`
+	});
+	if (typeof schema.maxLength === "number" && value.length > schema.maxLength) issues.push({
+		path,
+		message: `expected at most ${schema.maxLength} characters`
+	});
+	if (typeof schema.pattern === "string") try {
+		if (!new RegExp(schema.pattern).test(value)) issues.push({
+			path,
+			message: `did not match pattern ${schema.pattern}`
+		});
+	} catch {}
+	return issues;
+}
+function validateNumber(value, schema, path) {
+	if (schema === true || schema === false) return [];
+	const issues = [];
+	if ((Array.isArray(schema.type) ? schema.type : schema.type === void 0 ? [] : [schema.type]).includes("integer") && !Number.isInteger(value)) issues.push({
+		path,
+		message: "expected an integer"
+	});
+	if (typeof schema.minimum === "number" && value < schema.minimum) issues.push({
+		path,
+		message: `expected >= ${schema.minimum}`
+	});
+	if (typeof schema.maximum === "number" && value > schema.maximum) issues.push({
+		path,
+		message: `expected <= ${schema.maximum}`
+	});
+	return issues;
+}
+function matchesType(value, type) {
+	switch (type) {
+		case "string": return typeof value === "string";
+		case "number": return typeof value === "number" && Number.isFinite(value);
+		case "integer": return typeof value === "number" && Number.isFinite(value);
+		case "boolean": return typeof value === "boolean";
+		case "null": return value === null;
+		case "array": return Array.isArray(value);
+		case "object": return typeof value === "object" && value !== null && !Array.isArray(value);
+		default: return true;
+	}
+}
+function equalsDeep(a, b) {
+	if (a === b) return true;
+	if (a === null || b === null) return a === b;
+	if (typeof a !== typeof b) return false;
+	if (Array.isArray(a) && Array.isArray(b)) {
+		if (a.length !== b.length) return false;
+		return a.every((item, i) => equalsDeep(item, b[i]));
+	}
+	if (typeof a === "object" && typeof b === "object") {
+		const ak = Object.keys(a);
+		const bk = Object.keys(b);
+		if (ak.length !== bk.length) return false;
+		return ak.every((key) => equalsDeep(a[key], b[key]));
+	}
+	return false;
+}
+function formatValue(value) {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return Object.prototype.toString.call(value);
+	}
+}
+function buildError(issues) {
+	return {
+		name: "GraphorinMCPSchemaError",
+		message: issues.map((i) => `${i.path.length === 0 ? "." : i.path.join(".")}: ${i.message}`).join("; "),
+		issues: Object.freeze(issues.map((i) => ({
+			path: Object.freeze([...i.path]),
+			message: i.message
+		})))
+	};
+}
+
+//#endregion
+export { buildJsonSchemaValidator };
+//# sourceMappingURL=json-schema.js.map

package/dist/registry/json-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.js","names":["issues: Issue[]","types: ReadonlyArray<string>"],"sources":["../../src/registry/json-schema.ts"],"sourcesContent":["/**\n * Lightweight JSON-Schema -> {@link ZodLikeSchema} adapter.\n *\n * The Model Context Protocol carries tool input + output schemas as\n * JSON Schema documents; the Graphorin tool registry types its\n * schemas via the `ZodLikeSchema` structural contract from\n * `@graphorin/core`. This module bridges the two without pulling\n * `zod` into the MCP boundary or relying on code generation +\n * runtime `eval` (the popular `json-schema-to-zod` package generates\n * source code that needs `new Function(...)` to execute).\n *\n * The adapter validates the canonical subset of JSON Schema the MCP\n * spec uses: `object` (with `properties`, `required`,\n * `additionalProperties`), `array` (with `items`, `minItems`,\n * `maxItems`), `string` (with `enum`, `minLength`, `maxLength`,\n * `pattern`), `number` / `integer` (with `enum`, `minimum`,\n * `maximum`), `boolean`, `null`, and the primitive composition\n * keywords `enum`, `const`, `oneOf`, `anyOf`, `allOf`. Unknown keys\n * are accepted permissively so newer MCP server schemas that ship\n * additional vocabulary do not break the adapter.\n *\n * @packageDocumentation\n */\n\nimport type { ZodLikeError, ZodLikeSafeParseResult, ZodLikeSchema } from '@graphorin/core';\n\n/** JSON Schema document subset accepted by {@link buildJsonSchemaValidator}. */\nexport type JsonSchemaLike =\n  | boolean\n  | (Readonly<Record<string, unknown>> & {\n      readonly type?: string | ReadonlyArray<string>;\n      readonly properties?: Readonly<Record<string, JsonSchemaLike>>;\n      readonly required?: ReadonlyArray<string>;\n      readonly additionalProperties?: boolean | JsonSchemaLike;\n      readonly items?: JsonSchemaLike | ReadonlyArray<JsonSchemaLike>;\n      readonly minItems?: number;\n      readonly maxItems?: number;\n      readonly minimum?: number;\n      readonly maximum?: number;\n      readonly minLength?: number;\n      readonly maxLength?: number;\n      readonly pattern?: string;\n      readonly enum?: ReadonlyArray<unknown>;\n      readonly const?: unknown;\n      readonly oneOf?: ReadonlyArray<JsonSchemaLike>;\n      readonly anyOf?: ReadonlyArray<JsonSchemaLike>;\n      readonly allOf?: ReadonlyArray<JsonSchemaLike>;\n    });\n\n/**\n * Build a {@link ZodLikeSchema} that validates `data` against\n * `schema`. The returned instance follows the structural Zod\n * contract from `@graphorin/core` (a `parse` method that throws + a\n * `safeParse` method that returns a `ZodLikeSafeParseResult`).\n *\n * @stable\n */\nexport function buildJsonSchemaValidator<T = unknown>(schema: JsonSchemaLike): ZodLikeSchema<T> {\n  function parse(data: unknown): T {\n    const issues = validate(data, schema, []);\n    if (issues.length === 0) return data as T;\n    throw buildError(issues);\n  }\n  function safeParse(data: unknown): ZodLikeSafeParseResult<T, unknown> {\n    const issues = validate(data, schema, []);\n    if (issues.length === 0) {\n      return { success: true, data: data as T };\n    }\n    return { success: false, error: buildError(issues) };\n  }\n  return Object.freeze({ parse, safeParse });\n}\n\ninterface Issue {\n  readonly path: ReadonlyArray<string | number>;\n  readonly message: string;\n}\n\nfunction validate(\n  value: unknown,\n  schema: JsonSchemaLike,\n  path: ReadonlyArray<string | number>,\n): Issue[] {\n  if (schema === true) return [];\n  if (schema === false) return [{ path, message: 'rejected by schema (false)' }];\n\n  const issues: Issue[] = [];\n\n  if ('const' in schema && schema.const !== undefined) {\n    if (!equalsDeep(value, schema.const)) {\n      issues.push({ path, message: `expected const ${formatValue(schema.const)}` });\n    }\n  }\n  if (Array.isArray(schema.enum)) {\n    if (!schema.enum.some((candidate) => equalsDeep(value, candidate))) {\n      issues.push({ path, message: 'value does not match any enum entry' });\n    }\n  }\n  if (Array.isArray(schema.allOf)) {\n    for (const sub of schema.allOf) {\n      issues.push(...validate(value, sub, path));\n    }\n  }\n  if (Array.isArray(schema.anyOf)) {\n    const anyOk = schema.anyOf.some((sub) => validate(value, sub, path).length === 0);\n    if (!anyOk) issues.push({ path, message: 'value did not match any of the anyOf branches' });\n  }\n  if (Array.isArray(schema.oneOf)) {\n    const matchCount = schema.oneOf.filter((sub) => validate(value, sub, path).length === 0).length;\n    if (matchCount !== 1) {\n      issues.push({\n        path,\n        message: `expected exactly one oneOf branch to match (got ${matchCount})`,\n      });\n    }\n  }\n\n  if (schema.type !== undefined) {\n    const typeIssues = validateType(value, schema, path);\n    issues.push(...typeIssues);\n  }\n\n  return issues;\n}\n\nfunction validateType(\n  value: unknown,\n  schema: JsonSchemaLike,\n  path: ReadonlyArray<string | number>,\n): Issue[] {\n  if (schema === true || schema === false) return [];\n  const types: ReadonlyArray<string> = Array.isArray(schema.type)\n    ? schema.type\n    : schema.type === undefined\n      ? []\n      : [schema.type];\n  if (types.length === 0) return [];\n  if (!types.some((t) => matchesType(value, t))) {\n    return [{ path, message: `expected type ${types.join(' | ')}` }];\n  }\n\n  if (\n    matchesType(value, 'object') &&\n    (schema.properties !== undefined ||\n      schema.required !== undefined ||\n      schema.additionalProperties !== undefined)\n  ) {\n    return validateObject(value as Record<string, unknown>, schema, path);\n  }\n  if (matchesType(value, 'array')) {\n    return validateArray(value as unknown[], schema, path);\n  }\n  if (matchesType(value, 'string')) {\n    return validateString(value as string, schema, path);\n  }\n  if (matchesType(value, 'number') || matchesType(value, 'integer')) {\n    return validateNumber(value as number, schema, path);\n  }\n  return [];\n}\n\nfunction validateObject(\n  value: Record<string, unknown>,\n  schema: JsonSchemaLike & { readonly type?: unknown },\n  path: ReadonlyArray<string | number>,\n): Issue[] {\n  if (schema === true || schema === false) return [];\n  const issues: Issue[] = [];\n  const required = Array.isArray(schema.required) ? schema.required : [];\n  for (const key of required) {\n    if (!(key in value)) {\n      issues.push({ path: [...path, key], message: 'is required' });\n    }\n  }\n  const properties = schema.properties ?? {};\n  for (const [key, subSchema] of Object.entries(properties)) {\n    if (!(key in value)) continue;\n    issues.push(...validate(value[key], subSchema, [...path, key]));\n  }\n  if (schema.additionalProperties === false) {\n    for (const key of Object.keys(value)) {\n      if (!(key in properties)) {\n        issues.push({ path: [...path, key], message: 'unexpected additional property' });\n      }\n    }\n  } else if (\n    typeof schema.additionalProperties === 'object' &&\n    schema.additionalProperties !== null\n  ) {\n    for (const key of Object.keys(value)) {\n      if (key in properties) continue;\n      issues.push(\n        ...validate(value[key], schema.additionalProperties as JsonSchemaLike, [...path, key]),\n      );\n    }\n  }\n  return issues;\n}\n\nfunction validateArray(\n  value: unknown[],\n  schema: JsonSchemaLike & { readonly type?: unknown },\n  path: ReadonlyArray<string | number>,\n): Issue[] {\n  if (schema === true || schema === false) return [];\n  const issues: Issue[] = [];\n  if (typeof schema.minItems === 'number' && value.length < schema.minItems) {\n    issues.push({ path, message: `expected at least ${schema.minItems} items` });\n  }\n  if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {\n    issues.push({ path, message: `expected at most ${schema.maxItems} items` });\n  }\n  const items = schema.items;\n  if (items === undefined) return issues;\n  if (Array.isArray(items)) {\n    for (let i = 0; i < items.length; i++) {\n      if (i >= value.length) break;\n      const sub = items[i];\n      if (sub === undefined) continue;\n      issues.push(...validate(value[i], sub, [...path, i]));\n    }\n  } else {\n    for (let i = 0; i < value.length; i++) {\n      issues.push(...validate(value[i], items as JsonSchemaLike, [...path, i]));\n    }\n  }\n  return issues;\n}\n\nfunction validateString(\n  value: string,\n  schema: JsonSchemaLike & { readonly type?: unknown },\n  path: ReadonlyArray<string | number>,\n): Issue[] {\n  if (schema === true || schema === false) return [];\n  const issues: Issue[] = [];\n  if (typeof schema.minLength === 'number' && value.length < schema.minLength) {\n    issues.push({ path, message: `expected at least ${schema.minLength} characters` });\n  }\n  if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {\n    issues.push({ path, message: `expected at most ${schema.maxLength} characters` });\n  }\n  if (typeof schema.pattern === 'string') {\n    try {\n      const re = new RegExp(schema.pattern);\n      if (!re.test(value))\n        issues.push({ path, message: `did not match pattern ${schema.pattern}` });\n    } catch {\n      // Treat malformed patterns as permissive (mirrors Ajv default).\n    }\n  }\n  return issues;\n}\n\nfunction validateNumber(\n  value: number,\n  schema: JsonSchemaLike & { readonly type?: unknown },\n  path: ReadonlyArray<string | number>,\n): Issue[] {\n  if (schema === true || schema === false) return [];\n  const issues: Issue[] = [];\n  const types: ReadonlyArray<string> = Array.isArray(schema.type)\n    ? schema.type\n    : schema.type === undefined\n      ? []\n      : [schema.type];\n  if (types.includes('integer') && !Number.isInteger(value)) {\n    issues.push({ path, message: 'expected an integer' });\n  }\n  if (typeof schema.minimum === 'number' && value < schema.minimum) {\n    issues.push({ path, message: `expected >= ${schema.minimum}` });\n  }\n  if (typeof schema.maximum === 'number' && value > schema.maximum) {\n    issues.push({ path, message: `expected <= ${schema.maximum}` });\n  }\n  return issues;\n}\n\nfunction matchesType(value: unknown, type: string): boolean {\n  switch (type) {\n    case 'string':\n      return typeof value === 'string';\n    case 'number':\n      return typeof value === 'number' && Number.isFinite(value);\n    case 'integer':\n      return typeof value === 'number' && Number.isFinite(value);\n    case 'boolean':\n      return typeof value === 'boolean';\n    case 'null':\n      return value === null;\n    case 'array':\n      return Array.isArray(value);\n    case 'object':\n      return typeof value === 'object' && value !== null && !Array.isArray(value);\n    default:\n      return true;\n  }\n}\n\nfunction equalsDeep(a: unknown, b: unknown): boolean {\n  if (a === b) return true;\n  if (a === null || b === null) return a === b;\n  if (typeof a !== typeof b) return false;\n  if (Array.isArray(a) && Array.isArray(b)) {\n    if (a.length !== b.length) return false;\n    return a.every((item, i) => equalsDeep(item, b[i]));\n  }\n  if (typeof a === 'object' && typeof b === 'object') {\n    const ak = Object.keys(a as Record<string, unknown>);\n    const bk = Object.keys(b as Record<string, unknown>);\n    if (ak.length !== bk.length) return false;\n    return ak.every((key) =>\n      equalsDeep((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]),\n    );\n  }\n  return false;\n}\n\nfunction formatValue(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return Object.prototype.toString.call(value);\n  }\n}\n\nfunction buildError(issues: ReadonlyArray<Issue>): ZodLikeError {\n  return {\n    name: 'GraphorinMCPSchemaError',\n    message: issues\n      .map((i) => `${i.path.length === 0 ? '.' : i.path.join('.')}: ${i.message}`)\n      .join('; '),\n    issues: Object.freeze(\n      issues.map((i) => ({ path: Object.freeze([...i.path]), message: i.message })),\n    ),\n  };\n}\n"],"mappings":"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"}

package/dist/transport/index.d.ts

@@ -0,0 +1,4 @@
+import { MCPTransportConfig, ServerIdentity, SseTransportConfig, StdioTransportConfig, StreamableHttpTransportConfig } from "./types.js";
+import { deriveServerIdentity, formatMCPServerName } from "../helpers/identity.js";
+import { validateMCPServerConfig } from "../helpers/validate-config.js";
+export { type MCPTransportConfig, type ServerIdentity, type SseTransportConfig, type StdioTransportConfig, type StreamableHttpTransportConfig, deriveServerIdentity, formatMCPServerName, validateMCPServerConfig };

package/dist/transport/index.js

@@ -0,0 +1,4 @@
+import { deriveServerIdentity, formatMCPServerName } from "../helpers/identity.js";
+import { validateMCPServerConfig } from "../helpers/validate-config.js";
+
+export { deriveServerIdentity, formatMCPServerName, validateMCPServerConfig };

package/dist/transport/types.d.ts

@@ -0,0 +1,93 @@
+//#region src/transport/types.d.ts
+/**
+ * Transport descriptors accepted by {@link createMCPClient}.
+ *
+ * The discriminated union mirrors the three transports the
+ * `@modelcontextprotocol/sdk@^1.29.0` package exports:
+ *
+ * - `'stdio'`           — the primary transport for local MCP servers
+ *   started as a child process. The transport spawns the configured
+ *   command, pipes JSON-RPC over stdio, and tears the child down on
+ *   `client.close()`.
+ * - `'streamable-http'` — the current default transport for remote MCP
+ *   servers (the spec-recommended replacement for the legacy SSE
+ *   transport). Supports server-assigned `Mcp-Session-Id` + the
+ *   `Last-Event-ID` resume handshake when the server advertises it on
+ *   `initialize`.
+ * - `'sse'`             — the deprecated legacy transport. Kept for
+ *   back-compat with MCP servers that have not yet migrated to the
+ *   streamable HTTP transport. The runtime emits one WARN-per-process
+ *   on transport selection; the transport is not eligible for the
+ *   resumable-session features.
+ *
+ * @stable
+ */
+type MCPTransportConfig = StdioTransportConfig | StreamableHttpTransportConfig | SseTransportConfig;
+/** Options for the `'stdio'` transport. */
+interface StdioTransportConfig {
+  readonly kind: 'stdio';
+  readonly command: string;
+  readonly args?: ReadonlyArray<string>;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly cwd?: string;
+  /**
+   * How to handle the spawned child's stderr stream. Defaults to
+   * `'inherit'` so operator-supplied servers print diagnostics to the
+   * host process's stderr; `'pipe'` collects stderr into the
+   * transport for in-process logging; `'ignore'` discards it.
+   */
+  readonly stderr?: 'inherit' | 'pipe' | 'ignore';
+}
+/** Options for the `'streamable-http'` transport. */
+interface StreamableHttpTransportConfig {
+  readonly kind: 'streamable-http';
+  readonly url: string | URL;
+  readonly headers?: Readonly<Record<string, string>>;
+  /**
+   * Optional pre-existing session id. Most operators leave this
+   * unset — the server assigns one on `initialize` and the client
+   * persists it for the lifetime of the connection.
+   */
+  readonly sessionId?: string;
+  /** Custom `fetch` implementation; defaults to the global `fetch`. */
+  readonly fetch?: typeof fetch;
+}
+/** Options for the deprecated `'sse'` transport. */
+interface SseTransportConfig {
+  readonly kind: 'sse';
+  readonly url: string | URL;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly fetch?: typeof fetch;
+}
+/**
+ * Server identity descriptor attached to every MCP-derived `Tool`.
+ * Mirrors the shape consumed by the tool-registry collision
+ * resolver; the `argsHash` / `urlHostname` fields are the
+ * disambiguation keys the registry uses when surfacing collision
+ * resolutions, while the canonical `id` field is the operator-
+ * facing label.
+ *
+ * @stable
+ */
+type ServerIdentity = {
+  readonly kind: 'mcp-stdio';
+  readonly id: string;
+  readonly command: string;
+  readonly argsHash: string;
+  readonly serverInfoName?: string;
+} | {
+  readonly kind: 'mcp-streamable-http';
+  readonly id: string;
+  readonly urlHostname: string;
+  readonly urlPath: string;
+  readonly serverInfoName?: string;
+} | {
+  readonly kind: 'mcp-sse';
+  readonly id: string;
+  readonly urlHostname: string;
+  readonly urlPath: string;
+  readonly serverInfoName?: string;
+};
+//#endregion
+export { MCPTransportConfig, ServerIdentity, SseTransportConfig, StdioTransportConfig, StreamableHttpTransportConfig };
+//# sourceMappingURL=types.d.ts.map

package/dist/transport/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/transport/types.ts"],"sourcesContent":[],"mappings":";;AAuBA;;;;;AAMA;;;;;AAgBA;;;;;;AAeA;;;;;;AAiBY,KAtDA,kBAAA,GACR,oBAqDsB,GApDtB,6BAoDsB,GAnDtB,kBAmDsB;;UAhDT,oBAAA;;;kBAGC;iBACD,SAAS;;;;;;;;;;;UAYT,6BAAA;;yBAEQ;qBACJ,SAAS;;;;;;;;0BAQJ;;;UAIT,kBAAA;;yBAEQ;qBACJ,SAAS;0BACJ;;;;;;;;;;;;KAad,cAAA"}

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@graphorin/mcp",
+  "version": "0.5.0",
+  "description": "Model Context Protocol client for the Graphorin framework: stdio + Streamable HTTP + SSE transports, typed `MCPClient` (`listTools` / `listResources` / `listPrompts` / `callTool`), `toTools()` adapter (per-server inbound prompt-injection sanitization, deferred-loading auto-default at the 10-tool threshold, structured-content + outputSchema round-trip with backward-compatible TextContent mirror, per-server result envelope overrides, per-server call timeout, mcp provenance stamping for the dataflow policy, per-server preferredModel and side-effect class overrides), OAuth integration backed by @graphorin/security/oauth, typed errors, and library helpers consumed by the upcoming graphorin auth CLI.",
+  "license": "MIT",
+  "author": "Oleksiy Stepurenko",
+  "homepage": "https://github.com/o-stepper/graphorin/tree/main/packages/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/graphorin.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/o-stepper/graphorin/issues"
+  },
+  "keywords": [
+    "graphorin",
+    "ai",
+    "agents",
+    "framework",
+    "mcp",
+    "model-context-protocol",
+    "mcp-client",
+    "stdio",
+    "streamable-http",
+    "sse",
+    "oauth",
+    "structured-content",
+    "resumable-sessions",
+    "tool-collision",
+    "deferred-loading",
+    "inbound-sanitization"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./transport": {
+      "types": "./dist/transport/index.d.ts",
+      "import": "./dist/transport/index.js"
+    },
+    "./oauth": {
+      "types": "./dist/oauth/index.d.ts",
+      "import": "./dist/oauth/index.js"
+    },
+    "./helpers": {
+      "types": "./dist/helpers/index.d.ts",
+      "import": "./dist/helpers/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.ts",
+      "import": "./dist/errors/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@graphorin/core": "0.5.0",
+    "@graphorin/observability": "0.5.0",
+    "@graphorin/security": "0.5.0",
+    "@graphorin/tools": "0.5.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.23.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": false
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "fast-check": "^3.23.0",
+    "hono": "^4.12.21",
+    "zod": "^3.25.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  }
+}