droid-mcp-core/io.droidmcp.core

Package-level declarations

Types

fun interface AuditSink

Host-supplied sink for tools/call audit records. Implementations must be cheap and non-throwing on the calling path — the protocol invokes record synchronously after each call and swallows exceptions so a broken audit backend never fails a tool. The Room-backed implementation lives in the opt-in droid-mcp-audit module; hosts that don't depend on it pay nothing.

BuiltInPrompts

object BuiltInPrompts

Ready-made prompts built on the standard tool modules. Add them with DroidMcp.Builder.addBuiltInPrompts. Each one is listed only while the tools it names are registered and enabled (see McpPrompt.requiredTools), so hosts can add all of them safely.

CompletionContext

class CompletionContext

What a completion (McpPrompt.complete, ResourceProvider.complete) can draw on: the other arguments the user has already filled in, and callTool for reading device data through a read-only tool, e.g. contact names from search_contacts. The server builds the context; the public constructor (no tools, callTool always null) is for testing a completer.

DroidMcp

class DroidMcp

The SDK entry point. Built via DroidMcp.builder / Builder, it owns a ToolRegistry and both transports: an always-on InProcessTransport for on-device LLMs (listTools / callTool) and an optional HttpTransport for desktop MCP clients (startServer).

ElicitationResult

data class ElicitationResult(val action: ElicitationResult.Action, val content: Map<String, Any?> = emptyMap())

The answer to an elicit request.

McpPrompt

interface McpPrompt

A reusable prompt template a client can offer its user (MCP prompts/list / prompts/get). droid-mcp ships a few in BuiltInPrompts; hosts can add their own via DroidMcp.Builder.addPrompt.

McpResource

data class McpResource(val uri: String, val name: String, val title: String? = null, val description: String? = null, val mimeType: String? = null, val size: Long? = null)

A concrete piece of device data a client can read by uri (MCP resources/list).

McpResourceTemplate

data class McpResourceTemplate(val uriTemplate: String, val name: String, val title: String? = null, val description: String? = null, val mimeType: String? = null)

A parameterised family of resources (MCP resources/templates/list), e.g. droidmcp://contacts/{id}. uriTemplate follows RFC 6570.

McpTool

interface McpTool

The contract every droid-mcp tool implements. A tool is a single, self-describing capability — its name, description, and parameters are surfaced verbatim through MCP tools/list, and execute services a tools/call.

OutputSchema

object OutputSchema

Builds the JSON Schema a tool advertises as McpTool.outputSchema, and checks result maps against it.

ParameterType

enum ParameterType : Enum<ParameterType>

The JSON Schema primitive type of a ToolParameter. jsonType is the literal string emitted into the tool's inputSchema ("string", "integer", …).

PermissionHelper

object PermissionHelper

Runtime-permission checks shared by every module's provider object. The SDK never requests permissions (the host app owns its permission UX) — it only inspects what has already been granted, so a tool can decline gracefully.

PermissionStatus

sealed class PermissionStatus

Uniform shape returned by every special-access module's permissionStatus(context) helper. Lets host apps render permission cards inline (e.g. in chat) before the LLM tries to call a tool, with a single switch over a closed type.

ProgressUpdate

data class ProgressUpdate(val progress: Double, val total: Double? = null, val message: String? = null)

One progress update from a running tool; see reportProgress.

PromptArgument

data class PromptArgument(val name: String, val description: String, val required: Boolean = false)

One argument a prompt accepts (MCP prompts/list). Values always arrive as strings.

PromptMessage

data class PromptMessage(val role: PromptMessage.Role, val text: String)

One message of a rendered prompt. droid-mcp prompts are text-only.

PromptRegistry

class PromptRegistry

Thread-safe collection of McpPrompts keyed by name, with change listeners like ToolRegistry.

PromptResult

data class PromptResult(val messages: List<PromptMessage>, val description: String? = null)

The output of McpPrompt.render: the messages plus an optional description of this rendering.

ResourceContents

sealed class ResourceContents

The body of one resource returned by resources/read: either Text or base64 Blob.

ResourceProvider

interface ResourceProvider

Supplies resources for one area of the device (photos, files, contacts, …). Registered through DroidMcp.Builder.addResourceProvider; each module exposes its own, e.g. MediaTools.resources(context).

ResourceRegistry

class ResourceRegistry

Thread-safe collection of ResourceProviders. Changes are reported to addChangeListener subscribers so the HTTP transport can emit notifications/resources/list_changed; providers whose listing changes on their own call notifyChanged.

ToolAnnotations

data class ToolAnnotations(val readOnlyHint: Boolean = false, val destructiveHint: Boolean = false, val idempotentHint: Boolean = false, val openWorldHint: Boolean = false, val title: String? = null)

Behavioural hints attached to a tool, mirroring the MCP tools/list annotation fields. They are advisory metadata for clients and LLMs — the SDK does not enforce them — but the HTTP transport's readOnly server mode uses readOnlyHint to decide which tools to expose.

ToolCallAudit

data class ToolCallAudit(val timestamp: Long, val toolName: String, val clientLabel: String?, val argumentsJson: String?, val success: Boolean, val errorMessage: String?, val durationMs: Long)

One audited tools/call. Captured by McpProtocolImpl after the tool runs and handed to the host's AuditSink.

ToolCallConfirmer

fun interface ToolCallConfirmer

Host callback that approves or declines a tool call before it runs — typically by showing the user a dialog ("Allow send_message to +1 555…?"). Return true to run the tool.

ToolCallRequest

data class ToolCallRequest(val toolName: String, val arguments: Map<String, Any>, val annotations: ToolAnnotations, val clientLabel: String?)

A tool call waiting for the host's approval. See DroidMcp.Builder.confirmToolCalls.

ToolImage

data class ToolImage(val base64: String, val mimeType: String, val dataKey: String? = null)

An image produced by a tool, sent over MCP as an image content block ({"type": "image", "data": <base64>, "mimeType": ...}). Created by ToolResult.withImage.

ToolParameter

@Serializable

data class ToolParameter(val name: String, val description: String, val type: ParameterType, val required: Boolean = false, val itemsType: ParameterType? = null, val enumValues: List<String>? = null, val minimum: Double? = null, val maximum: Double? = null)

A single declared input to an McpTool. The list of these on a tool is compiled into the inputSchema advertised by MCP tools/list, so name and type are part of the wire contract.

ToolRegistry

class ToolRegistry(val toolTimeoutMs: Long = DEFAULT_TOOL_TIMEOUT_MS, confirmer: ToolCallConfirmer? = null, requiresConfirmation: (McpTool) -> Boolean = { it.annotations.destructiveHint })

Thread-safe collection of registered McpTools, keyed by McpTool.name. Backed by a ConcurrentHashMap so tools can be registered and invoked concurrently. Also tracks a host-controlled runtime gate (see setDisabledTools) that hides/blocks tools without unregistering them.

ToolResult

data class ToolResult(val isSuccess: Boolean, val data: Map<String, Any?>?, val errorMessage: String?, val images: List<ToolImage> = emptyList())

The outcome of an McpTool.execute call. Exactly one of data / errorMessage is meaningful, selected by isSuccess. The protocol layer maps a result onto the MCP tools/call response: success becomes content, failure becomes an isError: true payload.

Properties

DROID_MCP_VERSION

const val DROID_MCP_VERSION: String

The droid-mcp SDK version, reported as the server version in the MCP initialize handshake and broadcast over mDNS. Must equal VERSION_NAME in the root gradle.properties (the single source for the published version) — VersionTest enforces it.

Functions

elicit

suspend fun elicit(message: String, requestedSchema: Map<String, Any>): ElicitationResult?

Ask the MCP client's user for input or confirmation while a tool runs (MCP elicitation/create).

reportProgress

suspend fun reportProgress(progress: Double, total: Double? = null, message: String? = null)

Report progress from inside McpTool.execute. Over MCP this becomes a notifications/progress message when the client asked for progress (it sent a progressToken); in-process callers receive it through the onProgress overload of DroidMcp.callTool. Otherwise it does nothing, so tools can call it unconditionally.