use std::{
collections::{BTreeMap, HashMap, HashSet},
fmt,
marker::PhantomData,
sync::{
Arc, Mutex,
atomic::{AtomicU64, Ordering},
},
};
use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64_STANDARD};
use serde_json::{Map, Value};
use stateknot_core::{
BoxFuture, CapabilityIdentity, Digest, SkillActingWindow, SkillActingWindowDuration,
SkillActingWindowId, SkillActingWindowOpenRequest, SkillActingWindowRevocation,
SkillActingWindowRevocationReason, SkillActivationApproval, SkillActivationApprovalId,
SkillActivationScope, SkillActivationSource, SkillActivationStore, SkillActivationStoreFailure,
SkillAuthorizationSubject,
};
use thiserror::Error;
use crate::{
MCP_SKILLS_EXTENSION_ID, McpCachePolicy, McpClient, StatelessMcpClientError,
mcp_server_skill::{
parse_frontmatter, validate_frontmatter, validate_relative_path, validate_skill_uri,
},
mcp_skill_tool::{McpSkillToolBinding, McpSkillToolInvocation, McpSkillToolOperation},
};
const MEBIBYTE: usize = 1024 * 1024;
const MAX_SKILL_URI_BYTES: usize = 4096;
const MAX_CURSOR_BYTES: usize = 4096;
const MAX_MIME_TYPE_BYTES: usize = 255;
const MAX_ORIGIN_LABEL_BYTES: usize = 128;
const MAX_TOOL_NAME_BYTES: usize = 1024;
const SKILL_DOCUMENT: &str = "SKILL.md";
const SKILLS_LIST_METHOD: &str = "skills/list";
const SKILLS_GET_METHOD: &str = "skills/get";
const RESOURCE_READ_METHOD: &str = "resources/read";
pub const MCP_SKILL_MAXIMUM_BYTES: usize = 16 * MEBIBYTE;
pub const MCP_SKILL_MAXIMUM_FILES: usize = 512;
pub const MCP_SKILL_MAXIMUM_FRONTMATTER_BYTES: usize = 64 * 1024;
pub const MCP_SKILL_WIRE_RESPONSE_BYTES: usize = 104 * MEBIBYTE;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct McpSkillCapabilities {
directory_read: bool,
}
impl McpSkillCapabilities {
#[must_use]
pub const fn directory_read(self) -> bool {
self.directory_read
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct McpSkillResource {
uri: Arc<str>,
digest: Arc<str>,
size: usize,
relative_path: Arc<str>,
}
impl McpSkillResource {
#[must_use]
pub fn uri(&self) -> &str {
&self.uri
}
#[must_use]
pub fn digest(&self) -> &str {
&self.digest
}
#[must_use]
pub const fn size(&self) -> usize {
self.size
}
#[must_use]
pub fn relative_path(&self) -> &str {
&self.relative_path
}
}
#[derive(Clone)]
pub struct McpSkillEntry {
binding_id: u64,
uri: Arc<str>,
name: Arc<str>,
description: Arc<str>,
frontmatter: Arc<Map<String, Value>>,
resources: Arc<BTreeMap<String, McpSkillResource>>,
manifest_digest: Arc<str>,
total_bytes: usize,
}
impl McpSkillEntry {
#[must_use]
pub fn uri(&self) -> &str {
&self.uri
}
#[must_use]
pub fn name(&self) -> &str {
&self.name
}
#[must_use]
pub fn description(&self) -> &str {
&self.description
}
#[must_use]
pub fn frontmatter(&self) -> &Map<String, Value> {
&self.frontmatter
}
pub fn resources(&self) -> impl ExactSizeIterator<Item = &McpSkillResource> {
self.resources.values()
}
#[must_use]
pub const fn total_bytes(&self) -> usize {
self.total_bytes
}
#[must_use]
pub fn manifest_digest(&self) -> &str {
&self.manifest_digest
}
fn skill_document(&self) -> &McpSkillResource {
self.resources
.get(self.uri())
.expect("validated Skill manifests contain SKILL.md")
}
fn resource_by_path(&self, relative_path: &str) -> Option<&McpSkillResource> {
self.resources
.values()
.find(|resource| resource.relative_path() == relative_path)
}
}
impl fmt::Debug for McpSkillEntry {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("McpSkillEntry")
.field("uri", &self.uri)
.field("name", &self.name)
.field("resources", &self.resources.len())
.field("total_bytes", &self.total_bytes)
.field("manifest_digest", &self.manifest_digest)
.finish_non_exhaustive()
}
}
#[derive(Clone, Debug)]
pub struct McpSkillPage {
skills: Vec<McpSkillEntry>,
next_cursor: Option<Box<str>>,
cache: McpCachePolicy,
}
impl McpSkillPage {
#[must_use]
pub fn skills(&self) -> &[McpSkillEntry] {
&self.skills
}
#[must_use]
pub fn next_cursor(&self) -> Option<&str> {
self.next_cursor.as_deref()
}
#[must_use]
pub const fn cache(&self) -> &McpCachePolicy {
&self.cache
}
}
#[derive(Clone, Debug)]
pub struct McpSkillCatalog {
skills: Vec<McpSkillEntry>,
}
impl McpSkillCatalog {
#[must_use]
pub fn skills(&self) -> &[McpSkillEntry] {
&self.skills
}
#[must_use]
pub fn find_uri(&self, uri: &str) -> Option<&McpSkillEntry> {
self.skills.iter().find(|entry| entry.uri() == uri)
}
}
#[derive(Clone, Debug)]
pub struct McpSkillResourceContent {
uri: Arc<str>,
mime_type: Option<Arc<str>>,
bytes: Arc<[u8]>,
}
impl McpSkillResourceContent {
#[must_use]
pub fn uri(&self) -> &str {
&self.uri
}
#[must_use]
pub fn mime_type(&self) -> Option<&str> {
self.mime_type.as_deref()
}
#[must_use]
pub fn bytes(&self) -> &[u8] {
&self.bytes
}
}
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum McpSkillClientError {
#[error(transparent)]
Transport(#[from] StatelessMcpClientError),
#[error("MCP client was not configured for Skills")]
ClientSkillsDisabled,
#[error("MCP server did not advertise the Resources capability required by Skills")]
ResourcesNotAdvertised,
#[error("MCP server did not advertise the Skills extension")]
SkillsNotAdvertised,
#[error("MCP Skills capability is invalid")]
InvalidCapability,
#[error("dynamic MCP Skills are unsupported by the static Host profile")]
DynamicSkillUnsupported,
#[error("MCP Skills catalog response is invalid")]
InvalidCatalog,
#[error("MCP Skills lookup response is invalid")]
InvalidLookup,
#[error("MCP Skill entry is invalid")]
InvalidEntry,
#[error("MCP Skills pagination cursor is invalid")]
InvalidPagination,
#[error("MCP Skills catalog exceeds its page limit")]
CatalogPageLimit,
#[error("MCP Skills catalog exceeds its entry limit")]
CatalogTooLarge,
#[error("MCP Skills catalog contains a duplicate URI")]
DuplicateSkillUri,
#[error("MCP Skill resource response is invalid")]
InvalidResource,
}
impl McpClient {
pub fn skill_capabilities(&self) -> Result<McpSkillCapabilities, McpSkillClientError> {
if !self.options().skills_enabled() {
return Err(McpSkillClientError::ClientSkillsDisabled);
}
if !self.server().supports_resources() {
return Err(McpSkillClientError::ResourcesNotAdvertised);
}
let extensions = self
.server()
.capabilities()
.get("extensions")
.and_then(Value::as_object)
.ok_or(McpSkillClientError::SkillsNotAdvertised)?;
let value = extensions
.get(MCP_SKILLS_EXTENSION_ID)
.ok_or(McpSkillClientError::SkillsNotAdvertised)?;
let object = value
.as_object()
.ok_or(McpSkillClientError::InvalidCapability)?;
let directory_read = match object.get("directoryRead") {
Some(value) => value
.as_bool()
.ok_or(McpSkillClientError::InvalidCapability)?,
None => false,
};
Ok(McpSkillCapabilities { directory_read })
}
pub async fn list_skills_page(
&self,
cursor: Option<&str>,
) -> Result<McpSkillPage, McpSkillClientError> {
self.skill_capabilities()?;
if cursor.is_some_and(|cursor| cursor.is_empty() || cursor.len() > MAX_CURSOR_BYTES) {
return Err(McpSkillClientError::InvalidPagination);
}
let mut params = Map::new();
if let Some(cursor) = cursor {
params.insert("cursor".to_owned(), Value::String(cursor.to_owned()));
}
let result = self
.send_extension_rpc(SKILLS_LIST_METHOD, None, params)
.await?;
parse_skill_page(
&result,
self.binding_id(),
self.options().maximum_skill_catalog_entries(),
)
}
pub async fn list_skills(&self) -> Result<McpSkillCatalog, McpSkillClientError> {
let mut cursor: Option<Box<str>> = None;
let mut seen_cursors = HashSet::new();
let mut seen_uris = HashSet::new();
let mut skills = Vec::new();
for _ in 0..self.options().maximum_catalog_pages() {
let page = self.list_skills_page(cursor.as_deref()).await?;
let next_len = skills
.len()
.checked_add(page.skills.len())
.ok_or(McpSkillClientError::CatalogTooLarge)?;
if next_len > self.options().maximum_skill_catalog_entries() {
return Err(McpSkillClientError::CatalogTooLarge);
}
for skill in page.skills {
if !seen_uris.insert(skill.uri().to_owned()) {
return Err(McpSkillClientError::DuplicateSkillUri);
}
skills.push(skill);
}
let Some(next) = page.next_cursor else {
return Ok(McpSkillCatalog { skills });
};
if !seen_cursors.insert(next.to_string()) {
return Err(McpSkillClientError::InvalidPagination);
}
cursor = Some(next);
}
Err(McpSkillClientError::CatalogPageLimit)
}
pub async fn get_skill(&self, uri: &str) -> Result<McpSkillEntry, McpSkillClientError> {
self.skill_capabilities()?;
if uri.is_empty() || uri.len() > MAX_SKILL_URI_BYTES {
return Err(McpSkillClientError::InvalidEntry);
}
let result = self
.send_extension_rpc(
SKILLS_GET_METHOD,
None,
Map::from_iter([("uri".to_owned(), Value::String(uri.to_owned()))]),
)
.await?;
let object = result
.as_object()
.ok_or(McpSkillClientError::InvalidLookup)?;
validate_complete(object, McpSkillClientError::InvalidLookup)?;
parse_required_cache(object).map_err(|()| McpSkillClientError::InvalidLookup)?;
let entry = parse_skill_entry(
object
.get("skill")
.ok_or(McpSkillClientError::InvalidLookup)?,
self.binding_id(),
)?;
if entry.uri() != uri {
return Err(McpSkillClientError::InvalidLookup);
}
Ok(entry)
}
pub async fn read_skill_resource(
&self,
uri: &str,
) -> Result<McpSkillResourceContent, McpSkillClientError> {
self.skill_capabilities()?;
if uri.is_empty() || uri.len() > MAX_SKILL_URI_BYTES {
return Err(McpSkillClientError::InvalidResource);
}
let result = self
.send_extension_rpc(
RESOURCE_READ_METHOD,
Some(uri),
Map::from_iter([("uri".to_owned(), Value::String(uri.to_owned()))]),
)
.await?;
parse_resource_content(&result, uri)
}
}
fn parse_skill_page(
value: &Value,
binding_id: u64,
maximum_entries: usize,
) -> Result<McpSkillPage, McpSkillClientError> {
let object = value
.as_object()
.ok_or(McpSkillClientError::InvalidCatalog)?;
validate_complete(object, McpSkillClientError::InvalidCatalog)?;
let cache = parse_required_cache(object).map_err(|()| McpSkillClientError::InvalidCatalog)?;
let entries = object
.get("skills")
.and_then(Value::as_array)
.filter(|entries| entries.len() <= maximum_entries)
.ok_or(McpSkillClientError::InvalidCatalog)?;
let mut skills = Vec::with_capacity(entries.len());
let mut seen_uris = HashSet::new();
for value in entries {
let entry = parse_skill_entry(value, binding_id)?;
if !seen_uris.insert(entry.uri().to_owned()) {
return Err(McpSkillClientError::DuplicateSkillUri);
}
skills.push(entry);
}
let next_cursor = match object.get("nextCursor") {
Some(value) => Some(
value
.as_str()
.filter(|cursor| !cursor.is_empty() && cursor.len() <= MAX_CURSOR_BYTES)
.ok_or(McpSkillClientError::InvalidPagination)?
.to_owned()
.into_boxed_str(),
),
None => None,
};
Ok(McpSkillPage {
skills,
next_cursor,
cache,
})
}
fn parse_skill_entry(value: &Value, binding_id: u64) -> Result<McpSkillEntry, McpSkillClientError> {
let object = value.as_object().ok_or(McpSkillClientError::InvalidEntry)?;
let uri = object
.get("uri")
.and_then(Value::as_str)
.filter(|uri| !uri.is_empty() && uri.len() <= MAX_SKILL_URI_BYTES)
.ok_or(McpSkillClientError::InvalidEntry)?;
let uri_parent = validate_skill_uri(uri).map_err(|_| McpSkillClientError::InvalidEntry)?;
let frontmatter = object
.get("frontmatter")
.and_then(Value::as_object)
.cloned()
.ok_or(McpSkillClientError::InvalidEntry)?;
if serde_json::to_vec(&frontmatter)
.map_err(|_| McpSkillClientError::InvalidEntry)?
.len()
> MCP_SKILL_MAXIMUM_FRONTMATTER_BYTES
{
return Err(McpSkillClientError::InvalidEntry);
}
validate_frontmatter(&frontmatter).map_err(|_| McpSkillClientError::InvalidEntry)?;
let name = frontmatter
.get("name")
.and_then(Value::as_str)
.ok_or(McpSkillClientError::InvalidEntry)?;
if name != uri_parent {
return Err(McpSkillClientError::InvalidEntry);
}
let description = frontmatter
.get("description")
.and_then(Value::as_str)
.ok_or(McpSkillClientError::InvalidEntry)?;
let resources = match object.get("resources") {
Some(Value::String(value)) if value == "dynamic" => {
return Err(McpSkillClientError::DynamicSkillUnsupported);
}
Some(Value::Array(resources)) => resources,
_ => return Err(McpSkillClientError::InvalidEntry),
};
if resources.is_empty() || resources.len() > MCP_SKILL_MAXIMUM_FILES {
return Err(McpSkillClientError::InvalidEntry);
}
let root = uri
.strip_suffix(SKILL_DOCUMENT)
.ok_or(McpSkillClientError::InvalidEntry)?;
let mut manifest = BTreeMap::new();
let mut total_bytes = 0usize;
for resource in resources {
let resource = parse_skill_resource(resource, uri, root)?;
total_bytes = total_bytes
.checked_add(resource.size())
.ok_or(McpSkillClientError::InvalidEntry)?;
if total_bytes > MCP_SKILL_MAXIMUM_BYTES
|| manifest
.insert(resource.uri().to_owned(), resource)
.is_some()
{
return Err(McpSkillClientError::InvalidEntry);
}
}
if !manifest.contains_key(uri) {
return Err(McpSkillClientError::InvalidEntry);
}
let manifest_digest = manifest_binding_digest(uri, manifest.values());
Ok(McpSkillEntry {
binding_id,
uri: Arc::from(uri),
name: Arc::from(name),
description: Arc::from(description),
frontmatter: Arc::new(frontmatter),
resources: Arc::new(manifest),
manifest_digest: Arc::from(manifest_digest),
total_bytes,
})
}
fn parse_skill_resource(
value: &Value,
skill_uri: &str,
root: &str,
) -> Result<McpSkillResource, McpSkillClientError> {
let object = value.as_object().ok_or(McpSkillClientError::InvalidEntry)?;
let uri = object
.get("uri")
.and_then(Value::as_str)
.filter(|uri| !uri.is_empty() && uri.len() <= MAX_SKILL_URI_BYTES)
.ok_or(McpSkillClientError::InvalidEntry)?;
let relative_path = if uri == skill_uri {
SKILL_DOCUMENT
} else {
uri.strip_prefix(root)
.ok_or(McpSkillClientError::InvalidEntry)?
};
validate_relative_path(relative_path).map_err(|_| McpSkillClientError::InvalidEntry)?;
if format!("{root}{relative_path}") != uri {
return Err(McpSkillClientError::InvalidEntry);
}
let digest = object
.get("digest")
.and_then(Value::as_str)
.filter(|digest| valid_sha256(digest))
.ok_or(McpSkillClientError::InvalidEntry)?;
let size = object
.get("size")
.and_then(Value::as_u64)
.and_then(|size| usize::try_from(size).ok())
.filter(|size| *size <= MCP_SKILL_MAXIMUM_BYTES)
.ok_or(McpSkillClientError::InvalidEntry)?;
Ok(McpSkillResource {
uri: Arc::from(uri),
digest: Arc::from(digest),
size,
relative_path: Arc::from(relative_path),
})
}
fn valid_sha256(value: &str) -> bool {
value.len() == 71
&& value.starts_with("sha256:")
&& value[7..]
.bytes()
.all(|byte| byte.is_ascii_digit() || matches!(byte, b'a'..=b'f'))
}
fn manifest_binding_digest<'a>(
skill_uri: &str,
resources: impl Iterator<Item = &'a McpSkillResource>,
) -> String {
let mut material = b"stateknot/mcp-skills/approval/v1".to_vec();
append_digest_part(&mut material, skill_uri.as_bytes());
for resource in resources {
append_digest_part(&mut material, resource.uri().as_bytes());
append_digest_part(&mut material, resource.digest().as_bytes());
append_digest_part(&mut material, &(resource.size() as u64).to_be_bytes());
}
Digest::sha256(material).to_string()
}
fn append_digest_part(target: &mut Vec<u8>, value: &[u8]) {
target.extend_from_slice(&(value.len() as u64).to_be_bytes());
target.extend_from_slice(value);
}
fn parse_resource_content(
value: &Value,
expected_uri: &str,
) -> Result<McpSkillResourceContent, McpSkillClientError> {
let object = value
.as_object()
.ok_or(McpSkillClientError::InvalidResource)?;
validate_complete(object, McpSkillClientError::InvalidResource)?;
let contents = object
.get("contents")
.and_then(Value::as_array)
.filter(|contents| contents.len() == 1)
.ok_or(McpSkillClientError::InvalidResource)?;
let content = contents[0]
.as_object()
.ok_or(McpSkillClientError::InvalidResource)?;
let uri = content
.get("uri")
.and_then(Value::as_str)
.filter(|uri| *uri == expected_uri)
.ok_or(McpSkillClientError::InvalidResource)?;
let mime_type = match content.get("mimeType") {
Some(value) => {
let mime = value
.as_str()
.filter(|mime| {
!mime.is_empty()
&& mime.len() <= MAX_MIME_TYPE_BYTES
&& mime.trim() == *mime
&& mime.parse::<mime::Mime>().is_ok()
})
.ok_or(McpSkillClientError::InvalidResource)?;
Some(Arc::from(mime))
}
None => None,
};
let bytes = match (content.get("text"), content.get("blob")) {
(Some(Value::String(text)), None) => text.as_bytes().to_vec(),
(None, Some(Value::String(blob))) => BASE64_STANDARD
.decode(blob)
.map_err(|_| McpSkillClientError::InvalidResource)?,
_ => return Err(McpSkillClientError::InvalidResource),
};
if bytes.len() > MCP_SKILL_MAXIMUM_BYTES {
return Err(McpSkillClientError::InvalidResource);
}
Ok(McpSkillResourceContent {
uri: Arc::from(uri),
mime_type,
bytes: Arc::from(bytes),
})
}
fn validate_complete(
object: &Map<String, Value>,
error: McpSkillClientError,
) -> Result<(), McpSkillClientError> {
if object.get("resultType").and_then(Value::as_str) == Some("complete") {
Ok(())
} else {
Err(error)
}
}
fn parse_required_cache(object: &Map<String, Value>) -> Result<McpCachePolicy, ()> {
let ttl_ms = object.get("ttlMs").and_then(Value::as_u64).ok_or(())?;
let scope = object
.get("cacheScope")
.and_then(Value::as_str)
.filter(|scope| matches!(*scope, "private" | "public"))
.ok_or(())?;
Ok(McpCachePolicy::required(ttl_ms, scope.into()))
}
#[derive(Clone, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct McpSkillOrigin(Arc<str>);
impl McpSkillOrigin {
pub fn new(value: impl Into<String>) -> Result<Self, McpSkillOriginError> {
let value = value.into();
if value.is_empty() {
return Err(McpSkillOriginError::Empty);
}
if value.len() > MAX_ORIGIN_LABEL_BYTES {
return Err(McpSkillOriginError::TooLong);
}
if value.trim() != value {
return Err(McpSkillOriginError::BoundaryWhitespace);
}
if value.chars().any(char::is_control) {
return Err(McpSkillOriginError::ControlCharacter);
}
Ok(Self(Arc::from(value)))
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
}
impl fmt::Debug for McpSkillOrigin {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_tuple("McpSkillOrigin")
.field(&self.0)
.finish()
}
}
#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum McpSkillOriginError {
#[error("MCP Skill origin label is empty")]
Empty,
#[error("MCP Skill origin label is too long")]
TooLong,
#[error("MCP Skill origin label has boundary whitespace")]
BoundaryWhitespace,
#[error("MCP Skill origin label contains a control character")]
ControlCharacter,
}
#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct McpSkillIdentity {
origin: McpSkillOrigin,
uri: Arc<str>,
}
impl McpSkillIdentity {
#[must_use]
pub fn origin(&self) -> &McpSkillOrigin {
&self.origin
}
#[must_use]
pub fn uri(&self) -> &str {
&self.uri
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum McpSkillActivationSource {
Direct,
Nested {
identity: McpSkillIdentity,
parent_window_id: SkillActingWindowId,
},
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct McpSkillActivationAttempt {
approval_id: SkillActivationApprovalId,
window_id: SkillActingWindowId,
}
impl McpSkillActivationAttempt {
#[must_use]
pub fn generate() -> Self {
Self {
approval_id: SkillActivationApprovalId::generate(),
window_id: SkillActingWindowId::generate(),
}
}
#[must_use]
pub const fn new(
approval_id: SkillActivationApprovalId,
window_id: SkillActingWindowId,
) -> Self {
Self {
approval_id,
window_id,
}
}
#[must_use]
pub const fn approval_id(self) -> SkillActivationApprovalId {
self.approval_id
}
#[must_use]
pub const fn window_id(self) -> SkillActingWindowId {
self.window_id
}
}
#[derive(Clone, Debug)]
pub struct McpSkillActivationRequest {
identity: McpSkillIdentity,
source: McpSkillActivationSource,
entry: McpSkillEntry,
scope: SkillActivationScope,
attempt: McpSkillActivationAttempt,
}
impl McpSkillActivationRequest {
#[must_use]
pub const fn identity(&self) -> &McpSkillIdentity {
&self.identity
}
#[must_use]
pub const fn source(&self) -> &McpSkillActivationSource {
&self.source
}
#[must_use]
pub const fn entry(&self) -> &McpSkillEntry {
&self.entry
}
#[must_use]
pub fn scope(&self) -> &SkillActivationScope {
&self.scope
}
#[must_use]
pub const fn attempt(&self) -> McpSkillActivationAttempt {
self.attempt
}
#[must_use]
pub fn requested_allowed_tools(&self) -> Option<&str> {
self.entry
.frontmatter()
.get("allowed-tools")
.and_then(Value::as_str)
}
}
#[derive(Clone, Debug)]
pub struct McpSkillToolAuthorizationRequest {
identity: McpSkillIdentity,
manifest_digest: Arc<str>,
activation_id: u64,
acting_window_id: SkillActingWindowId,
tool_name: Arc<str>,
tool_identity: Option<CapabilityIdentity>,
tool_descriptor_digest: Option<Digest>,
operation: McpSkillToolOperation,
invocation: Option<McpSkillToolInvocation>,
host_code_execution: bool,
requested_allowed_tools: Option<Arc<str>>,
}
impl McpSkillToolAuthorizationRequest {
#[must_use]
pub const fn identity(&self) -> &McpSkillIdentity {
&self.identity
}
#[must_use]
pub fn manifest_digest(&self) -> &str {
&self.manifest_digest
}
#[must_use]
pub const fn activation_id(&self) -> u64 {
self.activation_id
}
#[must_use]
pub const fn acting_window_id(&self) -> SkillActingWindowId {
self.acting_window_id
}
#[must_use]
pub fn tool_name(&self) -> &str {
&self.tool_name
}
#[must_use]
pub const fn tool_identity(&self) -> Option<&CapabilityIdentity> {
self.tool_identity.as_ref()
}
#[must_use]
pub const fn tool_descriptor_digest(&self) -> Option<Digest> {
self.tool_descriptor_digest
}
#[must_use]
pub const fn operation(&self) -> McpSkillToolOperation {
self.operation
}
#[must_use]
pub const fn invocation(&self) -> Option<&McpSkillToolInvocation> {
self.invocation.as_ref()
}
#[must_use]
pub const fn host_code_execution(&self) -> bool {
self.host_code_execution
}
#[must_use]
pub fn requested_allowed_tools(&self) -> Option<&str> {
self.requested_allowed_tools.as_deref()
}
}
pub trait McpSkillHostPolicy: Send + Sync + 'static {
fn approve_activation(
&self,
request: McpSkillActivationRequest,
) -> BoxFuture<'_, Result<McpSkillActivationGrant, McpSkillHostPolicyError>>;
fn authorize_tool_call(
&self,
request: McpSkillToolAuthorizationRequest,
) -> BoxFuture<'_, Result<McpSkillToolAuthorizationGrant, McpSkillHostPolicyError>>;
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct McpSkillActivationGrant {
policy: CapabilityIdentity,
policy_digest: Digest,
decision_digest: Digest,
duration: SkillActingWindowDuration,
}
impl McpSkillActivationGrant {
#[must_use]
pub const fn new(
policy: CapabilityIdentity,
policy_digest: Digest,
decision_digest: Digest,
duration: SkillActingWindowDuration,
) -> Self {
Self {
policy,
policy_digest,
decision_digest,
duration,
}
}
#[must_use]
pub const fn policy(&self) -> &CapabilityIdentity {
&self.policy
}
#[must_use]
pub const fn policy_digest(&self) -> Digest {
self.policy_digest
}
#[must_use]
pub const fn decision_digest(&self) -> Digest {
self.decision_digest
}
#[must_use]
pub const fn duration(&self) -> SkillActingWindowDuration {
self.duration
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct McpSkillToolAuthorizationGrant {
policy: CapabilityIdentity,
policy_digest: Digest,
decision_digest: Digest,
}
impl McpSkillToolAuthorizationGrant {
#[must_use]
pub const fn new(
policy: CapabilityIdentity,
policy_digest: Digest,
decision_digest: Digest,
) -> Self {
Self {
policy,
policy_digest,
decision_digest,
}
}
#[must_use]
pub const fn policy(&self) -> &CapabilityIdentity {
&self.policy
}
#[must_use]
pub const fn policy_digest(&self) -> Digest {
self.policy_digest
}
#[must_use]
pub const fn decision_digest(&self) -> Digest {
self.decision_digest
}
}
#[derive(Clone, Copy, Debug, Default)]
pub struct DenyMcpSkillHostPolicy;
impl McpSkillHostPolicy for DenyMcpSkillHostPolicy {
fn approve_activation(
&self,
_request: McpSkillActivationRequest,
) -> BoxFuture<'_, Result<McpSkillActivationGrant, McpSkillHostPolicyError>> {
Box::pin(async { Err(McpSkillHostPolicyError::Denied) })
}
fn authorize_tool_call(
&self,
_request: McpSkillToolAuthorizationRequest,
) -> BoxFuture<'_, Result<McpSkillToolAuthorizationGrant, McpSkillHostPolicyError>> {
Box::pin(async { Err(McpSkillHostPolicyError::Denied) })
}
}
#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum McpSkillHostPolicyError {
#[error("MCP Skill Host policy denied the operation")]
Denied,
#[error("MCP Skill Host policy is unavailable")]
Unavailable,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct McpSkillHostOptions {
maximum_cache_entries: usize,
maximum_cache_bytes: usize,
}
impl McpSkillHostOptions {
pub const HARD_MAXIMUM_CACHE_ENTRIES: usize = 65_536;
pub const HARD_MAXIMUM_CACHE_BYTES: usize = 1024 * MEBIBYTE;
pub const fn new(
maximum_cache_entries: usize,
maximum_cache_bytes: usize,
) -> Result<Self, McpSkillHostOptionsError> {
if maximum_cache_entries == 0 || maximum_cache_bytes == 0 {
return Err(McpSkillHostOptionsError::ZeroLimit);
}
if maximum_cache_entries > Self::HARD_MAXIMUM_CACHE_ENTRIES
|| maximum_cache_bytes > Self::HARD_MAXIMUM_CACHE_BYTES
{
return Err(McpSkillHostOptionsError::AboveHardMaximum);
}
Ok(Self {
maximum_cache_entries,
maximum_cache_bytes,
})
}
#[must_use]
pub const fn maximum_cache_entries(self) -> usize {
self.maximum_cache_entries
}
#[must_use]
pub const fn maximum_cache_bytes(self) -> usize {
self.maximum_cache_bytes
}
}
impl Default for McpSkillHostOptions {
fn default() -> Self {
Self {
maximum_cache_entries: 4096,
maximum_cache_bytes: 64 * MEBIBYTE,
}
}
}
#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum McpSkillHostOptionsError {
#[error("MCP Skill Host cache limits must be positive")]
ZeroLimit,
#[error("MCP Skill Host cache limit exceeds the hard maximum")]
AboveHardMaximum,
}
#[derive(Clone, Debug, Eq, Hash, PartialEq)]
struct CacheKey {
binding_id: u64,
origin: McpSkillOrigin,
uri: Arc<str>,
digest: Arc<str>,
size: usize,
}
#[derive(Default)]
struct MemoryCache {
entries: HashMap<CacheKey, Arc<McpSkillResourceContent>>,
bytes: usize,
}
struct McpSkillHostInner {
client: McpClient,
origin: McpSkillOrigin,
scope: SkillActivationScope,
policy: Arc<dyn McpSkillHostPolicy>,
activation_store: Arc<dyn SkillActivationStore>,
options: McpSkillHostOptions,
cache: Mutex<MemoryCache>,
next_activation_id: AtomicU64,
}
#[derive(Clone)]
pub struct McpSkillHost {
inner: Arc<McpSkillHostInner>,
}
impl McpSkillHost {
pub fn new(
client: McpClient,
origin: McpSkillOrigin,
scope: SkillActivationScope,
policy: Arc<dyn McpSkillHostPolicy>,
activation_store: Arc<dyn SkillActivationStore>,
options: McpSkillHostOptions,
) -> Result<Self, McpSkillHostError> {
let transport = client.options().transport();
if transport.maximum_response_bytes() < MCP_SKILL_WIRE_RESPONSE_BYTES
|| transport.maximum_sse_line_bytes() < MCP_SKILL_WIRE_RESPONSE_BYTES
|| transport.maximum_sse_event_bytes() < MCP_SKILL_WIRE_RESPONSE_BYTES
|| transport.maximum_sse_total_bytes() < MCP_SKILL_WIRE_RESPONSE_BYTES
{
return Err(McpSkillHostError::TransportProfileTooSmall);
}
client.skill_capabilities()?;
Ok(Self {
inner: Arc::new(McpSkillHostInner {
client,
origin,
scope,
policy,
activation_store,
options,
cache: Mutex::new(MemoryCache::default()),
next_activation_id: AtomicU64::new(1),
}),
})
}
#[must_use]
pub fn origin(&self) -> &McpSkillOrigin {
&self.inner.origin
}
#[must_use]
pub fn scope(&self) -> &SkillActivationScope {
&self.inner.scope
}
pub async fn list_skills(&self) -> Result<McpSkillCatalog, McpSkillHostError> {
Ok(self.inner.client.list_skills().await?)
}
pub async fn get_skill(&self, uri: &str) -> Result<McpSkillEntry, McpSkillHostError> {
Ok(self.inner.client.get_skill(uri).await?)
}
pub fn identity(&self, entry: &McpSkillEntry) -> Result<McpSkillIdentity, McpSkillHostError> {
self.require_local_entry(entry)?;
Ok(McpSkillIdentity {
origin: self.inner.origin.clone(),
uri: entry.uri.clone(),
})
}
pub async fn activate_uri(
&self,
uri: &str,
attempt: McpSkillActivationAttempt,
) -> Result<McpActivatedSkill, McpSkillHostError> {
let entry = self.get_skill(uri).await?;
self.activate_entry(entry, McpSkillActivationSource::Direct, attempt)
.await
}
pub async fn activate(
&self,
entry: &McpSkillEntry,
attempt: McpSkillActivationAttempt,
) -> Result<McpActivatedSkill, McpSkillHostError> {
self.activate_entry(entry.clone(), McpSkillActivationSource::Direct, attempt)
.await
}
async fn activate_entry(
&self,
entry: McpSkillEntry,
source: McpSkillActivationSource,
attempt: McpSkillActivationAttempt,
) -> Result<McpActivatedSkill, McpSkillHostError> {
let identity = self.identity(&entry)?;
let grant = self
.inner
.policy
.approve_activation(McpSkillActivationRequest {
identity: identity.clone(),
source: source.clone(),
entry: entry.clone(),
scope: self.inner.scope.clone(),
attempt,
})
.await
.map_err(map_activation_policy_error)?;
let instructions = self.verify_instructions(&identity, &entry).await?;
let subject = Self::authorization_subject(&identity, &entry)?;
let durable_source = match source {
McpSkillActivationSource::Direct => SkillActivationSource::Direct,
McpSkillActivationSource::Nested {
parent_window_id, ..
} => SkillActivationSource::Nested { parent_window_id },
};
let approval = SkillActivationApproval::new(
attempt.approval_id(),
self.inner.scope.clone(),
subject,
durable_source,
grant.policy().clone(),
grant.policy_digest(),
grant.decision_digest(),
grant.duration(),
)
.map_err(|_| McpSkillHostError::ActivationEvidenceInvalid)?;
let window = self
.inner
.activation_store
.open(SkillActingWindowOpenRequest::new(
attempt.window_id(),
approval.clone(),
))
.await
.map_err(map_activation_store_error)?;
if window.window_id() != attempt.window_id() || window.approval() != &approval {
return Err(McpSkillHostError::ActivationStoreRejected);
}
self.inner
.activation_store
.assert_active(window.clone())
.await
.map_err(map_activation_store_error)?;
self.finish_activation(identity, entry, instructions, window)
}
pub async fn resume(
&self,
entry: &McpSkillEntry,
window_id: SkillActingWindowId,
) -> Result<McpActivatedSkill, McpSkillHostError> {
self.require_local_entry(entry)?;
let window = self
.inner
.activation_store
.load_active(self.inner.scope.tenant_id().clone(), window_id)
.await
.map_err(map_activation_store_error)?;
let identity = self.identity(entry)?;
let subject = Self::authorization_subject(&identity, entry)?;
if window.approval().scope() != &self.inner.scope || window.approval().subject() != &subject
{
return Err(McpSkillHostError::ActivationStoreRejected);
}
let instructions = self.verify_instructions(&identity, entry).await?;
self.inner
.activation_store
.assert_active(window.clone())
.await
.map_err(map_activation_store_error)?;
self.finish_activation(identity, entry.clone(), instructions, window)
}
fn finish_activation(
&self,
identity: McpSkillIdentity,
entry: McpSkillEntry,
instructions: McpVerifiedSkillFile,
window: SkillActingWindow,
) -> Result<McpActivatedSkill, McpSkillHostError> {
let activation_id = allocate_monotonic_id(&self.inner.next_activation_id)
.ok_or(McpSkillHostError::ActivationIdExhausted)?;
Ok(McpActivatedSkill {
host: self.clone(),
identity,
entry,
instructions,
activation_id,
window,
})
}
async fn verify_instructions(
&self,
identity: &McpSkillIdentity,
entry: &McpSkillEntry,
) -> Result<McpVerifiedSkillFile, McpSkillHostError> {
let instructions = self
.verified_file(identity, entry, entry.skill_document())
.await?;
let text = std::str::from_utf8(instructions.bytes())
.map_err(|_| McpSkillHostError::SkillDocumentNotUtf8)?;
let frontmatter = parse_frontmatter(text)
.map_err(|_| McpSkillHostError::FrontmatterVerificationFailed)?;
if &frontmatter != entry.frontmatter() {
return Err(McpSkillHostError::FrontmatterVerificationFailed);
}
Ok(instructions)
}
fn authorization_subject(
identity: &McpSkillIdentity,
entry: &McpSkillEntry,
) -> Result<SkillAuthorizationSubject, McpSkillHostError> {
let manifest_digest = entry
.manifest_digest()
.parse()
.map_err(|_| McpSkillHostError::ActivationEvidenceInvalid)?;
SkillAuthorizationSubject::new(
"mcp",
identity.origin().as_str(),
identity.uri(),
manifest_digest,
)
.map_err(|_| McpSkillHostError::ActivationEvidenceInvalid)
}
async fn verified_file(
&self,
identity: &McpSkillIdentity,
entry: &McpSkillEntry,
resource: &McpSkillResource,
) -> Result<McpVerifiedSkillFile, McpSkillHostError> {
self.require_local_entry(entry)?;
let key = CacheKey {
binding_id: entry.binding_id,
origin: identity.origin.clone(),
uri: resource.uri.clone(),
digest: resource.digest.clone(),
size: resource.size,
};
if let Some(content) = self
.inner
.cache
.lock()
.map_err(|_| McpSkillHostError::CacheUnavailable)?
.entries
.get(&key)
.cloned()
{
return Ok(McpVerifiedSkillFile::new(
identity.clone(),
resource.relative_path.clone(),
content,
));
}
let content = Arc::new(
self.inner
.client
.read_skill_resource(resource.uri())
.await?,
);
verify_resource(resource, &content)?;
let mut cache = self
.inner
.cache
.lock()
.map_err(|_| McpSkillHostError::CacheUnavailable)?;
if let Some(existing) = cache.entries.get(&key).cloned() {
return Ok(McpVerifiedSkillFile::new(
identity.clone(),
resource.relative_path.clone(),
existing,
));
}
let next_bytes = cache.bytes.checked_add(content.bytes().len());
if cache.entries.len() < self.inner.options.maximum_cache_entries
&& next_bytes.is_some_and(|bytes| bytes <= self.inner.options.maximum_cache_bytes)
{
cache.bytes = next_bytes.expect("checked cache size exists");
cache.entries.insert(key, Arc::clone(&content));
}
Ok(McpVerifiedSkillFile::new(
identity.clone(),
resource.relative_path.clone(),
content,
))
}
fn require_local_entry(&self, entry: &McpSkillEntry) -> Result<(), McpSkillHostError> {
if entry.binding_id == self.inner.client.binding_id() {
Ok(())
} else {
Err(McpSkillHostError::ForeignClientBinding)
}
}
}
impl fmt::Debug for McpSkillHost {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("McpSkillHost")
.field("origin", &self.inner.origin)
.field("scope", &self.inner.scope)
.field("client", &self.inner.client)
.field("options", &self.inner.options)
.field("policy", &"[POLICY]")
.field("activation_store", &"[DURABLE STORE]")
.finish_non_exhaustive()
}
}
#[derive(Clone)]
pub struct McpVerifiedSkillFile {
identity: McpSkillIdentity,
relative_path: Arc<str>,
content: Arc<McpSkillResourceContent>,
}
impl McpVerifiedSkillFile {
fn new(
identity: McpSkillIdentity,
relative_path: Arc<str>,
content: Arc<McpSkillResourceContent>,
) -> Self {
Self {
identity,
relative_path,
content,
}
}
#[must_use]
pub const fn identity(&self) -> &McpSkillIdentity {
&self.identity
}
#[must_use]
pub fn relative_path(&self) -> &str {
&self.relative_path
}
#[must_use]
pub fn uri(&self) -> &str {
self.content.uri()
}
#[must_use]
pub fn mime_type(&self) -> Option<&str> {
self.content.mime_type()
}
#[must_use]
pub fn bytes(&self) -> &[u8] {
self.content.bytes()
}
#[must_use]
pub fn text(&self) -> Option<&str> {
std::str::from_utf8(self.bytes()).ok()
}
}
impl fmt::Debug for McpVerifiedSkillFile {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("McpVerifiedSkillFile")
.field("identity", &self.identity)
.field("relative_path", &self.relative_path)
.field("uri", &self.content.uri)
.field("size", &self.content.bytes.len())
.finish_non_exhaustive()
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct McpSkillDirectoryEntry {
relative_path: Arc<str>,
uri: Arc<str>,
directory: bool,
}
impl McpSkillDirectoryEntry {
#[must_use]
pub fn relative_path(&self) -> &str {
&self.relative_path
}
#[must_use]
pub fn uri(&self) -> &str {
&self.uri
}
#[must_use]
pub const fn is_directory(&self) -> bool {
self.directory
}
}
pub struct McpActivatedSkill {
host: McpSkillHost,
identity: McpSkillIdentity,
entry: McpSkillEntry,
instructions: McpVerifiedSkillFile,
activation_id: u64,
window: SkillActingWindow,
}
impl McpActivatedSkill {
#[must_use]
pub const fn identity(&self) -> &McpSkillIdentity {
&self.identity
}
#[must_use]
pub const fn entry(&self) -> &McpSkillEntry {
&self.entry
}
#[must_use]
pub const fn instructions(&self) -> &McpVerifiedSkillFile {
&self.instructions
}
#[must_use]
pub const fn acting_window(&self) -> &SkillActingWindow {
&self.window
}
pub async fn read_file(
&self,
relative_path: &str,
) -> Result<McpVerifiedSkillFile, McpSkillHostError> {
self.assert_active().await?;
validate_relative_path(relative_path)
.map_err(|_| McpSkillHostError::InvalidRelativePath)?;
let resource = self
.entry
.resource_by_path(relative_path)
.ok_or(McpSkillHostError::ResourceOutsideHeldManifest)?;
let file = self
.host
.verified_file(&self.identity, &self.entry, resource)
.await?;
self.assert_active().await?;
Ok(file)
}
pub fn list_directory(
&self,
relative_directory: &str,
) -> Result<Vec<McpSkillDirectoryEntry>, McpSkillHostError> {
if !relative_directory.is_empty() {
validate_relative_path(relative_directory)
.map_err(|_| McpSkillHostError::InvalidRelativePath)?;
}
let prefix = if relative_directory.is_empty() {
String::new()
} else {
format!("{relative_directory}/")
};
let root = self
.entry
.uri()
.strip_suffix(SKILL_DOCUMENT)
.expect("validated Skill URI ends in SKILL.md");
let mut children = BTreeMap::<String, bool>::new();
for resource in self.entry.resources() {
let Some(remainder) = resource.relative_path().strip_prefix(&prefix) else {
continue;
};
if remainder.is_empty() {
continue;
}
let (name, directory) = remainder
.split_once('/')
.map_or((remainder, false), |(name, _)| (name, true));
let child = format!("{prefix}{name}");
children
.entry(child)
.and_modify(|current| *current |= directory)
.or_insert(directory);
}
Ok(children
.into_iter()
.map(|(relative_path, directory)| McpSkillDirectoryEntry {
uri: Arc::from(format!("{root}{relative_path}")),
relative_path: Arc::from(relative_path),
directory,
})
.collect())
}
pub async fn activate_nested(
&self,
relative_skill_document: &str,
attempt: McpSkillActivationAttempt,
) -> Result<McpActivatedSkill, McpSkillHostError> {
self.assert_active().await?;
validate_relative_path(relative_skill_document)
.map_err(|_| McpSkillHostError::InvalidRelativePath)?;
if relative_skill_document == SKILL_DOCUMENT
|| !relative_skill_document.ends_with("/SKILL.md")
{
return Err(McpSkillHostError::InvalidNestedSkill);
}
let resource = self
.entry
.resource_by_path(relative_skill_document)
.ok_or(McpSkillHostError::ResourceOutsideHeldManifest)?;
let nested = self.host.get_skill(resource.uri()).await?;
self.host
.activate_entry(
nested,
McpSkillActivationSource::Nested {
identity: self.identity.clone(),
parent_window_id: self.window.window_id(),
},
attempt,
)
.await
}
pub async fn revoke(
&self,
reason: SkillActingWindowRevocationReason,
) -> Result<SkillActingWindowRevocation, McpSkillHostError> {
self.host
.inner
.activation_store
.revoke(self.window.clone(), reason)
.await
.map_err(map_activation_store_error)
}
async fn assert_active(&self) -> Result<(), McpSkillHostError> {
self.host
.inner
.activation_store
.assert_active(self.window.clone())
.await
.map_err(map_activation_store_error)
}
pub async fn authorize_tool_call<'activation>(
&'activation self,
tool_name: &str,
host_code_execution: bool,
) -> Result<McpSkillExecutionPermit<'activation>, McpSkillHostError> {
self.assert_active().await?;
if tool_name.is_empty()
|| tool_name.len() > MAX_TOOL_NAME_BYTES
|| tool_name.trim() != tool_name
|| tool_name.chars().any(char::is_control)
{
return Err(McpSkillHostError::InvalidToolName);
}
let requested_allowed_tools = self
.entry
.frontmatter()
.get("allowed-tools")
.and_then(Value::as_str)
.map(Arc::from);
let grant = self
.host
.inner
.policy
.authorize_tool_call(McpSkillToolAuthorizationRequest {
identity: self.identity.clone(),
manifest_digest: self.entry.manifest_digest.clone(),
activation_id: self.activation_id,
acting_window_id: self.window.window_id(),
tool_name: Arc::from(tool_name),
tool_identity: None,
tool_descriptor_digest: None,
operation: McpSkillToolOperation::Execute,
invocation: None,
host_code_execution,
requested_allowed_tools,
})
.await
.map_err(map_tool_policy_error)?;
self.assert_active().await?;
Ok(McpSkillExecutionPermit {
identity: self.identity.clone(),
manifest_digest: self.entry.manifest_digest.clone(),
activation_id: self.activation_id,
acting_window: self.window.clone(),
tool_name: Arc::from(tool_name),
tool_identity: None,
tool_descriptor_digest: None,
operation: McpSkillToolOperation::Execute,
invocation: None,
host_code_execution,
grant,
activation: PhantomData,
})
}
pub(crate) async fn authorize_bound_tool_operation<'activation>(
&'activation self,
binding: &McpSkillToolBinding,
operation: McpSkillToolOperation,
invocation: &McpSkillToolInvocation,
) -> Result<McpSkillExecutionPermit<'activation>, McpSkillHostError> {
self.assert_active().await?;
let requested_allowed_tools = self
.entry
.frontmatter()
.get("allowed-tools")
.and_then(Value::as_str)
.map(Arc::from);
let tool_name = Arc::from(binding.tool_name());
let grant = self
.host
.inner
.policy
.authorize_tool_call(McpSkillToolAuthorizationRequest {
identity: self.identity.clone(),
manifest_digest: self.entry.manifest_digest.clone(),
activation_id: self.activation_id,
acting_window_id: self.window.window_id(),
tool_name: Arc::clone(&tool_name),
tool_identity: Some(binding.identity().clone()),
tool_descriptor_digest: Some(binding.descriptor_digest()),
operation,
invocation: Some(invocation.clone()),
host_code_execution: binding.host_code_execution(),
requested_allowed_tools,
})
.await
.map_err(map_tool_policy_error)?;
Ok(McpSkillExecutionPermit {
identity: self.identity.clone(),
manifest_digest: self.entry.manifest_digest.clone(),
activation_id: self.activation_id,
acting_window: self.window.clone(),
tool_name,
tool_identity: Some(binding.identity().clone()),
tool_descriptor_digest: Some(binding.descriptor_digest()),
operation,
invocation: Some(invocation.clone()),
host_code_execution: binding.host_code_execution(),
grant,
activation: PhantomData,
})
}
}
impl fmt::Debug for McpActivatedSkill {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("McpActivatedSkill")
.field("identity", &self.identity)
.field("manifest_digest", &self.entry.manifest_digest)
.field("activation_id", &self.activation_id)
.field("acting_window", &self.window)
.finish_non_exhaustive()
}
}
#[derive(Debug)]
#[must_use = "the permit must be consumed by the exact approved Tool execution"]
pub struct McpSkillExecutionPermit<'activation> {
identity: McpSkillIdentity,
manifest_digest: Arc<str>,
activation_id: u64,
acting_window: SkillActingWindow,
tool_name: Arc<str>,
tool_identity: Option<CapabilityIdentity>,
tool_descriptor_digest: Option<Digest>,
operation: McpSkillToolOperation,
invocation: Option<McpSkillToolInvocation>,
host_code_execution: bool,
grant: McpSkillToolAuthorizationGrant,
activation: PhantomData<&'activation McpActivatedSkill>,
}
impl McpSkillExecutionPermit<'_> {
#[must_use]
pub const fn identity(&self) -> &McpSkillIdentity {
&self.identity
}
#[must_use]
pub fn manifest_digest(&self) -> &str {
&self.manifest_digest
}
#[must_use]
pub const fn activation_id(&self) -> u64 {
self.activation_id
}
#[must_use]
pub const fn acting_window(&self) -> &SkillActingWindow {
&self.acting_window
}
#[must_use]
pub fn tool_name(&self) -> &str {
&self.tool_name
}
#[must_use]
pub const fn tool_identity(&self) -> Option<&CapabilityIdentity> {
self.tool_identity.as_ref()
}
#[must_use]
pub const fn tool_descriptor_digest(&self) -> Option<Digest> {
self.tool_descriptor_digest
}
#[must_use]
pub const fn operation(&self) -> McpSkillToolOperation {
self.operation
}
#[must_use]
pub const fn invocation(&self) -> Option<&McpSkillToolInvocation> {
self.invocation.as_ref()
}
#[must_use]
pub const fn host_code_execution(&self) -> bool {
self.host_code_execution
}
#[must_use]
pub const fn grant(&self) -> &McpSkillToolAuthorizationGrant {
&self.grant
}
}
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum McpSkillHostError {
#[error(transparent)]
Client(#[from] McpSkillClientError),
#[error("MCP client transport limits are too small for static Skills")]
TransportProfileTooSmall,
#[error("MCP Skill entry belongs to another client binding")]
ForeignClientBinding,
#[error("MCP Skill activation was denied")]
ActivationDenied,
#[error("MCP Skill Tool call was denied")]
ToolCallDenied,
#[error("MCP Skill Host policy is unavailable")]
PolicyUnavailable,
#[error("MCP Skill resource verification failed")]
ResourceVerificationFailed,
#[error("MCP Skill SKILL.md is not UTF-8")]
SkillDocumentNotUtf8,
#[error("MCP Skill frontmatter verification failed")]
FrontmatterVerificationFailed,
#[error("MCP Skill resource is outside the held Manifest")]
ResourceOutsideHeldManifest,
#[error("invalid MCP Skill relative path")]
InvalidRelativePath,
#[error("invalid nested MCP Skill activation")]
InvalidNestedSkill,
#[error("invalid MCP Skill Tool name")]
InvalidToolName,
#[error("MCP Skill private cache is unavailable")]
CacheUnavailable,
#[error("MCP Skill activation identifier space is exhausted")]
ActivationIdExhausted,
#[error("MCP Skill activation evidence is invalid")]
ActivationEvidenceInvalid,
#[error("MCP Skill activation store is unavailable")]
ActivationStoreUnavailable,
#[error("MCP Skill acting window was not found")]
ActingWindowNotFound,
#[error("MCP Skill acting window is inactive")]
ActingWindowInactive,
#[error("MCP Skill activation store rejected the evidence")]
ActivationStoreRejected,
}
fn verify_resource(
expected: &McpSkillResource,
actual: &McpSkillResourceContent,
) -> Result<(), McpSkillHostError> {
if actual.uri() != expected.uri()
|| actual.bytes().len() != expected.size()
|| Digest::sha256(actual.bytes()).to_string() != expected.digest()
{
return Err(McpSkillHostError::ResourceVerificationFailed);
}
Ok(())
}
fn map_activation_policy_error(error: McpSkillHostPolicyError) -> McpSkillHostError {
match error {
McpSkillHostPolicyError::Denied => McpSkillHostError::ActivationDenied,
McpSkillHostPolicyError::Unavailable => McpSkillHostError::PolicyUnavailable,
}
}
fn map_tool_policy_error(error: McpSkillHostPolicyError) -> McpSkillHostError {
match error {
McpSkillHostPolicyError::Denied => McpSkillHostError::ToolCallDenied,
McpSkillHostPolicyError::Unavailable => McpSkillHostError::PolicyUnavailable,
}
}
fn map_activation_store_error(
error: stateknot_core::SkillActivationStoreError,
) -> McpSkillHostError {
let failure = error.failure();
drop(error);
match failure {
SkillActivationStoreFailure::Unavailable => McpSkillHostError::ActivationStoreUnavailable,
SkillActivationStoreFailure::NotFound => McpSkillHostError::ActingWindowNotFound,
SkillActivationStoreFailure::Inactive => McpSkillHostError::ActingWindowInactive,
_ => McpSkillHostError::ActivationStoreRejected,
}
}
fn allocate_monotonic_id(counter: &AtomicU64) -> Option<u64> {
counter
.fetch_update(Ordering::AcqRel, Ordering::Acquire, |current| {
(current != u64::MAX).then_some(current + 1)
})
.ok()
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
#[test]
fn static_entry_rejects_dynamic_and_manifest_escape() {
let dynamic = json!({
"uri": "skill://review/SKILL.md",
"frontmatter": {"name": "review", "description": "Review code."},
"resources": "dynamic"
});
assert!(matches!(
parse_skill_entry(&dynamic, 1),
Err(McpSkillClientError::DynamicSkillUnsupported)
));
let escaped = json!({
"uri": "skill://review/SKILL.md",
"frontmatter": {"name": "review", "description": "Review code."},
"resources": [{
"uri": "skill://other/secret.txt",
"digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"size": 1
}]
});
assert!(matches!(
parse_skill_entry(&escaped, 1),
Err(McpSkillClientError::InvalidEntry)
));
}
#[test]
fn origin_and_digest_are_stable_and_collision_safe() {
assert!(McpSkillOrigin::new(" docs ").is_err());
let first = McpSkillIdentity {
origin: McpSkillOrigin::new("docs-a").unwrap(),
uri: Arc::from("skill://review/SKILL.md"),
};
let second = McpSkillIdentity {
origin: McpSkillOrigin::new("docs-b").unwrap(),
uri: Arc::from("skill://review/SKILL.md"),
};
assert_ne!(first, second);
}
#[test]
fn static_entry_requires_a_complete_bounded_canonical_manifest() {
let digest = "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
let missing_document = json!({
"uri": "skill://review/SKILL.md",
"frontmatter": {"name": "review", "description": "Review code."},
"resources": [{
"uri": "skill://review/reference.md",
"digest": digest,
"size": 1
}]
});
assert!(matches!(
parse_skill_entry(&missing_document, 1),
Err(McpSkillClientError::InvalidEntry)
));
let upper_case_digest = json!({
"uri": "skill://review/SKILL.md",
"frontmatter": {"name": "review", "description": "Review code."},
"resources": [{
"uri": "skill://review/SKILL.md",
"digest": "sha256:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"size": 1
}]
});
assert!(matches!(
parse_skill_entry(&upper_case_digest, 1),
Err(McpSkillClientError::InvalidEntry)
));
let oversized_frontmatter = json!({
"uri": "skill://review/SKILL.md",
"frontmatter": {
"name": "review",
"description": "Review code.",
"untrusted-extension": "x".repeat(MCP_SKILL_MAXIMUM_FRONTMATTER_BYTES)
},
"resources": [{
"uri": "skill://review/SKILL.md",
"digest": digest,
"size": 1
}]
});
assert!(matches!(
parse_skill_entry(&oversized_frontmatter, 1),
Err(McpSkillClientError::InvalidEntry)
));
}
#[test]
fn catalog_page_enforces_the_callers_entry_ceiling() {
let entry = json!({
"uri": "skill://review/SKILL.md",
"frontmatter": {"name": "review", "description": "Review code."},
"resources": [{
"uri": "skill://review/SKILL.md",
"digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"size": 1
}]
});
let page = json!({
"resultType": "complete",
"skills": [entry.clone(), entry],
"ttlMs": 0,
"cacheScope": "private"
});
assert!(matches!(
parse_skill_page(&page, 1, 1),
Err(McpSkillClientError::InvalidCatalog)
));
}
}