Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
//! Tool exposure filter for the MCP server.
//!
//! This lets operators restrict which `onto_*` tools are advertised over MCP
//! (and which can actually be invoked) via configuration or CLI flags.
//!
//! TWO AXES, AND THEY COMPOSE.
//!
//! The first axis is the PROFILE: a named subset of the tool surface sized for
//! one job. A client that is aligning two vocabularies has no use for most of
//! what `src/server.rs` registers, and every tool it has no use for is one more
//! chance to call the wrong one. `expand_profile` is the table and `profiles()`
//! lists the names. No count is written here on purpose: the total is measured
//! from the router by `tests/toolfilter_profiles_test.rs` and stated in
//! `docs/tool-reference.md`, which is the one document allowed to state it.
//!
//! The second axis is the MODE, which is the older mechanism and is unchanged:
//! - `Mode::All` — every tool the profile left standing (default).
//! - `Mode::Allow` — only tools in `list` (or expanded from `groups`).
//! - `Mode::Deny` — all but the tools in `list` (or `groups`).
//!
//! The profile narrows FIRST and the mode narrows what is left, so
//! `--tool-profile alignment --tools-deny onto_push` is the alignment profile
//! minus one tool and neither axis can widen the other. The `groups` on the
//! mode axis (`read_only`, `mutating`, …) cut along a different line: they
//! answer what a caller may be trusted to do, not what it is here to do.
//!
//! THE DEFAULT DOES NOT MOVE. No profile means `full`, which is every tool this
//! build can serve, which is what every existing client already sees.
//!
//! Implementation: applied by removing routes from the rmcp `ToolRouter`
//! before the server is constructed. Removed tools are not advertised via
//! `tools/list` and cannot be invoked via `tools/call`.
use serde::Deserialize;
use std::collections::HashSet;
use rmcp::handler::server::tool::ToolRouter;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Default)]
#[serde(rename_all = "lowercase")]
pub enum Mode {
#[default]
All,
Allow,
Deny,
}
impl Mode {
pub fn parse(s: &str) -> Result<Self, String> {
match s.to_ascii_lowercase().as_str() {
"all" | "" => Ok(Mode::All),
"allow" | "allowlist" | "whitelist" => Ok(Mode::Allow),
"deny" | "denylist" | "blacklist" => Ok(Mode::Deny),
other => Err(format!("unknown tool filter mode: {}", other)),
}
}
}
/// User-facing filter spec.
#[derive(Debug, Clone, Default)]
pub struct ToolFilter {
pub mode: Mode,
/// Explicit tool names.
pub list: Vec<String>,
/// Group names that expand to a curated set of tool names.
pub groups: Vec<String>,
/// Task profile. `None` and `Some("full")` both mean every tool, which is
/// the default and what every client saw before profiles existed.
pub profile: Option<String>,
}
impl ToolFilter {
pub fn all() -> Self {
Self::default()
}
pub fn allow_only(names: impl IntoIterator<Item = String>) -> Self {
Self {
mode: Mode::Allow,
list: names.into_iter().collect(),
groups: vec![],
profile: None,
}
}
pub fn deny(names: impl IntoIterator<Item = String>) -> Self {
Self {
mode: Mode::Deny,
list: names.into_iter().collect(),
groups: vec![],
profile: None,
}
}
/// Resolve the effective set of explicit names (list ∪ expand(groups)).
fn resolved_names(&self) -> HashSet<String> {
let mut out: HashSet<String> = self.list.iter().cloned().collect();
for g in &self.groups {
for n in expand_group(g) {
out.insert(n.to_string());
}
}
out
}
/// A filter that exposes exactly one profile. Errors on an unknown name
/// rather than falling back to `full`.
pub fn with_profile(name: &str) -> Result<Self, String> {
if !is_profile(name) {
return Err(format!(
"unknown tool profile {:?}; known: {}",
name,
profiles().join(", ")
));
}
Ok(Self {
profile: Some(name.to_string()),
..Default::default()
})
}
/// The profile in force, `full` when none was chosen.
pub fn profile_name(&self) -> &str {
self.profile.as_deref().unwrap_or(FULL)
}
/// Whether the PROFILE axis alone lets `tool_name` through.
fn profile_allows(&self, tool_name: &str) -> bool {
match self.profile.as_deref() {
None | Some(FULL) => true,
Some(p) => match expand_profile(p) {
Some(names) => names.contains(&tool_name),
// Unreachable through the CLI, the env var and the config file,
// all three of which refuse an unknown name at startup. Reached
// only by building the struct by hand, and the conservative
// reading of a name nobody recognises is that it names nothing.
None => false,
},
}
}
/// What a client is looking at, for `onto_status` and the startup log.
///
/// `servable` is counted AFTER `remove_unavailable` and `compiled_in`
/// before it, because in a default build eight of the registered tools are
/// behind a Cargo feature and are already gone by the time the operator's
/// filter runs. Folding the two into one number would report the feature
/// gate as something the profile withheld, and the field a user reads to
/// answer "why can I not see it" would name the wrong cause.
pub fn describe(&self, compiled_in: usize, servable: usize, exposed: usize) -> ToolSurface {
ToolSurface {
profile: self.profile_name().to_string(),
mode: match self.mode {
Mode::All => "all",
Mode::Allow => "allow",
Mode::Deny => "deny",
},
compiled_in,
servable_in_this_build: servable,
exposed,
withheld_by_filter: servable.saturating_sub(exposed),
}
}
/// Decide whether `tool_name` should be exposed.
///
/// The profile narrows first and the mode narrows what is left, so naming a
/// tool in `--tools-allow` that the profile does not carry does not bring it
/// back.
pub fn allows(&self, tool_name: &str) -> bool {
self.allows_given(&self.resolved_names(), tool_name)
}
/// `allows` with the resolved name set supplied, so `apply` builds it once
/// for the whole router instead of once per tool. The DECISION lives here
/// and nowhere else: `apply` used to carry its own copy of the match, which
/// is two places for one rule to be changed in.
fn allows_given(&self, names: &HashSet<String>, tool_name: &str) -> bool {
if !self.profile_allows(tool_name) {
return false;
}
match self.mode {
Mode::All => true,
Mode::Allow => names.contains(tool_name),
Mode::Deny => !names.contains(tool_name),
}
}
/// Apply the filter to a `ToolRouter` by removing disallowed routes.
/// Returns the list of removed tool names (for logging/inspection).
///
/// This is the OPERATOR's filter. [`remove_unavailable`] runs first and is
/// not optional: a tool the build cannot serve is never advertised,
/// whatever the operator asked for.
pub fn apply<S>(&self, router: &mut ToolRouter<S>) -> Vec<String>
where
S: Send + Sync + 'static,
{
// The fast path is the DEFAULT path and it has to stay exact: no
// profile and `Mode::All` must remove nothing at all.
if self.mode == Mode::All && matches!(self.profile.as_deref(), None | Some(FULL)) {
return Vec::new();
}
let names = self.resolved_names();
let all: Vec<String> = router
.list_all()
.into_iter()
.map(|t| t.name.to_string())
.collect();
let mut removed = Vec::new();
for name in all {
if !self.allows_given(&names, &name) {
router.remove_route(&name);
removed.push(name);
}
}
removed
}
}
/// The filtered surface as reported to clients.
#[derive(Debug, Clone, serde::Serialize)]
pub struct ToolSurface {
/// `full` when nothing was selected.
pub profile: String,
/// The second axis: `all`, `allow` or `deny`.
pub mode: &'static str,
/// Tools the binary registers, whatever this build can serve.
pub compiled_in: usize,
/// Of those, the ones this feature set can actually serve.
pub servable_in_this_build: usize,
/// Of those, the ones that survived the operator's filter.
pub exposed: usize,
/// The filter's own doing. Non-zero here is the answer to "why can I not
/// see it", and `compiled_in - servable_in_this_build` is the other answer.
pub withheld_by_filter: usize,
}
/// The name that means "everything".
pub const FULL: &str = "full";
/// Tools present in EVERY profile.
///
/// Not a category, a floor. Nothing else in any profile can do anything until a
/// graph is loaded, and a client that cannot check what it loaded or clear a
/// bad load is stuck inside its own profile. Six tools is the price of every
/// profile being self-sufficient, and a profile that is not self-sufficient
/// sends the user back to `full`, which defeats the exercise.
pub const SPINE: &[&str] = &[
"onto_status",
"onto_validate",
"onto_load",
"onto_query",
"onto_stats",
"onto_clear",
];
/// The task-oriented profiles, each the tools for one job, on top of `SPINE`.
///
/// Read off what the tools do in `src/server.rs`, which is why they OVERLAP:
/// `onto_shacl` belongs to judging data and to landing it, `onto_module_extract`
/// to authoring, reasoning and retrieval, and forcing a partition would have
/// left one of those jobs a tool short. The only rule the set has to satisfy is
/// COVERAGE, enforced by
/// `tests/toolfilter_profiles_test.rs::every_registered_tool_is_in_some_profile`:
/// a tool added later and filed under nothing fails the build rather than
/// becoming reachable only from `full` and therefore never missed.
const PROFILES: &[(&str, &str, &[&str])] = &[
(
"authoring",
"Write and edit an ontology: validate, lint, enforce patterns, version, \
extract modules, and pull in vocabularies to build on.",
&[
"onto_save", "onto_convert", "onto_diff", "onto_lint", "onto_lint_feedback",
"onto_defects", "onto_dl_check", "onto_dl_explain", "onto_version", "onto_history",
"onto_rollback", "onto_marketplace", "onto_import", "onto_pull", "onto_push",
"onto_repo_list", "onto_repo_load", "onto_unload", "onto_recompile",
"onto_cache_status", "onto_cache_list", "onto_cache_remove", "onto_enforce",
"onto_enforce_feedback", "onto_ossie_import", "onto_import_schema",
"onto_plugin_list", "onto_plugin_call", "onto_induce", "onto_module_extract",
"onto_conservative_check",
],
),
(
"validation",
"Judge data against an ontology: SHACL shapes, closed-world vocabulary \
checks, shape induction, what the rule table can see, and the \
provenance of what the graph claims.",
&[
"onto_shacl", "onto_shacl_check", "onto_vocab_check", "onto_lint", "onto_defects",
"onto_dlp_boundary", "onto_justify", "onto_coevolve_dependency_graph",
"onto_owl_shacl_coevolve_check", "onto_owl_shacl_coevolve_incremental",
"onto_shape_induce", "onto_shape_combinatorics", "onto_ingest", "onto_map",
"onto_extend", "onto_support_check", "onto_support_verdict", "onto_support_report",
"onto_plugin_list", "onto_plugin_call",
],
),
(
"reasoning",
"Derive consequences and produce the artefacts that can be checked: \
certificates, justifications, first-order export and proof checking, \
DL tableaux, model finding.",
&[
"onto_reason", "onto_reason_incremental", "onto_rules_import", "onto_defects",
"onto_dlp_boundary", "onto_trace_label", "onto_justify", "onto_provenance",
"onto_classify_el",
"onto_dl_check", "onto_dl_explain", "onto_fol_export", "onto_fol_model",
"onto_fol_prove", "onto_closure_diff", "onto_module_extract",
"graph_projection_entailment_check", "graph_projection_lossy_check", "onto_extend",
],
),
(
"alignment",
"Relate two vocabularies: alignment candidates and their feedback loop, \
clinical crosswalks, and the embeddings the scorer uses.",
&[
"onto_align", "onto_align_feedback", "onto_align_fuzzy", "onto_align_flora",
"onto_eval_alignment", "onto_diff", "onto_crosswalk", "onto_enrich",
"onto_validate_clinical", "onto_embed", "onto_search", "onto_similarity",
"onto_hnsw_build", "borderline_partition", "borderline_record_verdict",
],
),
(
"governance",
"Change an ontology in production and answer for it afterwards: plan, \
apply, lock, drift, monitor, policy, packs, conservativity and the \
lineage trail.",
&[
"onto_plan", "onto_apply", "onto_lock", "onto_drift", "onto_enforce",
"onto_enforce_feedback", "onto_monitor", "onto_monitor_clear", "onto_lineage",
"onto_provenance", "onto_conservative_check", "onto_version", "onto_history",
"onto_rollback", "onto_pack", "onto_unpack", "onto_policy_register",
"onto_policy_list", "onto_policy_check", "onto_support_report",
"onto_temporal_snapshot", "onto_temporal_query", "onto_temporal_conflicts",
],
),
(
"data",
"Land external data in the graph and keep it there: file and SQL \
ingest, schema induction, mapping, CDC watermarks, and the two \
temporal clocks.",
&[
"onto_ingest", "onto_induce", "onto_map", "onto_extend", "onto_convert",
"onto_sql_ingest", "onto_import_schema", "onto_sql_sync_state",
"onto_sql_sync_reset", "onto_sql_sync_states_list", "onto_pull", "onto_push",
"onto_shacl", "onto_vocab_check", "onto_temporal_snapshot", "onto_temporal_query",
"onto_temporal_conflicts",
],
),
(
"planning",
"Act on the graph under laws: registered actions, BC+ invariants and \
defaults, PDDL compilation and plan validation.",
&[
"onto_action_register", "onto_action_list", "onto_action_applicable",
"onto_action_apply", "onto_action_apply_concurrent", "onto_certify_action",
"onto_invariant_register", "onto_invariant_list", "onto_invariant_remove",
"onto_invariant_check", "onto_default_register", "onto_default_apply",
"onto_plan_classical", "onto_plan_compile_pddl", "onto_plan_validate",
"onto_policy_check", "onto_lineage",
],
),
(
"retrieval",
"Ground a model on the graph: neighbourhood slices, modules, community \
skeletons, schema-guided extraction, and whether a slice kept what the \
answer rests on.",
&[
"onto_segment_retrieve", "onto_communities", "onto_extract_scaffold",
"onto_extract_validate", "onto_module_extract", "onto_embed", "onto_search",
"onto_similarity", "onto_hnsw_build", "graph_projection_lossy_check",
"graph_projection_entailment_check", "onto_closure_diff",
],
),
(
"evaluation",
"Score the thing rather than run it: competency questions, mmRAG and \
OAEI metrics, and the borderline-verdict loop.",
&[
"onto_cq_run", "onto_verify_cq", "onto_cq_verdicts_list", "eval_rag",
"eval_rag_mmrag", "onto_eval_alignment", "borderline_partition",
"borderline_record_verdict", "onto_shape_induce", "onto_shape_combinatorics",
"onto_diff",
],
),
];
/// Every profile name, `full` first. `full` is not in `PROFILES` because it is
/// not a subset: it is the absence of one. Giving it a list would mean a tool
/// added to `src/server.rs` had to be added to `full` by hand to stay visible,
/// which is the unreachability this whole exercise is against.
pub fn profiles() -> Vec<&'static str> {
let mut out = vec![FULL];
out.extend(PROFILES.iter().map(|(n, _, _)| *n));
out
}
/// One line saying what a profile is for, or `None` if the name is unknown.
pub fn profile_description(name: &str) -> Option<&'static str> {
if name == FULL {
return Some(
"Every tool this build can serve. The default, and what every \
client saw before profiles existed.",
);
}
PROFILES.iter().find(|(n, _, _)| *n == name).map(|(_, d, _)| *d)
}
/// The tools a profile exposes: `SPINE` plus its own, deduplicated and sorted.
///
/// `None` for an unknown name, and the distinction matters: a typo must be an
/// error at startup and must NOT fall back to exposing everything, which is the
/// one wrong answer a misspelled `--tool-profile` could give.
pub fn expand_profile(name: &str) -> Option<Vec<&'static str>> {
if name == FULL {
return None;
}
let (_, _, own) = PROFILES.iter().find(|(n, _, _)| *n == name)?;
let mut out: Vec<&'static str> = SPINE.iter().copied().chain(own.iter().copied()).collect();
out.sort_unstable();
out.dedup();
Some(out)
}
/// Whether `name` names a profile, `full` included.
pub fn is_profile(name: &str) -> bool {
name == FULL || PROFILES.iter().any(|(n, _, _)| *n == name)
}
// ───────────────────────────────────────────────────────────────────────────
// Tools this build cannot serve
// ───────────────────────────────────────────────────────────────────────────
/// The tools whose implementation is behind a Cargo feature, with the feature
/// each one needs.
///
/// Eight of the registered tools have a body that is `#[cfg(not(feature =
/// ...))] { return "Compiled without X feature" }`. Advertising one of those
/// over `tools/list` is a promise the build cannot keep: a client reads the
/// description, calls the tool, and gets an error that has nothing to do with
/// its input. That is the same defect as a verdict claimed but not earned, one
/// layer up — the advertisement and the capability have to agree, and the only
/// honest way to make them agree is to stop advertising what cannot be served.
///
/// `onto_import_schema` and `onto_sql_ingest` need EITHER `postgres` or
/// `duckdb`: they dispatch on the connection URL and the two schemes they
/// accept are the two features. A build with one of them keeps both tools,
/// because one scheme still works and the other reports a clear error about
/// the scheme rather than about the tool.
pub const FEATURE_GATED_TOOLS: &[(&str, &str)] = &[
("onto_plugin_list", "plugins"),
("onto_plugin_call", "plugins"),
("onto_embed", "embeddings"),
("onto_hnsw_build", "embeddings"),
("onto_search", "embeddings"),
("onto_similarity", "embeddings"),
("onto_import_schema", "postgres or duckdb"),
("onto_sql_ingest", "postgres or duckdb"),
];
/// Of those, the ones THIS build cannot serve. Empty when every feature is on.
pub fn unavailable_in_this_build() -> Vec<&'static str> {
let mut out: Vec<&'static str> = Vec::new();
if !cfg!(feature = "plugins") {
out.extend(["onto_plugin_list", "onto_plugin_call"]);
}
if !cfg!(feature = "embeddings") {
out.extend(["onto_embed", "onto_hnsw_build", "onto_search", "onto_similarity"]);
}
if !cfg!(feature = "postgres") && !cfg!(feature = "duckdb") {
out.extend(["onto_import_schema", "onto_sql_ingest"]);
}
out.sort_unstable();
out
}
/// Remove every tool this build cannot serve from `router`, returning what was
/// removed with the feature that would bring each one back.
///
/// Called before the operator's own filter and independently of its mode, so a
/// `Mode::All` server still does not advertise a tool guaranteed to fail.
pub fn remove_unavailable<S>(router: &mut ToolRouter<S>) -> Vec<(&'static str, &'static str)>
where
S: Send + Sync + 'static,
{
let gone = unavailable_in_this_build();
let mut removed = Vec::new();
for (name, feature) in FEATURE_GATED_TOOLS {
if gone.contains(name) {
router.remove_route(name);
removed.push((*name, *feature));
}
}
removed
}
/// Curated tool groups. Tool names must match the ones registered with
/// `#[tool(name = "...")]` in `src/server.rs`.
pub fn expand_group(name: &str) -> &'static [&'static str] {
match name {
// Read-only inspection tools (safe to expose to untrusted callers).
"read_only" | "read" => &[
"onto_status",
"onto_validate",
"onto_query",
"onto_stats",
"onto_diff",
"onto_lint",
"onto_history",
"onto_lineage",
"onto_cache_status",
"onto_cache_list",
"onto_repo_list",
"onto_dl_check",
"onto_dl_explain",
"onto_search",
"onto_similarity",
],
// Tools that mutate the in-memory store but not external systems.
"mutating" | "write" => &[
"onto_load",
"onto_clear",
"onto_save",
"onto_convert",
"onto_pull",
"onto_import",
"onto_marketplace",
"onto_version",
"onto_rollback",
"onto_ingest",
"onto_induce",
"onto_sql_ingest",
"onto_map",
"onto_shacl",
"onto_vocab_check",
"onto_reason",
"onto_extend",
"onto_unload",
"onto_recompile",
"onto_cache_remove",
"onto_repo_load",
],
// Tools that change governance / lifecycle state.
"governance" => &[
"onto_plan",
"onto_apply",
"onto_lock",
"onto_drift",
"onto_enforce",
"onto_monitor",
"onto_monitor_clear",
"onto_align",
"onto_align_feedback",
"onto_lint_feedback",
"onto_enforce_feedback",
],
// Tools that talk to external systems.
"remote" => &[
"onto_pull",
"onto_push",
"onto_marketplace",
"onto_import",
],
// Embedding / semantic search tools.
"embeddings" => &[
"onto_embed",
"onto_search",
"onto_similarity",
],
// SQL data backbone tools (PostgreSQL / DuckDB).
"sql" => &[
"onto_import_schema",
"onto_sql_ingest",
],
_ => &[],
}
}
/// Parse a comma-separated list of tool/group identifiers into (names, groups).
/// Identifiers prefixed with `@` are treated as group names.
pub fn parse_csv(spec: &str) -> (Vec<String>, Vec<String>) {
let mut names = Vec::new();
let mut groups = Vec::new();
for raw in spec.split(',') {
let item = raw.trim();
if item.is_empty() {
continue;
}
if let Some(g) = item.strip_prefix('@') {
groups.push(g.to_string());
} else {
names.push(item.to_string());
}
}
(names, groups)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn mode_parse() {
assert_eq!(Mode::parse("all").unwrap(), Mode::All);
assert_eq!(Mode::parse("ALLOW").unwrap(), Mode::Allow);
assert_eq!(Mode::parse("deny").unwrap(), Mode::Deny);
assert!(Mode::parse("nope").is_err());
}
#[test]
fn allow_filter_only_lets_listed_tools_through() {
let f = ToolFilter::allow_only(vec!["onto_status".to_string(), "onto_query".to_string()]);
assert!(f.allows("onto_status"));
assert!(f.allows("onto_query"));
assert!(!f.allows("onto_load"));
}
#[test]
fn deny_filter_blocks_listed_tools() {
let f = ToolFilter::deny(vec!["onto_clear".to_string()]);
assert!(f.allows("onto_status"));
assert!(!f.allows("onto_clear"));
}
#[test]
fn group_expansion() {
let f = ToolFilter {
mode: Mode::Allow,
list: vec![],
groups: vec!["read_only".to_string()],
profile: None,
};
assert!(f.allows("onto_status"));
assert!(f.allows("onto_query"));
assert!(!f.allows("onto_load"));
}
#[test]
fn csv_parser_splits_names_and_groups() {
let (n, g) = parse_csv("onto_status, onto_query, @read_only, ");
assert_eq!(n, vec!["onto_status", "onto_query"]);
assert_eq!(g, vec!["read_only"]);
}
#[test]
fn unknown_group_expands_to_empty() {
assert!(expand_group("does-not-exist").is_empty());
}
}