Package com.isomorphic.datasource

# Class MCPServlet

java.lang.Object
jakarta.servlet.GenericServlet
jakarta.servlet.http.HttpServlet
com.isomorphic.datasource.MCPServlet

All Implemented Interfaces:
  `jakarta.servlet.Servlet`, `jakarta.servlet.ServletConfig`, `Serializable`

public class MCPServlet extends jakarta.servlet.http.HttpServlet
Servlet that exposes SmartClient `DataSource` operations over HTTP using the Model Context Protocol (MCP) and JSON-RPC 2.0.

This servlet is intended for machine-driven clients (for example AI agents, command-line tools or other backend services) that need a compact, schema-driven interface to the `DataSources` configured on the server. Application code normally interacts with DataSources directly via `DSRequest` and `DSResponse`; this servlet provides an HTTP façade for external consumers.

## JSON-RPC methods

The servlet accepts HTTP `POST` requests with `Content-Type: application/json` and a standard JSON-RPC 2.0 envelope. The supported `method` values are:

- `"tools/list"` – discovers all DataSource-backed MCP tools and their JSON Schema input definitions.
- `"tools/call"` – executes a single tool (for example `"ds.order.fetch"`) and returns the corresponding DataSource response.

## Tool naming

For each defined `DataSource` with id `&lt;id&gt;`, this servlet exposes zero or more tools named:

- `ds.<id>.fetch`
- `ds.<id>.add`
- `ds.<id>.update`
- `ds.<id>.remove`
- `ds.<id>.fetchAdvanced` (only if the DataSource reports support for advanced criteria and/or aggregation)

A client can use `"tools/list"` once to discover the available tool names for each DataSource and then call those tools repeatedly via `"tools/call"`.

## "tools/list" result

The result for `"tools/list"` is an object containing:

- `tools` – an array of tool descriptors. Each descriptor includes:
  - `name` – the tool name (for example `"ds.order.fetch"`).
  - `description` – a short human-readable description.
  - `inputSchema` – a JSON Schema fragment describing the expected `arguments` object for that tool.
- `definitions` – shared JSON Schema definitions that can be referenced from tool schemas, including:
  - `"record:<id>"` – the record shape for a particular DataSource, derived from its `DSField` metadata.
  - `"criteria"` – flat criteria objects (field/value pairs).
  - `"advancedCriteria"` – nested AdvancedCriteria objects where supported.

## "tools/call" parameters

The `"tools/call"` method expects a JSON-RPC `params` object of the form:

- `name` – the name of a tool previously reported by `"tools/list"` (for example `"ds.order.fetch"`).
- `arguments` – an object matching the tool's `inputSchema`. Common members include:
  - `criteria` or `advancedCriteria` for filtering.
  - `data` for `add` / `update` payloads.
  - `startRow` / `endRow` for paging.
  - `sortBy`, and for advanced fetches, `groupBy` and `summaryFunctions` where the DataSource allows aggregation.

The servlet maps these arguments to a `DSRequest`, applies additional validations appropriate to each operation (for example forbidding AdvancedCriteria on simple `fetch`, or requiring non-empty criteria for `update` and `remove`), executes the request and converts the `DSResponse` back into MCP form.

## Results and errors

On success, the JSON-RPC `result` contains a single `content` entry with `type:"json"` and `text` set to a serialized SmartClient-style payload (status, row range and data list). On failure, parameter and validation errors are reported as JSON-RPC `error` responses with an appropriate numeric `code`, a human-readable `message` and optional structured `data` (for example DataSource status and field-level errors).

This servlet is typically registered under an application-specific URL via `web.xml` or programmatic servlet registration. The HTTP contract and MCP methods described above are considered the supported external interface; all helper methods inside this class are internal implementation details.

See Also:
  - `DataSource`
  - `DSRequest`
  - `DSResponse`
  - Serialized Form