modelcontextprotocol 0.2.3

Filesystem, Fetch, Memory, Shell, Skills, and Agents MCP servers in a single binary, implementing the Model Context Protocol 2026-07-28 specification.
use std::{
    collections::{BTreeMap, HashSet},
    fs,
    path::{Path, PathBuf},
};

use super::parser::{ParsedSkill, parse_skill_file};

const ROOTS: [&str; 3] = [".agents/skills", ".claude/skills", ".opencode/skills"];

#[derive(Debug, Clone)]
pub(crate) struct Skill {
    pub(crate) skill_dir: PathBuf,
    pub(crate) skill_file: PathBuf,
    pub(crate) description: String,
}

#[derive(Debug, Default)]
pub(crate) struct SkillRegistry {
    skills: BTreeMap<String, Skill>,
}

impl SkillRegistry {
    pub(crate) fn discover(workspace: impl AsRef<Path>) -> anyhow::Result<Self> {
        let workspace = fs::canonicalize(workspace)?;
        if !workspace.is_dir() {
            anyhow::bail!("workspace is not a directory")
        }
        let mut candidates = Vec::new();
        for (precedence, root) in ROOTS.into_iter().enumerate() {
            let root = workspace.join(root);
            let Ok(entries) = fs::read_dir(&root) else {
                continue;
            };
            let dirs = entries
                .filter_map(Result::ok)
                .filter_map(|entry| fs::canonicalize(entry.path()).ok())
                .collect::<Vec<_>>();
            for dir in dirs {
                if !dir.starts_with(&workspace) || !dir.is_dir() {
                    continue;
                }
                let file = dir.join("SKILL.md");
                let Ok(canonical_file) = fs::canonicalize(&file) else {
                    continue;
                };
                if !canonical_file.starts_with(&dir) || !canonical_file.is_file() {
                    continue;
                }
                match parse_skill_file(&canonical_file) {
                    Ok(parsed) => candidates.push((precedence, dir, canonical_file, parsed)),
                    Err(error) => {
                        tracing::warn!(path = %file.display(), %error, "ignoring malformed skill")
                    }
                }
            }
        }
        candidates.sort_by(|a, b| a.0.cmp(&b.0).then_with(|| a.1.cmp(&b.1)));
        let mut skills = BTreeMap::new();
        let mut identities = HashSet::new();
        for (
            _,
            skill_dir,
            skill_file,
            ParsedSkill {
                name, description, ..
            },
        ) in candidates
        {
            if !identities.insert(skill_dir.clone()) {
                continue;
            }
            if skills.contains_key(&name) {
                tracing::warn!(skill = %name, path = %skill_dir.display(), "ignoring skill with colliding name");
                continue;
            }
            skills.insert(
                name,
                Skill {
                    skill_dir,
                    skill_file,
                    description,
                },
            );
        }
        Ok(Self { skills })
    }

    pub(crate) fn names(&self) -> impl Iterator<Item = &str> {
        self.skills.keys().map(String::as_str)
    }
    pub(crate) fn descriptions(&self) -> impl Iterator<Item = (&str, &str)> {
        self.skills
            .iter()
            .map(|(n, s)| (n.as_str(), s.description.as_str()))
    }
    pub(crate) fn catalog(&self) -> String {
        self.descriptions()
            .map(|(n, d)| format!("- {n}: {d}"))
            .collect::<Vec<_>>()
            .join("\n")
    }
    pub(crate) fn get(&self, name: &str) -> Option<&Skill> {
        self.skills.get(name)
    }
    pub(crate) fn load(&self, name: &str) -> anyhow::Result<ParsedSkill> {
        let skill = self
            .skills
            .get(name)
            .ok_or_else(|| anyhow::anyhow!("unknown skill: {name}"))?;
        let file = fs::canonicalize(&skill.skill_file)?;
        if !file.starts_with(&skill.skill_dir) || file != skill.skill_file {
            anyhow::bail!("registered SKILL.md changed location")
        }
        let parsed = parse_skill_file(&file)?;
        if parsed.name != name {
            anyhow::bail!("registered SKILL.md name changed")
        }
        Ok(parsed)
    }
    pub(crate) fn is_empty(&self) -> bool {
        self.skills.is_empty()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use tempfile::tempdir;
    fn write(root: &Path, source: &str, dir: &str, name: &str) {
        let path = root.join(source).join(dir);
        fs::create_dir_all(&path).unwrap();
        fs::write(
            path.join("SKILL.md"),
            format!("---\nname: {name}\ndescription: {source}\n---\nbody"),
        )
        .unwrap();
    }
    #[test]
    fn precedence_and_catalog_are_deterministic() {
        let temp = tempdir().unwrap();
        write(temp.path(), ".opencode/skills", "z", "same");
        write(temp.path(), ".agents/skills", "a", "same");
        write(temp.path(), ".claude/skills", "b", "other");
        let registry = SkillRegistry::discover(temp.path()).unwrap();
        assert_eq!(
            registry.catalog(),
            "- other: .claude/skills\n- same: .agents/skills"
        );
    }

    #[test]
    fn discovers_all_three_roots() {
        let temp = tempdir().unwrap();
        write(temp.path(), ".agents/skills", "agent", "agent");
        write(temp.path(), ".claude/skills", "claude", "claude");
        write(temp.path(), ".opencode/skills", "open", "open");
        assert_eq!(
            SkillRegistry::discover(temp.path())
                .unwrap()
                .names()
                .collect::<Vec<_>>(),
            ["agent", "claude", "open"]
        );
    }
    #[test]
    fn malformed_candidate_does_not_block_valid_one() {
        let temp = tempdir().unwrap();
        write(temp.path(), ".agents/skills", "good", "good");
        let bad = temp.path().join(".claude/skills/bad");
        fs::create_dir_all(&bad).unwrap();
        fs::write(bad.join("SKILL.md"), "bad").unwrap();
        assert_eq!(
            SkillRegistry::discover(temp.path())
                .unwrap()
                .names()
                .collect::<Vec<_>>(),
            ["good"]
        );
    }

    #[test]
    fn lexical_path_breaks_same_root_name_ties() {
        let temp = tempdir().unwrap();
        write(temp.path(), ".agents/skills", "z", "same");
        write(temp.path(), ".agents/skills", "a", "same");
        assert_eq!(
            SkillRegistry::discover(temp.path())
                .unwrap()
                .get("same")
                .unwrap()
                .description,
            ".agents/skills"
        );
        assert!(
            SkillRegistry::discover(temp.path())
                .unwrap()
                .get("same")
                .unwrap()
                .skill_dir
                .ends_with("a")
        );
    }

    #[cfg(unix)]
    #[test]
    fn canonical_identity_is_deduplicated_before_name_deduplication() {
        use std::os::unix::fs::symlink;
        let temp = tempdir().unwrap();
        write(temp.path(), ".agents/skills", "real", "real");
        let root = temp.path().join(".agents/skills");
        symlink(root.join("real"), root.join("alias")).unwrap();
        let registry = SkillRegistry::discover(temp.path()).unwrap();
        assert_eq!(registry.names().collect::<Vec<_>>(), ["real"]);
        assert!(registry.get("real").unwrap().skill_dir.ends_with("real"));
    }
}