object

# `mcp_server`

MCP (Model Context Protocol) server for Logtalk applications. Exposes Logtalk objects implementing the `mcp_tool_protocol` and optionally `mcp_prompt_protocol` and `mcp_resource_protocol` protocols as MCP tool, prompt, and resource providers over stdio transport with Content-Length framing. Implements the MCP 2025-03-26 specification. Uses the `json_rpc` library for JSON-RPC 2.0 message handling.

Availability:
`logtalk_load(mcp_server(loader))`
Author: Paulo Moura
Version: 0:5:1
Date: 2026-03-13
Compilation flags:
`static, context_switching_calls`
Imports:
`public` options
Uses:
json_rpc
list
term_io
user
Remarks:

> - MCP specification: Implements the Model Context Protocol 2025-03-26: https://spec.modelcontextprotocol.io/specification/2025-03-26/

> - Transport: Uses stdio (standard input/output) with Content-Length header framing as defined by the MCP specification.

> - Version negotiation: During initialization, the server performs protocol version negotiation. The client sends its highest supported version in the `initialize` request. The server selects the highest version it supports that is compatible (i.e., less than or equal to the client version). If no compatible version exists, the server responds with error `-32602` (“Unsupported protocol version”) including a `data` field with the list of supported versions.

> - Capabilities: Supports the tools capability (`tools/list` and `tools/call`). Optionally supports the prompts capability (`prompts/list` and `prompts/get`) when the application declares it via `capabilities/1` and implements `mcp_prompt_protocol`. Optionally supports the resources capability (`resources/list` and `resources/read`) when the application declares it via `capabilities/1` and implements `mcp_resource_protocol`. Optionally supports the elicitation capability (`elicitation/create`) when the application declares it via `capabilities/1`.

> - Tool discovery: Tools are discovered from objects implementing the `mcp_tool_protocol`. Tool metadata (descriptions, parameter schemas) is derived from `info/2` and `mode/2` directives.

> - Prompt discovery: Prompts are discovered from objects implementing the `mcp_prompt_protocol`. Prompt metadata (names, descriptions, arguments) is declared via the `prompts/1` predicate.

> - Resource discovery: Resources are discovered from objects implementing the `mcp_resource_protocol`. Resource metadata (URIs, names, descriptions, MIME types) is declared via the `resources/1` predicate.

> - Auto-dispatch: When an object does not define `tool_call/3` or `tool_call/4` for a tool, the server auto-dispatches: it calls the predicate as a message to the object, collects output-mode arguments, and returns them as text content.

> - Elicitation: When the application declares `elicitation` in its `capabilities/1`, the server constructs an elicit closure and passes it to `tool_call/4`. The closure sends `elicitation/create` requests to the client and reads back the user response. This enables interactive tools that can ask the user questions during execution.

> - Error handling: Predicate failures and exceptions both result in MCP tool-level errors with `isError` set to `true`.

Inherited public predicates:
check_option/1 check_options/1 default_option/1 default_options/1 option/2 option/3 valid_option/1 valid_options/1

## Public predicates

### `start/2`

Starts the MCP server with the given server name and application object. The application object must implement the `mcp_tool_protocol` protocol. Reads JSON-RPC messages from standard input and writes responses to standard output using Content-Length framing. Blocks until the client disconnects or an exit signal is received.

Compilation flags:
`static`
Template:
`start(Name,Application)`
Mode and number of proofs:
`start(+atom,+object_identifier)` - `one`

### `start/3`

Starts the MCP server with the given server name, application object, and options. Currently supported options: `server_version(Version)` to set the server version (default `'1.0.0'`), `server_title(Title)` to set the server display title (default `''`, omitted when empty).

Compilation flags:
`static`
Template:
`start(Name,Application,Options)`
Mode and number of proofs:
`start(+atom,+object_identifier,+list)` - `one`

### `start/4`

Starts the MCP server with custom input and output streams. Useful for testing or non-stdio transports. Uses default options.

Compilation flags:
`static`
Template:
`start(Name,Application,Input,Output)`
Mode and number of proofs:
`start(+atom,+object_identifier,+stream,+stream)` - `one`

### `start/5`

Starts the MCP server with custom input and output streams and options.

Compilation flags:
`static`
Template:
`start(Name,Application,Input,Output,Options)`
Mode and number of proofs:
`start(+atom,+object_identifier,+stream,+stream,+list)` - `one`

### `elicit_request/5`

Sends an `elicitation/create` request to the MCP client and reads the response. `Input` and `Output` are the I/O streams. `Message` is the prompt text (an atom). `RequestedSchema` is a curly-term JSON Schema describing the input to request from the user (e.g., `{type-object, properties-{answer-{type-string, enum-[yes, no]}}, required-[answer]}`). `Answer` is unified with `accept(Content)` (where `Content` is the user response as a curly-term), `decline`, or `cancel`. This predicate is typically not called directly but through the elicit closure passed to `tool_call/4`.

Compilation flags:
`static`
Template:
`elicit_request(Input,Output,Message,RequestedSchema,Answer)`
Mode and number of proofs:
`elicit_request(+stream,+stream,+atom,+compound,--compound)` - `one`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

### `initialized_/0`

Flag indicating that the server has been initialized.

Compilation flags:
`dynamic`
Mode and number of proofs:
`initialized_` - `zero_or_one`

### `application_/1`

Current application object.

Compilation flags:
`dynamic`
Template:
`application_(Application)`
Mode and number of proofs:
`application_(?object_identifier)` - `zero_or_one`

### `server_name_/1`

Current server name.

Compilation flags:
`dynamic`
Template:
`server_name_(Name)`
Mode and number of proofs:
`server_name_(?atom)` - `zero_or_one`

### `server_version_/1`

Current server version.

Compilation flags:
`dynamic`
Template:
`server_version_(Version)`
Mode and number of proofs:
`server_version_(?atom)` - `zero_or_one`

### `server_title_/1`

Current server display title.

Compilation flags:
`dynamic`
Template:
`server_title_(Title)`
Mode and number of proofs:
`server_title_(?atom)` - `zero_or_one`

### `elicit_counter_/1`

Counter for elicitation request identifiers.

Compilation flags:
`dynamic`
Template:
`elicit_counter_(Counter)`
Mode and number of proofs:
`elicit_counter_(?integer)` - `zero_or_one`

### `application_capabilities_/1`

Cached application capabilities list.

Compilation flags:
`dynamic`
Template:
`application_capabilities_(Capabilities)`
Mode and number of proofs:
`application_capabilities_(?list)` - `zero_or_one`

## Operators

(none)