mcp-server.ts

Overview

The mcp-server.ts file defines core type-safe structures for representing and categorizing MCP (likely "Media Control Protocol" or similar) server configurations within an application. It primarily provides an enumeration for supported server types and interfaces describing the shape of server-related data objects, including server metadata, connection details, and optional configuration variables.

This file serves as a foundational data contract layer, enabling consistent handling, validation, and communication of MCP server information across different system components.

Exports and Types

Enum: McpServerType

Defines the supported server types for MCP servers.

export enum McpServerType {
    Sse = 'sse',
    StreamableHttp = 'streamable-http',
}

• Purpose: To strongly type and limit the possible server types to known protocols.

• Members:

  • Sse — Represents servers using Server-Sent Events.

  • StreamableHttp — Represents servers using HTTP streaming.

Usage Example:

const serverType: McpServerType = McpServerType.Sse;
console.log(serverType); // Output: 'sse'

Interface: IMcpServerVariable

Structure describing a variable related to an MCP server instance.

export interface IMcpServerVariable {
    key: string;
    name: string;
}

• Properties:

  • key (string): The identifier for the variable, likely used programmatically.

  • name (string): A human-readable name or label for the variable.

Usage Example:

const variable: IMcpServerVariable = {
    key: 'token',
    name: 'Access Token',
};

Interface: IMcpServerInfo

Describes the metadata and configuration properties of an MCP server instance.

export interface IMcpServerInfo {
    id: string;
    name: string;
    url: string;
    server_type: McpServerType;
    description?: string;
    variables?: IMcpServerVariable[];
    headers: Map<string, string>;
}

• Properties:

  Property	Type	Description
  id	string	Unique identifier for the server instance.
  name	string	Human-readable name for the server.
  url	string	The base URL or endpoint address of the server.
  server_type	McpServerType	The type of server (e.g., SSE, Streamable HTTP).
  description	string (optional)	Optional textual description providing additional information about the server.
  variables	IMcpServerVariable[] (optional)	Optional list of variables that can be configured or used with this server.
  headers	Map<string, string>	A map of HTTP headers to include when connecting or communicating with the server.

• Usage Example:

const serverInfo: IMcpServerInfo = {
    id: 'server-01',
    name: 'Primary SSE Server',
    url: 'https://sse.example.com/mcp',
    server_type: McpServerType.Sse,
    description: 'Handles real-time events via SSE',
    variables: [
        { key: 'authToken', name: 'Authentication Token' }
    ],
    headers: new Map([
        ['Authorization', 'Bearer abc123'],
        ['Accept', 'text/event-stream']
    ]),
};

Implementation Details and Usage Context

• The McpServerType enum restricts server types to known protocols, facilitating type safety and ensuring that logic branching based on server type is robust and maintainable.

• IMcpServerVariable allows the system to represent configurable parameters or placeholders that an MCP server might require, such as authentication tokens or query parameters.

• IMcpServerInfo aggregates all relevant data about a server instance, including connection details (url, headers), identification (id, name), and metadata (description, variables). This structure can be used for server registration, display in UI components, or configuring client-side connections.

• The use of a Map<string, string> for headers, instead of a plain object, supports ordered headers and provides a clear API for header manipulation.

• This file is purely declarative — it does not contain runtime logic or functions; it provides type definitions to be used across the system.

Interaction with Other System Components

• Likely consumed by modules responsible for:

  • Managing MCP server connections (e.g., establishing SSE or HTTP streams).

  • Configuration management UI or APIs that register and modify MCP servers.

  • Authentication or authorization layers that utilize server variables.

  • Network layers that set HTTP headers for requests.

• Acts as a contract ensuring consistent data exchange and validation between front-end components, back-end services, and possibly persistent storage layers.

Visual Diagram

Below is a Mermaid class diagram illustrating the structure and relationships of the types defined in this file:

classDiagram
    class McpServerType {
        <<enumeration>>
        +Sse = 'sse'
        +StreamableHttp = 'streamable-http'
    }

    class IMcpServerVariable {
        +key: string
        +name: string
    }

    class IMcpServerInfo {
        +id: string
        +name: string
        +url: string
        +server_type: McpServerType
        +description?: string
        +variables?: IMcpServerVariable[]
        +headers: Map<string, string>
    }

    IMcpServerInfo --> McpServerType : server_type
    IMcpServerInfo "1" o-- "*" IMcpServerVariable : variables

Summary

• Purpose: Provides strongly typed definitions for MCP servers and their configuration.

• Core Types: Enum for server types and interfaces for server variables and server information.

• Key Features: Type safety, extensibility with optional properties, and clear data modeling.

• Usage: Forms the backbone for MCP server registration, connection, and metadata management across the system.

This file is essential for ensuring consistent handling of MCP server configurations and can be extended with additional types or fields as the MCP protocol or system requirements evolve.