calute.mcp.types

calute.mcp.types#

Type definitions for Model Context Protocol (MCP) integration.

This module provides data structures and type definitions for MCP (Model Context Protocol) integration within the Calute framework. It includes: - Transport type enumeration for different communication protocols - Server configuration dataclass for MCP server connections - Tool, resource, and prompt dataclasses for MCP primitives

MCP enables standardized communication between AI agents and external tools/services. These types form the foundation for the MCP client implementation in Calute.

Example

>>> from calute.mcp.types import MCPServerConfig, MCPTransportType
>>> config = MCPServerConfig(
...     name="filesystem",
...     command="npx",
...     args=["-y", "@modelcontextprotocol/server-filesystem"],
...     transport=MCPTransportType.STDIO
... )

class calute.mcp.types.MCPPrompt(name: str, description: str, arguments: list[dict[str, typing.Any]] = <factory>, server_name: str = '')[source]#

Bases: object

Represents an MCP prompt template.

Encapsulates reusable prompt templates exposed by MCP servers. Prompts allow servers to provide pre-defined interaction patterns that agents can invoke with specific arguments to generate responses.

name#

Unique identifier for the prompt template.

Type: str

description#

Human-readable description of the prompt purpose.

Type: str

arguments#

List of argument definitions with name, type, and description.

Type: list[dict[str, Any]]

server_name#

Name of the MCP server that provides this prompt.

Type: str

Example

>>> prompt = MCPPrompt(
...     name="summarize",
...     description="Summarize the given text",
...     arguments=[{"name": "text", "type": "string", "required": True}],
...     server_name="text-tools"
... )

arguments: list[dict[str, Any]]#

description: str#

name: str#

server_name: str = ''#

class calute.mcp.types.MCPResource(uri: str, name: str, description: str, mime_type: str | None = None, server_name: str = '')[source]#

Bases: object

Represents an MCP resource (data) accessible to agents.

Encapsulates metadata for data resources exposed by MCP servers. Resources provide read-only access to contextual information that agents can use to inform their responses and decisions.

uri#

Unique resource identifier URI for accessing the resource.

Type: str

name#

Human-readable display name for the resource.

Type: str

description#

Detailed description of the resource content.

Type: str

mime_type#

MIME type indicating the resource format (e.g., ‘text/plain’).

Type: str | None

server_name#

Name of the MCP server that provides this resource.

Type: str

Example

>>> resource = MCPResource(
...     uri="file:///path/to/document.txt",
...     name="Document",
...     description="Project documentation file",
...     mime_type="text/plain",
...     server_name="filesystem"
... )

description: str#

mime_type: str | None = None#

name: str#

server_name: str = ''#

uri: str#

class calute.mcp.types.MCPServerConfig(name: str, command: str | None = None, args: list[str] = <factory>, env: dict[str, str] = <factory>, transport: ~calute.mcp.types.MCPTransportType = MCPTransportType.STDIO, url: str | None = None, headers: dict[str, str] = <factory>, enabled: bool = True, timeout: float = 30.0, sse_read_timeout: float = 300.0)[source]#

Bases: object

Configuration for an MCP server connection.

Defines all settings required to establish and manage a connection to an MCP server. Supports both local subprocess (STDIO) and remote HTTP-based transports with configurable timeouts and authentication.

name#

Unique identifier name for this MCP server.

Type: str

command#

Command to start the server (required for STDIO transport).

Type: str | None

args#

Command-line arguments for the server process.

Type: list[str]

env#

Environment variables to set for the server process.

Type: dict[str, str]

transport#

Communication protocol type (STDIO, SSE, or STREAMABLE_HTTP).

Type: calute.mcp.types.MCPTransportType

url#

Server URL (required for SSE/Streamable HTTP transports).

Type: str | None

headers#

HTTP headers for authentication and custom metadata.

Type: dict[str, str]

enabled#

Whether this server connection is active.

Type: bool

timeout#

Timeout in seconds for HTTP operations (default: 30.0).

Type: float

sse_read_timeout#

Timeout in seconds for SSE event stream reads (default: 300.0).

Type: float

Example

>>> config = MCPServerConfig(
...     name="github",
...     url="https://mcp.github.com/sse",
...     transport=MCPTransportType.SSE,
...     headers={"Authorization": "Bearer token"}
... )

args: list[str]#

command: str | None = None#

enabled: bool = True#

env: dict[str, str]#

headers: dict[str, str]#

name: str#

sse_read_timeout: float = 300.0#

timeout: float = 30.0#

transport: MCPTransportType = 'stdio'#

url: str | None = None#

class calute.mcp.types.MCPTool(name: str, description: str, input_schema: dict[str, Any], server_name: str)[source]#

Bases: object

Represents an MCP tool that can be called by agents.

Encapsulates the metadata and schema for an MCP tool, enabling agents to discover and invoke external capabilities exposed by MCP servers. Tools are the primary mechanism for agent actions.

name#

Unique identifier for the tool within its server.

Type: str

description#

Human-readable description of tool functionality.

Type: str

input_schema#

JSON Schema defining required and optional parameters.

Type: dict[str, Any]

server_name#

Name of the MCP server that provides this tool.

Type: str

Example

>>> tool = MCPTool(
...     name="read_file",
...     description="Read contents of a file",
...     input_schema={"type": "object", "properties": {"path": {"type": "string"}}},
...     server_name="filesystem"
... )

description: str#

input_schema: dict[str, Any]#

name: str#

server_name: str#

class calute.mcp.types.MCPTransportType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Enumeration of available MCP transport types.

Defines the communication protocols supported for connecting to MCP servers. Each transport type has different use cases and performance characteristics.

Transport Types:

STDIO: Local subprocess communication via standard input/output.: Best for local tools like npx or uvx style servers.
SSE: Server-Sent Events over HTTP (legacy 2024-11-05 protocol).: Suitable for remote servers with one-way streaming.
STREAMABLE_HTTP: Streamable HTTP transport (recommended for 2025+).: Modern bidirectional streaming protocol for remote servers.

Note

HTTP and WEBSOCKET are deprecated aliases maintained for backwards compatibility. Use SSE or STREAMABLE_HTTP instead.

HTTP = 'sse'#

SSE = 'sse'#

STDIO = 'stdio'#

STREAMABLE_HTTP = 'streamable_http'#

WEBSOCKET = 'streamable_http'#

calute.mcp.types

Contents

calute.mcp.types#