yeti_types/plugins/

mcp.rs

//! MCP tool registry hooks.
//!
//! Two hook chains let wasm plugin-apps extend yeti-mcp's tool surface
//! without depending on yeti-mcp (a host-only crate) directly:
//!
//!  - [`LIST_TOOLS_HOOK_CHAIN_NAME`] — accumulator. The host seeds the
//!    request with the auto-generated inventory; plugins extend the
//!    list. Final response is the union (host-prefilled +
//!    plugin-contributed).
//!  - [`CALL_TOOL_HOOK_CHAIN_NAME`] — dispatcher. yeti-mcp consults
//!    the chain before its built-in `{table}_{op}` CRUD dispatcher.
//!    First plugin whose service returns `Some(value)` wins; if every
//!    plugin returns `None`, the host falls through to the auto-
//!    inventory dispatch.
//!
//! `ToolDefinition` / `ToolAnnotations` mirror the shapes already
//! defined in `yeti-mcp-domain::types`, but live here so foundation-
//! layer crates can reference them without violating layering
//! (yeti-types is L0; yeti-mcp-domain is request-band L3). yeti-mcp
//! converts host-typed ↔ domain-typed at the dispatch boundary.

use serde::{Deserialize, Deserializer, Serialize, Serializer};
use serde_json::Value;
use tower::util::BoxCloneSyncService;

use crate::error::YetiError;

/// JSON-as-string wire helper: bincode 1.3 cannot round-trip
/// `serde_json::Value` because `Value::deserialize` uses
/// `deserialize_any`, which bincode rejects (`DeserializeAnyNotSupported`).
/// The hook bridge uses bincode for performance and consistency
/// with the auth bridges, so any `Value` field we want to carry across
/// must be encoded as a JSON string and parsed back on the other side.
///
/// These helpers are used via `#[serde(with = "value_as_json_string")]`
/// on the `Value` fields below. The host- and guest-side serializers
/// both round-trip through the same JSON text, so the wire shape is
/// stable across the WIT boundary.
mod value_as_json_string {
    use super::{Deserialize, Deserializer, Serializer, Value};

    pub(super) fn serialize<S>(value: &Value, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        let s = serde_json::to_string(value).map_err(serde::ser::Error::custom)?;
        serializer.serialize_str(&s)
    }

    pub(super) fn deserialize<'de, D>(deserializer: D) -> Result<Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        serde_json::from_str(&s).map_err(serde::de::Error::custom)
    }
}

/// Versioned hook chain name for tool-list accumulator services
/// (ADR-009).
///
/// See [`super::oauth::OAUTH_HOOK_CHAIN_NAME`] for the rationale
/// behind placing the constant in yeti-types rather than in the
/// owning static plugin (yeti-mcp).
pub const LIST_TOOLS_HOOK_CHAIN_NAME: &str = "yeti.mcp.list_tools.v1";

/// Versioned hook chain name for tool-call dispatcher services
/// (ADR-009).
pub const CALL_TOOL_HOOK_CHAIN_NAME: &str = "yeti.mcp.call_tool.v1";

/// Tower-shaped tool-list accumulator service. Plugins register
/// `BoxCloneSyncService::new(service_fn(...))` against this type;
/// yeti-mcp chains every registered service per `tools/list` MCP
/// request, threading the accumulating tool list through each.
pub type ListToolsService = BoxCloneSyncService<ListToolsRequest, ListToolsResponse, YetiError>;

/// Tower-shaped tool-call dispatcher service. Plugins register
/// `BoxCloneSyncService::new(service_fn(...))` against this type;
/// yeti-mcp consults the chain per `tools/call` MCP request and the
/// first service to return `Some(value)` wins.
pub type CallToolService = BoxCloneSyncService<CallToolRequest, CallToolResponse, YetiError>;

/// MCP tool definition — wire-shape mirror of
/// `yeti_mcp_domain::types::ToolDefinition`.
///
/// Kept here so wasm plugin-apps can construct tool definitions
/// against `yeti_sdk::prelude::plugins::mcp::ToolDefinition` without
/// pulling in yeti-mcp-domain (which is request-band and not part of
/// the SDK surface). yeti-mcp converts to/from the domain type at the
/// dispatch boundary.
///
/// Bincode is the on-the-wire format for the hook bridge.
/// We intentionally do **not** use `#[serde(skip_serializing_if)]` /
/// `#[serde(rename_all)]` here — bincode is a positional binary
/// format and omitting fields on serialize but expecting them on
/// deserialize is a decode error. The JSON-friendly attributes live
/// on the domain-side `yeti_mcp_domain::types::ToolDefinition` and
/// are applied at the dispatch boundary in
/// `yeti_mcp::dev_resource::ext_tool_to_rmcp`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ToolDefinition {
    /// Tool name (e.g. `"yeti_hello"`, `"widgets_list"`).
    pub name: String,
    /// Human-readable tool description shown in MCP clients.
    pub description: String,
    /// JSON Schema describing the tool's arguments. Most tools use
    /// an object schema (`{"type": "object", "properties": { ... }}`).
    ///
    /// Stored as `serde_json::Value` for ergonomic in-process use; on
    /// the bincode wire it serializes as a JSON string to dodge
    /// `DeserializeAnyNotSupported`.
    #[serde(with = "value_as_json_string")]
    pub input_schema: Value,
    /// Optional MCP-2025-03-26 behavior hints. `None` is equivalent
    /// to "all hints unset."
    pub annotations: Option<ToolAnnotations>,
}

/// Tool behavior annotations (MCP 2025-03-26) — wire-shape mirror of
/// `yeti_mcp_domain::types::ToolAnnotations`.
///
/// See note on [`ToolDefinition`] for why this struct deliberately
/// omits `skip_serializing_if` / `rename_all`.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ToolAnnotations {
    /// Tool does not mutate state. Clients may treat the result as
    /// cacheable.
    pub read_only_hint: Option<bool>,
    /// Tool performs a destructive action (delete, drop, etc.).
    /// Clients should require explicit user confirmation.
    pub destructive_hint: Option<bool>,
    /// Calling the tool multiple times with the same arguments yields
    /// the same effect (no cumulative side effects beyond the first).
    pub idempotent_hint: Option<bool>,
}

/// Input to the tool-list accumulator pipeline.
///
/// `Serialize` + `Deserialize` derives are wire-shape carriers for
/// cross-component hook chains via WIT (bincode payload). Each end of
/// the WIT boundary needs to encode/decode the same struct shape.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ListToolsRequest {
    /// Deployment hash for the request. Hardcoded `"local"` today until
    /// Fabric multi-deployment hosting plumbs a real value through.
    pub deployment_hash: String,
    /// Accumulator. yeti-mcp pre-fills this with the auto-generated
    /// inventory before invoking the chain; each plugin in the chain
    /// receives the (possibly extended) list and returns the next-stage
    /// version. Plugins typically push their additional tools onto the
    /// vec and return it.
    pub tools: Vec<ToolDefinition>,
}

/// Output of the tool-list accumulator pipeline — the final tool list
/// returned to the MCP client.
pub type ListToolsResponse = Vec<ToolDefinition>;

/// Input to the tool-call dispatcher pipeline.
///
/// `Serialize` + `Deserialize` derives carry the wire shape.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CallToolRequest {
    /// Deployment hash for the request. See [`ListToolsRequest`].
    pub deployment_hash: String,
    /// Tool name the client is invoking.
    pub tool_name: String,
    /// JSON-shaped tool arguments. yeti-mcp passes the raw client
    /// payload here; the plugin is responsible for any shape validation.
    ///
    /// See note on [`ToolDefinition::input_schema`] for why this is
    /// bincode-wire-encoded as a JSON string rather than a raw `Value`.
    #[serde(with = "value_as_json_string")]
    pub arguments: Value,
}

/// Output of the tool-call dispatcher pipeline.
///
/// - `Some(value)` — this plugin handled the call; `value` is the
///   tool's response (returned to the MCP client as the tool result).
/// - `None` — this plugin did not handle the call. yeti-mcp continues
///   iterating the chain; if every registered plugin returns `None`,
///   the host falls through to its built-in auto-inventory dispatcher.
///
/// Wrapped in a transparent newtype so the inner `Option<String>` can
/// carry the bincode-safe JSON-text wire encoding of the `Value` (see
/// [`ToolDefinition::input_schema`] for why bincode can't ride a
/// `serde_json::Value` directly). [`CallToolResponse::some`] /
/// [`CallToolResponse::none`] / [`CallToolResponse::value`] are the
/// construction / read helpers.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(transparent)]
pub struct CallToolResponse {
    inner: Option<String>,
}

impl CallToolResponse {
    /// `Ok(None)` equivalent — the plugin did not handle the call.
    /// Yeti-mcp falls through to the next service / auto-inventory.
    #[must_use]
    pub const fn none() -> Self {
        Self { inner: None }
    }

    /// Wrap a `Value` for the wire. Equivalent to `Some(value)` —
    /// the plugin handled the call and `value` is the tool's response.
    #[must_use]
    pub fn some(value: &Value) -> Self {
        // serde_json::to_string is infallible on Value — it only fails
        // for non-serializable types, which Value never is.
        Self {
            inner: Some(serde_json::to_string(value).unwrap_or_else(|_| "null".to_owned())),
        }
    }

    /// Parse the wire form back into the typed `Option<Value>` the
    /// host's dispatcher consumes. Decoding errors flatten to `None`
    /// so a malformed plugin response degrades to "not handled" rather
    /// than poisoning the chain.
    #[must_use]
    pub fn value(&self) -> Option<Value> {
        self.inner
            .as_deref()
            .and_then(|s| serde_json::from_str(s).ok())
    }

    /// True if this response carries a plugin-supplied value
    /// (i.e. `Some(...)`).
    #[must_use]
    pub const fn is_some(&self) -> bool {
        self.inner.is_some()
    }

    /// True if this response is the no-op fall-through (`None`).
    #[must_use]
    pub const fn is_none(&self) -> bool {
        self.inner.is_none()
    }
}

impl From<Option<Value>> for CallToolResponse {
    fn from(value: Option<Value>) -> Self {
        value.as_ref().map_or_else(Self::none, Self::some)
    }
}

impl From<CallToolResponse> for Option<Value> {
    fn from(resp: CallToolResponse) -> Self {
        resp.value()
    }
}