sirchmunk 0.0.1.post1__py3-none-any.whl → 0.0.2__py3-none-any.whl

sirchmunk_mcp/tools.py

@@ -0,0 +1,410 @@
+# Copyright (c) ModelScope Contributors. All rights reserved.
+"""
+MCP Tools definitions for Sirchmunk.
+
+Defines the MCP tools that expose Sirchmunk functionality to MCP clients.
+"""
+
+import json
+import logging
+from typing import Any, Dict, List
+
+from mcp.types import Tool, TextContent
+
+from .service import SirchmunkService
+
+
+logger = logging.getLogger(__name__)
+
+
+# Tool definitions following MCP specification
+SIRCHMUNK_SEARCH_TOOL = Tool(
+    name="sirchmunk_search",
+    description=(
+        "Intelligent code and document search with multi-mode support. "
+        "DEEP mode provides comprehensive knowledge extraction with full context analysis. "
+        "FAST mode offers quick content search without deep LLM processing. "
+        "FILENAME_ONLY mode performs fast filename pattern matching without content search."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "Search query or question (e.g., 'How does authentication work?')",
+            },
+            "search_paths": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Paths to search in (files or directories)",
+            },
+            "mode": {
+                "type": "string",
+                "enum": ["DEEP", "FAST", "FILENAME_ONLY"],
+                "default": "DEEP",
+                "description": (
+                    "Search mode: DEEP (comprehensive analysis, 10-30s), "
+                    "FAST (quick search, 3-8s), FILENAME_ONLY (file discovery, <1s)"
+                ),
+            },
+            "max_depth": {
+                "type": "integer",
+                "default": 5,
+                "minimum": 1,
+                "maximum": 20,
+                "description": "Maximum directory depth to search",
+            },
+            "top_k_files": {
+                "type": "integer",
+                "default": 3,
+                "minimum": 1,
+                "maximum": 20,
+                "description": "Number of top files to return",
+            },
+            "keyword_levels": {
+                "type": "integer",
+                "default": 3,
+                "minimum": 1,
+                "maximum": 5,
+                "description": "Keyword granularity levels (DEEP mode only, more levels = more fallback options)",
+            },
+            "include": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "File patterns to include (glob, e.g., ['*.py', '*.md'])",
+            },
+            "exclude": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "File patterns to exclude (glob, e.g., ['*.pyc', '*.log'])",
+            },
+            "return_cluster": {
+                "type": "boolean",
+                "default": False,
+                "description": "Return full KnowledgeCluster object (DEEP/FAST modes only)",
+            },
+        },
+        "required": ["query", "search_paths"],
+    },
+)
+
+
+SIRCHMUNK_GET_CLUSTER_TOOL = Tool(
+    name="sirchmunk_get_cluster",
+    description=(
+        "Retrieve a previously saved knowledge cluster by its ID. "
+        "Knowledge clusters are automatically saved during DEEP mode searches "
+        "and contain rich information including evidences, patterns, and constraints."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "cluster_id": {
+                "type": "string",
+                "description": "Knowledge cluster ID (e.g., 'C1007')",
+            },
+        },
+        "required": ["cluster_id"],
+    },
+)
+
+
+SIRCHMUNK_LIST_CLUSTERS_TOOL = Tool(
+    name="sirchmunk_list_clusters",
+    description=(
+        "List all saved knowledge clusters with optional filtering and sorting. "
+        "Useful for discovering previously searched topics and reusing knowledge."
+    ),
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "limit": {
+                "type": "integer",
+                "default": 10,
+                "minimum": 1,
+                "maximum": 100,
+                "description": "Maximum number of clusters to return",
+            },
+            "sort_by": {
+                "type": "string",
+                "enum": ["hotness", "confidence", "last_modified"],
+                "default": "last_modified",
+                "description": (
+                    "Sort field: hotness (query frequency), "
+                    "confidence (quality score), last_modified (most recent)"
+                ),
+            },
+        },
+    },
+)
+
+
+# Tool registry
+TOOLS = [
+    SIRCHMUNK_SEARCH_TOOL,
+    SIRCHMUNK_GET_CLUSTER_TOOL,
+    SIRCHMUNK_LIST_CLUSTERS_TOOL,
+]
+
+
+async def handle_sirchmunk_search(
+    service: SirchmunkService,
+    arguments: Dict[str, Any],
+) -> List[TextContent]:
+    """Handle sirchmunk_search tool invocation.
+    
+    Args:
+        service: SirchmunkService instance
+        arguments: Tool arguments from MCP client
+    
+    Returns:
+        List of TextContent with search results
+    
+    Raises:
+        ValueError: If required arguments are missing or invalid
+    """
+    # Extract required arguments
+    query = arguments.get("query")
+    search_paths = arguments.get("search_paths")
+    
+    if not query:
+        raise ValueError("Missing required argument: query")
+    if not search_paths:
+        raise ValueError("Missing required argument: search_paths")
+    
+    # Extract optional arguments with defaults
+    mode = arguments.get("mode", "DEEP")
+    max_depth = arguments.get("max_depth")
+    top_k_files = arguments.get("top_k_files")
+    keyword_levels = arguments.get("keyword_levels")
+    include = arguments.get("include")
+    exclude = arguments.get("exclude")
+    return_cluster = arguments.get("return_cluster", False)
+    
+    logger.info(f"Handling sirchmunk_search: mode={mode}, query='{query[:50]}...'")
+    
+    try:
+        # Perform search
+        result = await service.search(
+            query=query,
+            search_paths=search_paths,
+            mode=mode,
+            max_depth=max_depth,
+            top_k_files=top_k_files,
+            keyword_levels=keyword_levels,
+            include=include,
+            exclude=exclude,
+            return_cluster=return_cluster,
+        )
+        
+        # Format response based on result type
+        if result is None:
+            response_text = f"No results found for query: {query}"
+        
+        elif isinstance(result, str):
+            # DEEP or FAST mode: string summary
+            response_text = result
+        
+        elif isinstance(result, list):
+            # FILENAME_ONLY mode: list of file matches
+            response_text = _format_filename_results(result, query)
+        
+        elif hasattr(result, "to_dict"):
+            # KnowledgeCluster object
+            response_text = _format_cluster(result)
+        
+        else:
+            response_text = str(result)
+        
+        return [TextContent(
+            type="text",
+            text=response_text,
+        )]
+    
+    except Exception as e:
+        logger.error(f"Search failed: {e}", exc_info=True)
+        error_message = f"Search failed: {str(e)}"
+        return [TextContent(
+            type="text",
+            text=error_message,
+        )]
+
+
+async def handle_sirchmunk_get_cluster(
+    service: SirchmunkService,
+    arguments: Dict[str, Any],
+) -> List[TextContent]:
+    """Handle sirchmunk_get_cluster tool invocation.
+    
+    Args:
+        service: SirchmunkService instance
+        arguments: Tool arguments from MCP client
+    
+    Returns:
+        List of TextContent with cluster information
+    
+    Raises:
+        ValueError: If required arguments are missing
+    """
+    cluster_id = arguments.get("cluster_id")
+    
+    if not cluster_id:
+        raise ValueError("Missing required argument: cluster_id")
+    
+    logger.info(f"Handling sirchmunk_get_cluster: cluster_id={cluster_id}")
+    
+    try:
+        cluster = await service.get_cluster(cluster_id)
+        
+        if cluster is None:
+            response_text = f"Cluster not found: {cluster_id}"
+        else:
+            response_text = _format_cluster(cluster)
+        
+        return [TextContent(
+            type="text",
+            text=response_text,
+        )]
+    
+    except Exception as e:
+        logger.error(f"Get cluster failed: {e}", exc_info=True)
+        error_message = f"Failed to retrieve cluster: {str(e)}"
+        return [TextContent(
+            type="text",
+            text=error_message,
+        )]
+
+
+async def handle_sirchmunk_list_clusters(
+    service: SirchmunkService,
+    arguments: Dict[str, Any],
+) -> List[TextContent]:
+    """Handle sirchmunk_list_clusters tool invocation.
+    
+    Args:
+        service: SirchmunkService instance
+        arguments: Tool arguments from MCP client
+    
+    Returns:
+        List of TextContent with cluster listing
+    """
+    limit = arguments.get("limit", 10)
+    sort_by = arguments.get("sort_by", "last_modified")
+    
+    logger.info(f"Handling sirchmunk_list_clusters: limit={limit}, sort_by={sort_by}")
+    
+    try:
+        clusters = await service.list_clusters(limit=limit, sort_by=sort_by)
+        
+        if not clusters:
+            response_text = "No knowledge clusters found."
+        else:
+            response_text = _format_cluster_list(clusters, sort_by)
+        
+        return [TextContent(
+            type="text",
+            text=response_text,
+        )]
+    
+    except Exception as e:
+        logger.error(f"List clusters failed: {e}", exc_info=True)
+        error_message = f"Failed to list clusters: {str(e)}"
+        return [TextContent(
+            type="text",
+            text=error_message,
+        )]
+
+
+def _format_filename_results(results: List[Dict[str, Any]], query: str) -> str:
+    """Format FILENAME_ONLY mode results.
+    
+    Args:
+        results: List of filename match dictionaries
+        query: Original query
+    
+    Returns:
+        Formatted string representation
+    """
+    lines = [
+        f"# Filename Search Results",
+        f"",
+        f"**Query**: `{query}`",
+        f"**Found**: {len(results)} matching file(s)",
+        f"",
+    ]
+    
+    for i, result in enumerate(results, 1):
+        lines.append(f"## {i}. {result['filename']}")
+        lines.append(f"- **Path**: `{result['path']}`")
+        lines.append(f"- **Relevance**: {result['match_score']:.2f}")
+        if "matched_pattern" in result:
+            lines.append(f"- **Pattern**: `{result['matched_pattern']}`")
+        lines.append("")
+    
+    return "\n".join(lines)
+
+
+def _format_cluster(cluster: Any) -> str:
+    """Format KnowledgeCluster object.
+    
+    Args:
+        cluster: KnowledgeCluster object
+    
+    Returns:
+        Formatted string representation
+    """
+    # Use the cluster's __str__ method for human-readable format
+    return str(cluster)
+
+
+def _format_cluster_list(clusters: List[Dict[str, Any]], sort_by: str) -> str:
+    """Format cluster list.
+    
+    Args:
+        clusters: List of cluster metadata dictionaries
+        sort_by: Sort field used
+    
+    Returns:
+        Formatted string representation
+    """
+    lines = [
+        f"# Knowledge Clusters",
+        f"",
+        f"**Total**: {len(clusters)} cluster(s)",
+        f"**Sorted by**: {sort_by}",
+        f"",
+    ]
+    
+    for i, cluster in enumerate(clusters, 1):
+        lines.append(f"## {i}. {cluster['name']}")
+        lines.append(f"- **ID**: `{cluster['id']}`")
+        lines.append(f"- **Lifecycle**: {cluster['lifecycle']}")
+        lines.append(f"- **Version**: {cluster['version']}")
+        
+        if cluster['confidence'] is not None:
+            lines.append(f"- **Confidence**: {cluster['confidence']:.2f}")
+        
+        if cluster['hotness'] is not None:
+            lines.append(f"- **Hotness**: {cluster['hotness']:.2f}")
+        
+        if cluster['last_modified']:
+            lines.append(f"- **Last Modified**: {cluster['last_modified']}")
+        
+        if cluster['queries']:
+            queries_preview = ", ".join(f'"{q}"' for q in cluster['queries'][:3])
+            if len(cluster['queries']) > 3:
+                queries_preview += f" (+{len(cluster['queries']) - 3} more)"
+            lines.append(f"- **Related Queries**: {queries_preview}")
+        
+        lines.append(f"- **Evidences**: {cluster['evidences_count']}")
+        lines.append("")
+    
+    return "\n".join(lines)
+
+
+# Tool handler registry
+TOOL_HANDLERS = {
+    "sirchmunk_search": handle_sirchmunk_search,
+    "sirchmunk_get_cluster": handle_sirchmunk_get_cluster,
+    "sirchmunk_list_clusters": handle_sirchmunk_list_clusters,
+}

sirchmunk-0.0.1.post1.dist-info/RECORD

@@ -1,45 +0,0 @@
-sirchmunk/__init__.py,sha256=5sdppELUcjnTofJtwZ2ACuUscmLYIPhCwj-G-MMSl-M,184
-sirchmunk/base.py,sha256=qVQ63QfEWhEvOJl3OxQvC2rOUNTZCD5weXRn-1vvEkU,439
-sirchmunk/search.py,sha256=NROpV39oklDT4wusE8EnkQPABq9LiAa0kQrtyR6viHQ,18210
-sirchmunk/version.py,sha256=kBLMG2WZUGcfsN5po-4OyjkyndbcTcGgae_91l8-sFE,28
-sirchmunk/insight/__init__.py,sha256=7sQeT0fSg5-b9jrwthA9_fSCR1Q5qSvm33L9l7kHjLY,144
-sirchmunk/insight/text_insights.py,sha256=BwFqmDNG8FmOz4Lv3qO1Mz2xRv_LVg4b3wj6YUhVLVE,9075
-sirchmunk/learnings/__init__.py,sha256=310L84MdAIw4THnzf5YsLiUhW_oaxgJHHcZZeMso3jY,61
-sirchmunk/learnings/evidence_processor.py,sha256=QDg-qReSte8R8I2BrRRC-d-Glyfjcnqazbe57-PSDHU,17922
-sirchmunk/learnings/knowledge_base.py,sha256=8szliKLFKu_BTIVf0vhy2mSe7Tix4145Umdd5OQ2rww,8343
-sirchmunk/llm/__init__.py,sha256=4ynF6R63afMWW1d9T21C8JqfVc9xJTiOFXZNzDwPLww,98
-sirchmunk/llm/openai_chat.py,sha256=ET7HqEoFTbbvhUTlAUZNOoJwxF9hA73qeH3xFTsNK-w,8138
-sirchmunk/llm/prompts.py,sha256=8Wpugif43EhCaDuRF4U6xRgbv6EB_UdU-2NdDFuglM0,8755
-sirchmunk/retrieve/__init__.py,sha256=310L84MdAIw4THnzf5YsLiUhW_oaxgJHHcZZeMso3jY,61
-sirchmunk/retrieve/base.py,sha256=VDpCwdwhjVYuj0mbe78qg_FhbcQkasbCS0cd66hQ4hk,618
-sirchmunk/retrieve/text_retriever.py,sha256=1ryDjqecXJz2bwjeoJhaUvMxCAdoNzPMMOAJYH3x7g0,39484
-sirchmunk/scan/__init__.py,sha256=310L84MdAIw4THnzf5YsLiUhW_oaxgJHHcZZeMso3jY,61
-sirchmunk/scan/base.py,sha256=3Jqvn0W9KJ00u2oy8U-qD16KksV7taAx4s9qhCpRD-c,496
-sirchmunk/scan/file_scanner.py,sha256=GtGFP9ZwqemOSkHjFcEDaD2WCnw5qMB_bCeiVUaIEQg,14645
-sirchmunk/scan/web_scanner.py,sha256=YQRBQ5JnATwNdek2o1_Y8GB0eG0IWQvx4YhqW4Zc5Tw,531
-sirchmunk/scheduler/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sirchmunk/schema/__init__.py,sha256=kvzKU8Rt1t91Rm5tuy6KqgZXj8lfYQ2q1XvLYGNLUh4,103
-sirchmunk/schema/cognition.py,sha256=NDgCOjMpqyUBxd_ymeMQrjSr3Ri-nJeMUNRuWfLUhBI,4031
-sirchmunk/schema/context.py,sha256=wwsSBE5EJXmrvh-RCluf3nJm7hcxkWaiNWfJ10coGY4,628
-sirchmunk/schema/knowledge.py,sha256=mPKuhqXzLFIfcz5yHRcNe7B4WifUVlHDNnzeevnFKQM,11108
-sirchmunk/schema/metadata.py,sha256=VdUD6GPCB_jtyBkowkGEpCPMYL1c-sFVSUloKPSZRwE,22810
-sirchmunk/schema/request.py,sha256=EPum-IzmN15EgFmwN12oL-CNoI-KvTcHN4nLuO-c09c,7702
-sirchmunk/schema/response.py,sha256=6xc5tvAnqL_zpUhQtchVGwbrt1btzy4QArCeS81DrIU,488
-sirchmunk/schema/snapshot.py,sha256=zZSKDRN8jMtpOIH3TL0FCrAn7AlUc_5zO8qFX2f2u_s,12341
-sirchmunk/storage/__init__.py,sha256=9mF1JdbVrgC0mt9uvBYU9RwiLGRdrmwGAyTj7EA21Pg,231
-sirchmunk/storage/duckdb.py,sha256=Jw_EK9i589YyKXYhi-yjAmX7zIM7txDsoxy0Gx-XY8o,23092
-sirchmunk/storage/knowledge_manager.py,sha256=YYlZa4CnbCXzFWjOleztil2hohqrvrOZs-8UcV0DTEM,27746
-sirchmunk/utils/__init__.py,sha256=33bVrhpUfPXpM85r_SEB07QJnGDjD-4BE5p9vpF-fXw,265
-sirchmunk/utils/constants.py,sha256=D6RP2mtRH9uA3ZI1SpFD77_QPtYkxIKIi7zZY8-do1w,551
-sirchmunk/utils/deps.py,sha256=QTL0k7CN1t0_r-CrZ4TM__pdK8U2X1d0OKvJUtQe_xA,563
-sirchmunk/utils/file_utils.py,sha256=9OtYNffXbo1Pz6XuJsOECQS_mYRBg1NpGUsglNgfWnU,2257
-sirchmunk/utils/install_rga.py,sha256=i7sWYi6u2A32dc0mq5LB_OtqcMWqKezSz6WILWaK1Oc,5215
-sirchmunk/utils/log_utils.py,sha256=HujosgEXV9fpSVd6JjRh7KEQuskhrcpC4Kit6aIpnW0,14195
-sirchmunk/utils/tokenizer_util.py,sha256=JIg4FylB6o8AIe71q8Uv83PKmPF1funX3ffhb9cPX3c,1624
-sirchmunk/utils/utils.py,sha256=qnwZ8R9xLqsMooW0IdcWoPKto7q4AQ49-SOR33rCy1g,3394
-sirchmunk-0.0.1.post1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-sirchmunk-0.0.1.post1.dist-info/METADATA,sha256=H4zSxLJBlsFVfMPT1HscJvNkCfR0AmfNEA0m0XfQsoQ,18408
-sirchmunk-0.0.1.post1.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-sirchmunk-0.0.1.post1.dist-info/entry_points.txt,sha256=lpnP-Ll2CUY0P1wYm6kutcBMrxwG67astmgY-vVhF14,56
-sirchmunk-0.0.1.post1.dist-info/top_level.txt,sha256=8MiQvqjFkqiGJ7m4xqxsfxwxFHtH2mIXlrkV9PfX-aM,10
-sirchmunk-0.0.1.post1.dist-info/RECORD,,

sirchmunk-0.0.1.post1.dist-info/top_level.txt

@@ -1 +0,0 @@
-sirchmunk