feat(types): introduce MCP definitions and align with latest OpenAI spec

- Add comprehensive Model Context Protocol (MCP) type definitions, including `MCPTool`, `MCPToolCall`, `MCPListTools`, connector IDs, and approval filters to support remote server tool calling.
- Add `ServiceTier` literal ("auto", "default", etc.) and include the `service_tier` field in `CreateChatCompletionResponse`.
- Restrict `finish_reason` in completion responses to strict standard literals (`stop`, `length`, `tool_calls`, `content_filter`, `function_call`).
- Introduce `ChatCompletionMessageCustomToolCall` to support custom tool calls generated by the model.
- Update `ChatCompletionRequestAssistantMessage` to include the `name` field and add descriptive docstrings to message types.

Signed-off-by: JamePeng <jame_peng@sina.com>

Author: JamePeng

llama_cpp/llama_types.py

@@ -144,14 +144,18 @@ class ChatCompletionResponseChoice(TypedDict):
     index: int
     message: "ChatCompletionResponseMessage"
     logprobs: Optional[ChatCompletionLogprobs]
-    finish_reason: Optional[str]
+    finish_reason: Optional[Literal["stop", "length", "tool_calls", "content_filter", "function_call"]]
+
+
+ServiceTier = Literal["auto", "default", "flex", "scale", "priority"]
 
 
 class CreateChatCompletionResponse(TypedDict):
     id: str
     object: Literal["chat.completion"]
     created: int
     model: str
+    service_tier: NotRequired[ServiceTier]
     choices: List["ChatCompletionResponseChoice"]
     usage: CompletionUsage
 
@@ -300,27 +304,130 @@ class ChatCompletionRequestUserMessage(TypedDict):
     content: Optional[Union[str, List[ChatCompletionRequestMessageContentPart]]]
 
 
+# Function tool call
+
 class ChatCompletionMessageToolCallFunction(TypedDict):
+    """The function that the model called."""
     name: str
     arguments: str
 
 
 class ChatCompletionMessageToolCall(TypedDict):
+    """A call to a function tool created by the model."""
     id: str
     type: Literal["function"]
     function: ChatCompletionMessageToolCallFunction
 
+# Custom tool call
 
-ChatCompletionMessageToolCalls = List[ChatCompletionMessageToolCall]
+class ChatCompletionMessageCustomToolCallCustom(TypedDict):
+    """The custom tool that the model called."""
+    name: str
+    input: str
 
+class ChatCompletionMessageCustomToolCall(TypedDict):
+    """A call to a custom tool created by the model."""
+    id: str
+    type: Literal["custom"]
+    custom: ChatCompletionMessageCustomToolCallCustom
 
-class ChatCompletionRequestAssistantMessageFunctionCall(TypedDict):
+# The tool calls generated by the model, such as function calls.
+ChatCompletionMessageToolCalls = Union[
+    ChatCompletionMessageToolCall,
+    ChatCompletionMessageCustomToolCall
+]
+
+
+# MCP ToolCall
+
+MCPConnectorID = Literal[
+    "connector_dropbox",
+    "connector_gmail",
+    "connector_googlecalendar",
+    "connector_googledrive",
+    "connector_microsoftteams",
+    "connector_outlookcalendar",
+    "connector_outlookemail",
+    "connector_sharepoint"
+]
+
+MCPToolCallStatus = Literal["in_progress", "completed", "incomplete", "calling", "failed"]
+
+class MCPToolCall(TypedDict):
+    """An invocation of a tool on an MCP server."""
+    type: Literal["mcp_call"]
+    id: str
+    server_label: str
     name: str
+    arguments: str  # JSON string
+    output: NotRequired[Optional[str]]
+    error: NotRequired[Optional[str]]
+    status: NotRequired[MCPToolCallStatus]
+    approval_request_id: NotRequired[Optional[str]]
+
+
+class MCPListToolsTool(TypedDict):
+    """A tool available on an MCP server."""
+    name: str
+    description: Optional[str]
+    input_schema: Dict[str, Any]  # The JSON schema describing the tool's input
+    annotations: Optional[Dict[str, Any]]
+
+
+class MCPListTools(TypedDict):
+    """A list of tools available on an MCP server."""
+    type: Literal["mcp_list_tools"]
+    id: str
+    server_label: str
+    tools: List[MCPListToolsTool]
+    error: Optional[str]
+
+
+class MCPToolFilter(TypedDict):
+    """A filter object to specify which tools are allowed."""
+    tool_names: NotRequired[List[str]]
+    read_only: NotRequired[bool]
+
+
+class MCPToolApprovalFilter(TypedDict, total=False):
+    """Specify which of the MCP server's tools require approval based on filters."""
+    always: MCPToolFilter
+    never: MCPToolFilter
+
+
+class MCPTool(TypedDict):
+    """
+    Give the model access to additional tools via remote Model Context Protocol (MCP) servers.
+    """
+    # The type of the MCP tool. Always `mcp`.
+    type: Literal["mcp"]
+    # A label for this MCP server, used to identify it in tool calls.
+    server_label: str
+    # The URL for the MCP server. One of `server_url` or `connector_id` must be provided.
+    server_url: NotRequired[str]
+    connector_id: NotRequired[MCPConnectorID]
+    authorization: NotRequired[str]
+    server_description: NotRequired[str]
+    headers: NotRequired[Optional[Dict[str, str]]]
+    # List of allowed tool names or a filter object.
+    allowed_tools: NotRequired[Optional[Union[List[str], MCPToolFilter]]]
+    # Specify which of the MCP server's tools require approval.
+    require_approval: NotRequired[Optional[Union[Literal["always", "never"], MCPToolApprovalFilter]]]
+    # Whether this MCP tool is deferred and discovered via tool search.
+    defer_loading: NotRequired[bool]
+
+
+# Assistant message
+
+class ChatCompletionRequestAssistantMessageFunctionCall(TypedDict):
     arguments: str
+    name: str
 
 
 class ChatCompletionRequestAssistantMessage(TypedDict):
+    """Messages sent by the model in response to user messages."""
     role: Literal["assistant"]
+    name: Optional[str]
     content: NotRequired[Optional[str]]
     refusal: NotRequired[Optional[str]]
     tool_calls: NotRequired[ChatCompletionMessageToolCalls]