chub_cli/mcp/

tools.rs

use std::sync::Arc;

use chub_core::annotations::{
    clear_annotation, list_annotations, write_annotation, AnnotationKind,
};
use chub_core::fetch::{fetch_doc, fetch_doc_full, verify_content_hash};
use chub_core::registry::{
    get_entry, list_entries, resolve_doc_path, resolve_entry_file, search_entries, MergedRegistry,
    ResolvedPath, SearchFilters, TaggedEntry,
};
use chub_core::team;
use chub_core::telemetry::{is_feedback_enabled, send_feedback, FeedbackOpts, VALID_LABELS};

use rmcp::handler::server::router::tool::ToolRouter;
use rmcp::handler::server::wrapper::Parameters;
use rmcp::{schemars, tool, tool_router};

fn text_result(data: impl serde::Serialize) -> String {
    serde_json::to_string_pretty(&data).unwrap_or_else(|_| "{}".to_string())
}

fn simplify_entry(entry: &TaggedEntry) -> serde_json::Value {
    let mut val = serde_json::json!({
        "id": entry.id(),
        "name": entry.name(),
        "type": entry.entry_type,
        "description": entry.description(),
        "tags": entry.tags(),
    });
    if let Some(languages) = entry.languages() {
        val["languages"] =
            serde_json::json!(languages.iter().map(|l| &l.language).collect::<Vec<_>>());
    }
    val
}

// --- Tool parameter structs ---

#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
pub struct SearchParams {
    /// Search query. Omit to list all entries.
    #[schemars(default)]
    pub query: Option<String>,
    /// Comma-separated tag filter (e.g. "openai,chat")
    #[schemars(default)]
    pub tags: Option<String>,
    /// Filter by language (e.g. "python", "js")
    #[schemars(default)]
    pub lang: Option<String>,
    /// Max results (default 20)
    #[schemars(default)]
    pub limit: Option<usize>,
}

#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
pub struct GetParams {
    /// Entry ID (e.g. "openai/chat", "stripe/api"). Use source:id for disambiguation.
    pub id: String,
    /// Language variant (e.g. "python", "js"). Auto-selected if only one.
    #[schemars(default)]
    pub lang: Option<String>,
    /// Specific version (e.g. "1.52.0"). Defaults to recommended.
    #[schemars(default)]
    pub version: Option<String>,
    /// Fetch all files, not just the entry point (default false)
    #[schemars(default)]
    pub full: Option<bool>,
    /// Fetch a specific file by path (e.g. "references/streaming.md")
    #[schemars(default)]
    pub file: Option<String>,
    /// Auto-detect version from project dependencies (default false)
    #[schemars(default)]
    pub match_env: Option<bool>,
}

#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
pub struct ListParams {
    /// Comma-separated tag filter
    #[schemars(default)]
    pub tags: Option<String>,
    /// Filter by language
    #[schemars(default)]
    pub lang: Option<String>,
    /// Max entries (default 50)
    #[schemars(default)]
    pub limit: Option<usize>,
}

#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
pub struct AnnotateParams {
    /// Entry ID to annotate (e.g. "openai/chat"). Required unless using list mode.
    #[schemars(default)]
    pub id: Option<String>,
    /// Annotation text to save. Omit to read existing annotation.
    #[schemars(default)]
    pub note: Option<String>,
    /// Annotation kind: "note" (default), "issue" (bug/gotcha), "fix" (workaround), "practice" (team convention).
    /// Use "issue" when you discover an undocumented bug or broken param.
    /// Use "fix" when you find a workaround for an issue.
    /// Use "practice" when you validate a pattern the team should follow.
    #[schemars(default)]
    pub kind: Option<String>,
    /// Severity for issue annotations: "high", "medium", or "low". Only used when kind="issue".
    #[schemars(default)]
    pub severity: Option<String>,
    /// Remove the annotation for this entry (default false)
    #[schemars(default)]
    pub clear: Option<bool>,
    /// List all annotations (default false). When true, id is not needed.
    #[schemars(default)]
    pub list: Option<bool>,
    /// Scope: "auto" (default), "personal", "team", or "org".
    /// auto = team when .chub/ exists, personal otherwise (org requires explicit scope).
    #[schemars(default)]
    pub scope: Option<String>,
}

#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
pub struct FeedbackParams {
    /// Entry ID to rate (e.g. "openai/chat")
    pub id: String,
    /// Thumbs up or down
    pub rating: String,
    /// Optional comment explaining the rating
    #[schemars(default)]
    pub comment: Option<String>,
    /// Entry type. Auto-detected if omitted.
    #[serde(rename = "type")]
    #[schemars(default)]
    pub entry_type: Option<String>,
    /// Language variant rated
    #[schemars(default)]
    pub lang: Option<String>,
    /// Version rated
    #[schemars(default)]
    pub version: Option<String>,
    /// Specific file rated
    #[schemars(default)]
    pub file: Option<String>,
    /// Structured feedback labels
    #[schemars(default)]
    pub labels: Option<Vec<String>>,
}

#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
#[allow(dead_code)] // Fields exposed via MCP JSON schema, read by serde
pub struct ContextParams {
    /// Task description to find relevant context for
    #[schemars(default)]
    pub task: Option<String>,
    /// Files currently open (for auto-profile detection)
    #[schemars(default)]
    pub files_open: Option<Vec<String>>,
    /// Profile name to scope context to
    #[schemars(default)]
    pub profile: Option<String>,
    /// Maximum token budget (soft limit)
    #[schemars(default)]
    pub max_tokens: Option<usize>,
}

#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
pub struct PinsParams {
    /// Entry ID to pin or unpin
    #[schemars(default)]
    pub id: Option<String>,
    /// Language variant
    #[schemars(default)]
    pub lang: Option<String>,
    /// Version to lock
    #[schemars(default)]
    pub version: Option<String>,
    /// Reason for pinning
    #[schemars(default)]
    pub reason: Option<String>,
    /// Remove the pin (default false)
    #[schemars(default)]
    pub remove: Option<bool>,
    /// List all pins (default false)
    #[schemars(default)]
    pub list: Option<bool>,
}

#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
pub struct TrackParams {
    /// Action: "status", "report", "log", "show"
    pub action: String,
    /// Session ID (for "show" action)
    #[schemars(default)]
    pub session_id: Option<String>,
    /// Number of days for report/log (default 30)
    #[schemars(default)]
    pub days: Option<u64>,
}

// --- MCP Server ---

#[derive(Debug, Clone)]
pub struct ChubMcpServer {
    pub merged: Arc<MergedRegistry>,
    pub tool_router: ToolRouter<Self>,
}

impl ChubMcpServer {
    pub fn new(merged: Arc<MergedRegistry>) -> Self {
        Self {
            merged,
            tool_router: Self::tool_router(),
        }
    }
}

#[tool_router]
impl ChubMcpServer {
    #[tool(
        name = "chub_search",
        description = "Search Context Hub for docs and skills by query, tags, or language"
    )]
    async fn handle_search(&self, Parameters(params): Parameters<SearchParams>) -> String {
        let limit = params.limit.unwrap_or(20);
        let filters = SearchFilters {
            tags: params.tags,
            lang: params.lang,
            entry_type: None,
        };

        let t0 = std::time::Instant::now();
        let entries = if let Some(ref query) = params.query {
            search_entries(query, &filters, &self.merged)
        } else {
            list_entries(&filters, &self.merged)
        };
        let elapsed = t0.elapsed().as_millis() as u64;

        if let Some(ref query) = params.query {
            team::analytics::record_search(query, entries.len(), Some(elapsed), Some("mcp-server"));
        }
        team::analytics::record_mcp_call("chub_search", Some(elapsed), Some("mcp-server"));

        let sliced: Vec<_> = entries.iter().take(limit).collect();
        text_result(serde_json::json!({
            "results": sliced.iter().map(|e| simplify_entry(e)).collect::<Vec<_>>(),
            "total": entries.len(),
            "showing": sliced.len(),
        }))
    }

    #[tool(
        name = "chub_get",
        description = "Fetch the content of a doc or skill by ID from Context Hub"
    )]
    async fn handle_get(&self, Parameters(params): Parameters<GetParams>) -> String {
        // Validate file parameter (path traversal) — reject suspicious paths
        if let Some(ref file) = params.file {
            if file.contains("..") || file.contains('\\') {
                return text_result(serde_json::json!({
                    "error": format!("Invalid file path: \"{}\". Path traversal is not allowed.", file),
                }));
            }
            let normalized = std::path::Path::new("/")
                .join(file)
                .to_string_lossy()
                .to_string();
            let normalized = normalized.trim_start_matches('/').to_string();
            if normalized != *file {
                return text_result(serde_json::json!({
                    "error": format!("Invalid file path: \"{}\". Path traversal is not allowed.", file),
                }));
            }
        }

        let result = get_entry(&params.id, &self.merged);

        if result.ambiguous {
            return text_result(serde_json::json!({
                "error": format!("Ambiguous entry ID \"{}\". Be specific:", params.id),
                "alternatives": result.alternatives,
            }));
        }

        let entry = match result.entry {
            Some(e) => e,
            None => {
                return text_result(serde_json::json!({
                    "error": format!("Entry \"{}\" not found.", params.id),
                    "suggestion": "Use chub_search to find available entries.",
                }));
            }
        };

        let entry_type = entry.entry_type;

        // Apply pin overrides: if the entry is pinned, use pinned lang/version as defaults
        let mut effective_lang = params.lang.clone();
        let mut effective_version = params.version.clone();
        let mut pin_notice = String::new();
        if let Some(pin) = team::pins::get_pin(entry.id()) {
            if effective_lang.is_none() {
                effective_lang = pin.lang.clone();
            }
            if effective_version.is_none() {
                effective_version = pin.version.clone();
            }
            pin_notice = team::team_annotations::get_pin_notice(
                pin.version.as_deref(),
                pin.lang.as_deref(),
                pin.reason.as_deref(),
            );
        }

        // Auto-detect version from project dependencies if match_env is set
        if params.match_env.unwrap_or(false) && effective_version.is_none() {
            let cwd = std::env::current_dir().unwrap_or_default();
            let deps = chub_core::team::detect::detect_dependencies(&cwd);
            if let Some(dep) = find_matching_dep_for_entry(entry.id(), &deps) {
                if let Some(ref ver) = dep.version {
                    let clean = ver.trim_start_matches(|c: char| {
                        c == '^' || c == '~' || c == '=' || c == '>' || c == '<' || c == 'v'
                    });
                    if !clean.is_empty() {
                        effective_version = Some(clean.to_string());
                    }
                }
            }
        }

        let resolved = resolve_doc_path(
            &entry,
            effective_lang.as_deref(),
            effective_version.as_deref(),
        );

        let resolved = match resolved {
            Some(r) => r,
            None => {
                return text_result(serde_json::json!({
                    "error": format!("Could not resolve path for \"{}\".", params.id),
                }));
            }
        };

        match &resolved {
            ResolvedPath::VersionNotFound {
                requested,
                available,
            } => {
                return text_result(serde_json::json!({
                    "error": format!("Version \"{}\" not found for \"{}\".", requested, params.id),
                    "available": available,
                }));
            }
            ResolvedPath::NeedsLanguage { available } => {
                return text_result(serde_json::json!({
                    "error": format!("Multiple languages available for \"{}\". Specify the lang parameter.", params.id),
                    "available": available,
                }));
            }
            ResolvedPath::Ok { .. } => {}
        }

        let (file_path, base_path, files) = match resolve_entry_file(&resolved, entry_type) {
            Some(r) => r,
            None => {
                return text_result(serde_json::json!({
                    "error": format!("\"{}\": unresolved", params.id),
                }));
            }
        };

        let (source, content_hash) = match &resolved {
            ResolvedPath::Ok {
                source,
                content_hash,
                ..
            } => (source.clone(), content_hash.clone()),
            _ => unreachable!(),
        };

        let mut content = if let Some(ref file) = params.file {
            if !files.contains(&file.to_string()) {
                let entry_file_name = if entry_type == "skill" {
                    "SKILL.md"
                } else {
                    "DOC.md"
                };
                let available: Vec<_> = files
                    .iter()
                    .filter(|f| f.as_str() != entry_file_name)
                    .collect();
                return text_result(serde_json::json!({
                    "error": format!("File \"{}\" not found in {}.", file, params.id),
                    "available": if available.is_empty() { vec!["(none)".to_string()] } else { available.iter().map(|s| s.to_string()).collect() },
                }));
            }
            let path = format!("{}/{}", base_path, file);
            match fetch_doc(&source, &path).await {
                Ok(c) => c,
                Err(e) => {
                    return text_result(serde_json::json!({
                        "error": format!("Failed to fetch \"{}\": {}", params.id, e),
                    }));
                }
            }
        } else if params.full.unwrap_or(false) && !files.is_empty() {
            match fetch_doc_full(&source, &base_path, &files).await {
                Ok(all_files) => all_files
                    .iter()
                    .map(|(name, content)| format!("# FILE: {}\n\n{}", name, content))
                    .collect::<Vec<_>>()
                    .join("\n\n---\n\n"),
                Err(e) => {
                    return text_result(serde_json::json!({
                        "error": format!("Failed to fetch \"{}\": {}", params.id, e),
                    }));
                }
            }
        } else {
            match fetch_doc(&source, &file_path).await {
                Ok(c) => {
                    // Verify content integrity if hash is available
                    if let Err(e) = verify_content_hash(&c, content_hash.as_deref(), &file_path) {
                        return text_result(serde_json::json!({
                            "error": format!("{}", e),
                            "warning": "Content may have been tampered with.",
                        }));
                    }
                    c
                }
                Err(e) => {
                    return text_result(serde_json::json!({
                        "error": format!("Failed to fetch \"{}\": {}", params.id, e),
                    }));
                }
            }
        };

        // Append pin notice if this doc is pinned
        if !pin_notice.is_empty() {
            content.push_str(&pin_notice);
        }

        // Append merged annotations (org + team + personal) with trust framing
        if let Some(merged_ann) =
            team::team_annotations::get_merged_annotation_async(entry.id()).await
        {
            content.push_str(&format!(
                "\n\n---\n⚠ USER-CONTRIBUTED ANNOTATIONS (not part of official documentation):\n{}\n",
                merged_ann
            ));
        }

        // Record analytics
        team::analytics::record_fetch(entry.id(), Some("mcp-server"));
        team::analytics::record_mcp_call("chub_get", None, Some("mcp-server"));

        content
    }

    #[tool(
        name = "chub_list",
        description = "List all available docs and skills in Context Hub"
    )]
    async fn handle_list(&self, Parameters(params): Parameters<ListParams>) -> String {
        let limit = params.limit.unwrap_or(50);
        let filters = SearchFilters {
            tags: params.tags,
            lang: params.lang,
            entry_type: None,
        };

        let entries = list_entries(&filters, &self.merged);
        let sliced: Vec<_> = entries.iter().take(limit).collect();

        team::analytics::record_mcp_call("chub_list", None, Some("mcp-server"));

        text_result(serde_json::json!({
            "entries": sliced.iter().map(|e| simplify_entry(e)).collect::<Vec<_>>(),
            "total": entries.len(),
            "showing": sliced.len(),
        }))
    }

    #[tool(
        name = "chub_annotate",
        description = "Read, write, clear, or list agent annotations for a doc entry. \
        USE THIS TOOL proactively after resolving something non-obvious with a library: \
        (1) Discovered an undocumented bug or broken param? Write kind=issue. \
        (2) Found a workaround? Write kind=fix. \
        (3) Validated a useful pattern? Write kind=practice. \
        Always read existing annotations first (id alone) to avoid duplicates. \
        Be concise and reproducible — include the exact call, param, or value. \
        Scope: auto (default), personal, team, or org (requires annotation_server config). \
        Modes: (a) list=true to list all, (b) id+note+kind to write, (c) id+clear=true to delete, (d) id alone to read."
    )]
    async fn handle_annotate(&self, Parameters(params): Parameters<AnnotateParams>) -> String {
        if params.list.unwrap_or(false) {
            let scope = params.scope.as_deref().unwrap_or("auto");
            if scope == "org" {
                let annotations = chub_core::team::org_annotations::list_org_annotations().await;
                let total = annotations.len();
                return text_result(serde_json::json!({
                    "annotations": annotations,
                    "scope": "org",
                    "total": total,
                }));
            } else if chub_core::team::project::project_chub_dir().is_some() {
                let annotations = chub_core::team::team_annotations::list_team_annotations();
                return text_result(serde_json::json!({
                    "annotations": annotations,
                    "scope": "team",
                    "total": annotations.len(),
                }));
            }
            let annotations = list_annotations();
            return text_result(serde_json::json!({
                "annotations": annotations,
                "scope": "personal",
                "total": annotations.len(),
            }));
        }

        let id = match params.id {
            Some(id) => id,
            None => {
                return text_result(serde_json::json!({
                    "error": "Missing required parameter: id. Provide an entry ID or use list mode.",
                }));
            }
        };

        // Validate entry ID
        if id.len() > 200 {
            return text_result(serde_json::json!({
                "error": "Entry ID too long (max 200 characters).",
            }));
        }
        if !id
            .chars()
            .all(|c| c.is_alphanumeric() || c == '.' || c == '-' || c == '_' || c == '/')
        {
            return text_result(serde_json::json!({
                "error": "Entry ID contains invalid characters. Use only alphanumeric, hyphens, underscores, dots, and slashes.",
            }));
        }

        if params.clear.unwrap_or(false) {
            let scope = params.scope.as_deref().unwrap_or("auto");
            let (scope_label, removed) = if scope == "org" {
                match chub_core::team::org_annotations::clear_org_annotation(&id).await {
                    Ok(r) => ("org", r),
                    Err(e) => {
                        return text_result(serde_json::json!({"error": e, "id": id}));
                    }
                }
            } else if scope == "personal" {
                ("personal", clear_annotation(&id))
            } else {
                // "auto" or "team"
                if chub_core::team::project::project_chub_dir().is_some() {
                    (
                        "team",
                        chub_core::team::team_annotations::clear_team_annotation(&id),
                    )
                } else {
                    ("personal", clear_annotation(&id))
                }
            };
            return text_result(serde_json::json!({
                "status": if removed { "cleared" } else { "not_found" },
                "scope": scope_label,
                "id": id,
            }));
        }

        if let Some(note) = params.note {
            let kind = params
                .kind
                .as_deref()
                .and_then(AnnotationKind::parse)
                .unwrap_or(AnnotationKind::Note);

            let scope = params.scope.as_deref().unwrap_or("auto");

            if scope == "org" {
                let author = get_agent_author();
                return match chub_core::team::org_annotations::write_org_annotation(
                    &id,
                    &note,
                    &author,
                    kind.clone(),
                    params.severity.clone(),
                )
                .await
                {
                    Ok(saved) => text_result(serde_json::json!({
                        "status": "saved",
                        "scope": "org",
                        "kind": kind.as_str(),
                        "annotation": saved,
                    })),
                    Err(e) => text_result(serde_json::json!({"error": e, "id": id})),
                };
            }

            if scope == "personal" {
                let saved = write_annotation(&id, &note, kind.clone(), params.severity.clone());
                team::analytics::record_annotate(&id, kind.as_str());
                team::analytics::record_mcp_call("chub_annotate", None, Some("mcp-server"));
                return text_result(serde_json::json!({
                    "status": "saved",
                    "scope": "personal",
                    "kind": kind.as_str(),
                    "annotation": saved,
                }));
            }

            // "auto" or "team": when a project .chub/ dir is present, write to team tier.
            if chub_core::team::project::project_chub_dir().is_some() {
                let author = get_agent_author();
                let result = match chub_core::team::team_annotations::write_team_annotation(
                    &id,
                    &note,
                    &author,
                    kind.clone(),
                    params.severity.clone(),
                ) {
                    Some(saved) => {
                        team::analytics::record_annotate(&id, kind.as_str());
                        team::analytics::record_mcp_call("chub_annotate", None, Some("mcp-server"));
                        // auto_push if configured
                        let auto_push =
                            chub_core::team::org_annotations::get_annotation_server_config()
                                .map(|c| c.auto_push)
                                .unwrap_or(false);
                        if auto_push {
                            let _ = chub_core::team::org_annotations::write_org_annotation(
                                &id,
                                &note,
                                &author,
                                kind.clone(),
                                params.severity.clone(),
                            )
                            .await;
                        }
                        text_result(serde_json::json!({
                            "status": "saved",
                            "scope": "team",
                            "kind": kind.as_str(),
                            "annotation": saved,
                        }))
                    }
                    None => text_result(serde_json::json!({
                        "error": "Failed to write team annotation. Check that .chub/annotations/ is writable.",
                        "id": id,
                    })),
                };
                return result;
            }

            // No project dir: write personal annotation (overwrite semantics).
            let saved = write_annotation(&id, &note, kind.clone(), params.severity.clone());
            return text_result(serde_json::json!({
                "status": "saved",
                "scope": "personal",
                "kind": kind.as_str(),
                "annotation": saved,
            }));
        }

        // Read mode: return merged all-tier annotation if available.
        if let Some(merged) = team::team_annotations::get_merged_annotation_async(&id).await {
            return text_result(serde_json::json!({ "annotation": merged }));
        }
        text_result(serde_json::json!({ "status": "no_annotation", "id": id }))
    }

    #[tool(
        name = "chub_context",
        description = "Get optimal context for a task: returns relevant pinned docs, team annotations, project context, and profile rules in one call"
    )]
    async fn handle_context(&self, Parameters(params): Parameters<ContextParams>) -> String {
        let mut result = serde_json::json!({});

        // Pinned docs
        let pins = team::pins::list_pins();
        if !pins.is_empty() {
            result["pins"] = serde_json::json!(pins);
        }

        // Active profile rules
        if let Some(ref profile_name) = params.profile {
            if let Ok(resolved) = team::profiles::resolve_profile(profile_name) {
                result["profile"] = serde_json::json!({
                    "name": resolved.name,
                    "rules": resolved.rules,
                    "context": resolved.context,
                });
            }
        } else if let Some(profile_name) = team::profiles::get_active_profile() {
            if let Ok(resolved) = team::profiles::resolve_profile(&profile_name) {
                result["profile"] = serde_json::json!({
                    "name": resolved.name,
                    "rules": resolved.rules,
                    "context": resolved.context,
                });
            }
        }

        // Project context docs
        let context_docs = team::context::list_context_docs();
        if !context_docs.is_empty() {
            result["project_context"] = serde_json::json!(context_docs);
        }

        // Team annotations for pinned docs
        let mut annotations = Vec::new();
        for pin in &pins {
            if let Some(merged_ann) = team::team_annotations::get_merged_annotation(&pin.id) {
                annotations.push(serde_json::json!({
                    "id": pin.id,
                    "annotation": merged_ann,
                }));
            }
        }
        if !annotations.is_empty() {
            result["annotations"] = serde_json::json!(annotations);
        }

        // Task relevance scoring (if task provided)
        if let Some(ref task) = params.task {
            result["task"] = serde_json::json!(task);
        }

        text_result(result)
    }

    #[tool(
        name = "chub_pins",
        description = "List, add, or remove pinned docs. Pinned docs have locked versions for the team."
    )]
    async fn handle_pins(&self, Parameters(params): Parameters<PinsParams>) -> String {
        if params.list.unwrap_or(false) || (params.id.is_none() && params.remove.is_none()) {
            let pins = team::pins::list_pins();
            return text_result(serde_json::json!({
                "pins": pins,
                "total": pins.len(),
            }));
        }

        let id = match params.id {
            Some(id) => id,
            None => {
                return text_result(serde_json::json!({
                    "error": "Missing required parameter: id",
                }));
            }
        };

        if params.remove.unwrap_or(false) {
            match team::pins::remove_pin(&id) {
                Ok(true) => text_result(serde_json::json!({"status": "unpinned", "id": id})),
                Ok(false) => text_result(serde_json::json!({"status": "not_found", "id": id})),
                Err(e) => text_result(serde_json::json!({"error": e.to_string()})),
            }
        } else {
            match team::pins::add_pin(&id, params.lang, params.version, params.reason, None) {
                Ok(()) => text_result(serde_json::json!({"status": "pinned", "id": id})),
                Err(e) => text_result(serde_json::json!({"error": e.to_string()})),
            }
        }
    }

    #[tool(
        name = "chub_feedback",
        description = "Send quality feedback (thumbs up/down) for a doc or skill to help authors improve content"
    )]
    async fn handle_feedback(&self, Parameters(params): Parameters<FeedbackParams>) -> String {
        if !is_feedback_enabled() {
            return text_result(serde_json::json!({
                "status": "skipped",
                "reason": "feedback_disabled",
            }));
        }

        // Auto-detect entry type
        let mut entry_type = params.entry_type.clone();
        if entry_type.is_none() {
            let result = get_entry(&params.id, &self.merged);
            if let Some(ref entry) = result.entry {
                entry_type = Some(entry.entry_type.to_string());
            }
        }
        let entry_type = entry_type.unwrap_or_else(|| "doc".to_string());

        // Validate labels
        let labels = params.labels.map(|ls| {
            ls.into_iter()
                .filter(|l| VALID_LABELS.contains(&l.as_str()))
                .collect::<Vec<_>>()
        });

        let result = send_feedback(
            &params.id,
            &entry_type,
            &params.rating,
            FeedbackOpts {
                comment: params.comment,
                doc_lang: params.lang,
                doc_version: params.version,
                target_file: params.file,
                labels,
                agent: Some("mcp-server".to_string()),
                model: None,
                cli_version: Some(env!("CARGO_PKG_VERSION").to_string()),
                source: None,
            },
        )
        .await;

        text_result(result)
    }

    #[tool(
        name = "chub_track",
        description = "Query AI usage tracking data — session status, cost reports, session history, and session details"
    )]
    async fn handle_track(&self, Parameters(params): Parameters<TrackParams>) -> String {
        team::analytics::record_mcp_call("chub_track", None, None);

        let days = params.days.unwrap_or(30);

        match params.action.as_str() {
            "status" => {
                let active = team::sessions::get_active_session();
                let journals = team::session_journal::list_journal_files();
                let entire_states = team::tracking::session_state::list_states();
                let active_state = active
                    .as_ref()
                    .and_then(|s| team::tracking::session_state::load_state(&s.session_id));
                text_result(serde_json::json!({
                    "active_session": active.as_ref().map(|s| serde_json::json!({
                        "session_id": s.session_id,
                        "agent": s.agent,
                        "model": s.model,
                        "started_at": s.started_at,
                        "turns": s.turns,
                        "tool_calls": s.tool_calls,
                        "tokens": {
                            "input": s.tokens.input,
                            "output": s.tokens.output,
                            "total": s.tokens.total(),
                        },
                        "phase": active_state.as_ref().map(|st| format!("{:?}", st.phase)),
                        "files_touched": active_state.as_ref().map(|st| st.files_touched.len()),
                        "transcript_linked": active_state.as_ref().map(|st| st.transcript_path.is_some()),
                    })),
                    "local_journals": journals.len(),
                    "entire_sessions": entire_states.len(),
                }))
            }
            "report" => {
                let report = team::sessions::generate_report(days);
                text_result(report)
            }
            "log" => {
                let sessions = team::sessions::list_sessions(days);
                let summaries: Vec<_> = sessions
                    .iter()
                    .map(|s| {
                        serde_json::json!({
                            "session_id": s.session_id,
                            "agent": s.agent,
                            "model": s.model,
                            "started_at": s.started_at,
                            "duration_s": s.duration_s,
                            "turns": s.turns,
                            "tokens_total": s.tokens.total(),
                            "tool_calls": s.tool_calls,
                            "est_cost_usd": s.est_cost_usd,
                        })
                    })
                    .collect();
                text_result(summaries)
            }
            "show" => {
                let session_id = match params.session_id {
                    Some(id) => id,
                    None => {
                        return text_result(serde_json::json!({
                            "error": "session_id is required for 'show' action"
                        }))
                    }
                };
                if let Some(session) = team::sessions::get_session(&session_id) {
                    text_result(session)
                } else {
                    text_result(serde_json::json!({
                        "error": format!("Session '{}' not found", session_id)
                    }))
                }
            }
            other => text_result(serde_json::json!({
                "error": format!("Unknown action: '{}'. Use: status, report, log, show", other)
            })),
        }
    }
}

fn get_agent_author() -> String {
    std::env::var("USER")
        .or_else(|_| std::env::var("USERNAME"))
        .unwrap_or_else(|_| "agent".to_string())
}

/// Find a matching dependency for a registry entry ID.
fn find_matching_dep_for_entry<'a>(
    entry_id: &str,
    deps: &'a [chub_core::team::detect::DetectedDep],
) -> Option<&'a chub_core::team::detect::DetectedDep> {
    let id_parts: Vec<&str> = entry_id.split('/').collect();
    let search_name = if !id_parts.is_empty() {
        id_parts[0].to_lowercase()
    } else {
        entry_id.to_lowercase()
    };
    deps.iter().find(|d| d.name.to_lowercase() == search_name)
}