sequential-thinking 0.6.0__py3-none-any.whl

mcp_sequential_thinking/analysis.py

@@ -0,0 +1,219 @@
+from collections import Counter
+from typing import Any
+from uuid import UUID
+
+from .logging_conf import configure_logging
+from .models import ThoughtData, ThoughtStage
+
+logger = configure_logging("sequential-thinking.analysis")
+
+
+class ThoughtAnalyzer:
+    """Analyzer for thought data to extract insights and patterns."""
+
+    @staticmethod
+    def find_related_thoughts(
+        current_thought: ThoughtData, all_thoughts: list[ThoughtData], max_results: int = 3
+    ) -> list[ThoughtData]:
+        """Find thoughts related to the current thought.
+
+        Args:
+            current_thought: The current thought to find related thoughts for
+            all_thoughts: All available thoughts to search through
+            max_results: Maximum number of related thoughts to return
+
+        Returns:
+            List[ThoughtData]: Related thoughts, sorted by relevance
+        """
+        # First, find thoughts in the same stage
+        same_stage = [
+            t
+            for t in all_thoughts
+            if t.stage == current_thought.stage and t.id != current_thought.id
+        ]
+
+        # Then, find thoughts with similar tags
+        if current_thought.tags:
+            tag_matches: list[tuple[ThoughtData, int]] = []
+            for thought in all_thoughts:
+                if thought.id == current_thought.id:
+                    continue
+
+                # Count matching tags
+                matching_tags = set(current_thought.tags) & set(thought.tags)
+                if matching_tags:
+                    tag_matches.append((thought, len(matching_tags)))
+
+            # Sort by number of matching tags (descending)
+            tag_matches.sort(key=lambda x: x[1], reverse=True)
+            tag_related = [t[0] for t in tag_matches]
+        else:
+            tag_related: list[ThoughtData] = []
+
+        # Combine and deduplicate results
+        combined: list[ThoughtData] = []
+        seen_ids: set[UUID] = set()
+
+        # First add same stage thoughts
+        for thought in same_stage:
+            if thought.id not in seen_ids:
+                combined.append(thought)
+                seen_ids.add(thought.id)
+
+                if len(combined) >= max_results:
+                    break
+
+        # Then add tag-related thoughts
+        if len(combined) < max_results:
+            for thought in tag_related:
+                if thought.id not in seen_ids:
+                    combined.append(thought)
+                    seen_ids.add(thought.id)
+
+                    if len(combined) >= max_results:
+                        break
+
+        return combined
+
+    @staticmethod
+    def generate_summary(thoughts: list[ThoughtData]) -> dict[str, Any]:
+        """Generate a summary of the thinking process.
+
+        Args:
+            thoughts: List of thoughts to summarize
+
+        Returns:
+            Dict[str, Any]: Summary data
+        """
+        if not thoughts:
+            return {"summary": "No thoughts recorded yet"}
+
+        # Group thoughts by stage
+        stages: dict[str, list[ThoughtData]] = {}
+        for thought in thoughts:
+            if thought.stage.value not in stages:
+                stages[thought.stage.value] = []
+            stages[thought.stage.value].append(thought)
+
+        # Count tags - using a more readable approach with explicit steps
+        # Collect all tags from all thoughts
+        all_tags: list[str] = []
+        for thought in thoughts:
+            all_tags.extend(thought.tags)
+
+        # Count occurrences of each tag
+        tag_counts: Counter[str] = Counter(all_tags)
+
+        # Get the 5 most common tags
+        top_tags: list[tuple[str, int]] = tag_counts.most_common(5)
+
+        # Create summary
+        try:
+            # Safely calculate max total thoughts to avoid division by zero
+            max_total = 0
+            if thoughts:
+                max_total = max((t.total_thoughts for t in thoughts), default=0)
+
+            # Calculate percent complete safely
+            percent_complete = 0
+            if max_total > 0:
+                percent_complete = (len(thoughts) / max_total) * 100
+
+            logger.debug(
+                f"Calculating completion: {len(thoughts)}/{max_total} = {percent_complete}%"
+            )
+
+            # Build the summary dictionary with more readable and
+            # maintainable list comprehensions
+
+            # Count thoughts by stage
+            stage_counts: dict[str, int] = {
+                stage: len(thoughts_list) for stage, thoughts_list in stages.items()
+            }
+
+            # Create timeline entries
+            sorted_thoughts = sorted(thoughts, key=lambda x: x.thought_number)
+            timeline_entries: list[dict[str, int | str]] = []
+            for t in sorted_thoughts:
+                timeline_entries.append({"number": t.thought_number, "stage": t.stage.value})
+
+            # Create top tags entries
+            top_tags_entries: list[dict[str, int | str]] = []
+            for tag, count in top_tags:
+                top_tags_entries.append({"tag": tag, "count": count})
+
+            # Check if all stages are represented
+            all_stages_present = all(stage.value in stages for stage in ThoughtStage)
+
+            # Assemble the final summary
+            summary: dict[str, Any] = {
+                "totalThoughts": len(thoughts),
+                "stages": stage_counts,
+                "timeline": timeline_entries,
+                "topTags": top_tags_entries,
+                "completionStatus": {
+                    "hasAllStages": all_stages_present,
+                    "percentComplete": percent_complete,
+                },
+            }
+        except Exception as e:
+            logger.error(f"Error generating summary: {e}")
+            summary = {"totalThoughts": len(thoughts), "error": str(e)}
+
+        return {"summary": summary}
+
+    @staticmethod
+    def analyze_thought(thought: ThoughtData, all_thoughts: list[ThoughtData]) -> dict[str, Any]:
+        """Analyze a single thought in the context of all thoughts.
+
+        Args:
+            thought: The thought to analyze
+            all_thoughts: All available thoughts for context
+
+        Returns:
+            Dict[str, Any]: Analysis results
+        """
+        # Find related thoughts
+        related_thoughts = ThoughtAnalyzer.find_related_thoughts(thought, all_thoughts)
+
+        # Check if this is the first thought in its stage (lowest thought_number)
+        same_stage_thoughts = [t for t in all_thoughts if t.stage == thought.stage]
+        is_first_in_stage = all(
+            t.thought_number >= thought.thought_number for t in same_stage_thoughts
+        )
+
+        # Calculate progress
+        progress = (thought.thought_number / thought.total_thoughts) * 100
+
+        # Create analysis
+        return {
+            "thoughtAnalysis": {
+                "currentThought": {
+                    "thoughtNumber": thought.thought_number,
+                    "totalThoughts": thought.total_thoughts,
+                    "nextThoughtNeeded": thought.next_thought_needed,
+                    "stage": thought.stage.value,
+                    "tags": thought.tags,
+                    "timestamp": thought.timestamp,
+                },
+                "analysis": {
+                    "relatedThoughtsCount": len(related_thoughts),
+                    "relatedThoughtSummaries": [
+                        {
+                            "thoughtNumber": t.thought_number,
+                            "stage": t.stage.value,
+                            "snippet": (
+                                t.thought[:100] + "..." if len(t.thought) > 100 else t.thought
+                            ),
+                        }
+                        for t in related_thoughts
+                    ],
+                    "progress": progress,
+                    "isFirstInStage": is_first_in_stage,
+                },
+                "context": {
+                    "thoughtHistoryLength": len(all_thoughts),
+                    "currentStage": thought.stage.value,
+                },
+            }
+        }

mcp_sequential_thinking/logging_conf.py

@@ -0,0 +1,22 @@
+import logging
+import sys
+
+
+def configure_logging(name: str = "sequential-thinking") -> logging.Logger:
+    """Configure and return a logger with standardized settings.
+
+    Args:
+        name: The name for the logger
+
+    Returns:
+        logging.Logger: Configured logger instance
+    """
+    # Configure root logger
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        handlers=[logging.StreamHandler(sys.stderr)],
+    )
+
+    # Get and return the named logger
+    return logging.getLogger(name)

mcp_sequential_thinking/models.py

@@ -0,0 +1,200 @@
+from datetime import datetime
+from enum import Enum
+from typing import Any
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, ValidationInfo, field_validator
+
+
+class ThoughtStage(Enum):
+    """Basic thinking stages for structured sequential thinking."""
+
+    PROBLEM_DEFINITION = "Problem Definition"
+    RESEARCH = "Research"
+    ANALYSIS = "Analysis"
+    SYNTHESIS = "Synthesis"
+    CONCLUSION = "Conclusion"
+
+    @classmethod
+    def from_string(cls, value: str) -> "ThoughtStage":
+        """Convert a string to a thinking stage.
+
+        Args:
+            value: The string representation of the thinking stage
+
+        Returns:
+            ThoughtStage: The corresponding ThoughtStage enum value
+
+        Raises:
+            ValueError: If the string does not match any valid thinking stage
+        """
+        # Case-insensitive comparison
+        for stage in cls:
+            if stage.value.casefold() == value.casefold():
+                return stage
+
+        # If no match found
+        valid_stages = ", ".join(stage.value for stage in cls)
+        raise ValueError(f"Invalid thinking stage: '{value}'. Valid stages are: {valid_stages}")
+
+
+class ThoughtData(BaseModel):
+    """Data structure for a single thought in the sequential thinking process."""
+
+    thought: str
+    thought_number: int
+    total_thoughts: int
+    next_thought_needed: bool
+    stage: ThoughtStage
+    tags: list[str] = Field(default_factory=list)
+    axioms_used: list[str] = Field(default_factory=list)
+    assumptions_challenged: list[str] = Field(default_factory=list)
+    timestamp: str = Field(default_factory=lambda: datetime.now().isoformat())
+    id: UUID = Field(default_factory=uuid4)
+
+    def __hash__(self) -> int:
+        """Make ThoughtData hashable based on its ID."""
+        return hash(self.id)
+
+    def __eq__(self, other: object) -> bool:
+        """Compare ThoughtData objects based on their ID."""
+        if not isinstance(other, ThoughtData):
+            return False
+        return self.id == other.id
+
+    @field_validator("thought")
+    def thought_not_empty(cls, v: str) -> str:
+        """Validate that thought content is not empty."""
+        if not v or not v.strip():
+            raise ValueError("Thought content cannot be empty")
+        return v
+
+    @field_validator("thought_number")
+    def thought_number_positive(cls, v: int) -> int:
+        """Validate that thought number is positive."""
+        if v < 1:
+            raise ValueError("Thought number must be positive")
+        return v
+
+    @field_validator("total_thoughts")
+    def total_thoughts_valid(cls, v: int, info: ValidationInfo) -> int:
+        """Validate that total thoughts is valid."""
+        thought_number = info.data.get("thought_number")
+        if thought_number is not None and v < thought_number:
+            raise ValueError("Total thoughts must be greater or equal to current thought number")
+        return v
+
+    def validate(self) -> bool:  # pyright: ignore[reportIncompatibleMethodOverride]
+        """Legacy validation method for backward compatibility.
+
+        Returns:
+            bool: True if the thought data is valid
+
+        Raises:
+            ValueError: If any validation checks fail
+        """
+        # Validation is now handled by Pydantic automatically
+        return True
+
+    def to_dict(self, include_id: bool = False) -> dict[str, Any]:
+        """Convert the thought data to a dictionary representation.
+
+        Args:
+            include_id: Whether to include the ID in the dictionary representation.
+                        Default is False to maintain compatibility with tests.
+
+        Returns:
+            dict: Dictionary representation of the thought data
+        """
+        from .utils import to_camel_case
+
+        # Get all model fields, excluding internal properties
+        data = self.model_dump()
+
+        # Handle special conversions
+        data["stage"] = self.stage.value
+
+        if not include_id:
+            # Remove ID for external representations
+            data.pop("id", None)
+        else:
+            # Convert ID to string for JSON serialization
+            data["id"] = str(data["id"])
+
+        # Convert snake_case keys to camelCase for API consistency
+        result: dict[str, Any] = {}
+        for key, value in data.items():
+            if key == "stage":
+                # Stage is already handled above
+                continue
+
+            camel_key = to_camel_case(key)
+            result[camel_key] = value
+
+        # Ensure these fields are always present with camelCase naming
+        result["thought"] = self.thought
+        result["thoughtNumber"] = self.thought_number
+        result["totalThoughts"] = self.total_thoughts
+        result["nextThoughtNeeded"] = self.next_thought_needed
+        result["stage"] = self.stage.value
+        result["tags"] = self.tags
+        result["axiomsUsed"] = self.axioms_used
+        result["assumptionsChallenged"] = self.assumptions_challenged
+        result["timestamp"] = self.timestamp
+
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ThoughtData":
+        """Create a ThoughtData instance from a dictionary.
+
+        Args:
+            data: Dictionary containing thought data
+
+        Returns:
+            ThoughtData: A new ThoughtData instance
+        """
+        # Convert any camelCase keys to snake_case
+        snake_data: dict[str, Any] = {}
+        mappings = {
+            "thoughtNumber": "thought_number",
+            "totalThoughts": "total_thoughts",
+            "nextThoughtNeeded": "next_thought_needed",
+            "axiomsUsed": "axioms_used",
+            "assumptionsChallenged": "assumptions_challenged",
+        }
+
+        # Process known direct mappings
+        for camel_key, snake_key in mappings.items():
+            if camel_key in data:
+                snake_data[snake_key] = data[camel_key]
+
+        # Copy fields that don't need conversion
+        for key in ["thought", "tags", "timestamp"]:
+            if key in data:
+                snake_data[key] = data[key]
+
+        # Handle special fields
+        if "stage" in data:
+            stage_value = data["stage"]
+            if not isinstance(stage_value, str):
+                raise ValueError("Stage must be a string")
+            snake_data["stage"] = ThoughtStage.from_string(stage_value)
+
+        # Set default values for missing fields
+        snake_data.setdefault("tags", [])
+        snake_data.setdefault("axioms_used", data.get("axiomsUsed", []))
+        snake_data.setdefault("assumptions_challenged", data.get("assumptionsChallenged", []))
+        snake_data.setdefault("timestamp", datetime.now().isoformat())
+
+        # Add ID if present, otherwise generate a new one
+        if "id" in data:
+            try:
+                id_value = data["id"]
+                snake_data["id"] = UUID(id_value) if isinstance(id_value, str) else uuid4()
+            except (ValueError, TypeError):
+                snake_data["id"] = uuid4()
+
+        return cls(**snake_data)
+
+    model_config = {"arbitrary_types_allowed": True}

mcp_sequential_thinking/server.py

@@ -0,0 +1,213 @@
+import os
+import sys
+from typing import Any
+
+from mcp.server.fastmcp import Context, FastMCP
+
+# Use absolute imports when running as a script
+try:
+    # When installed as a package
+    from .analysis import ThoughtAnalyzer
+    from .logging_conf import configure_logging
+    from .models import ThoughtData, ThoughtStage
+    from .storage import ThoughtStorage
+except ImportError:
+    # When run directly
+    from mcp_sequential_thinking.analysis import ThoughtAnalyzer
+    from mcp_sequential_thinking.logging_conf import configure_logging
+    from mcp_sequential_thinking.models import ThoughtData, ThoughtStage
+    from mcp_sequential_thinking.storage import ThoughtStorage
+
+logger = configure_logging("sequential-thinking.server")
+
+
+mcp = FastMCP("sequential-thinking")
+
+storage_dir = os.environ.get("MCP_STORAGE_DIR", None)
+storage = ThoughtStorage(storage_dir)
+
+
+@mcp.tool()  # pyright: ignore[reportUnknownMemberType, reportUntypedFunctionDecorator]
+async def process_thought(
+    thought: str,
+    thought_number: int,
+    total_thoughts: int,
+    next_thought_needed: bool,
+    stage: str,
+    tags: list[str] = [],
+    axioms_used: list[str] = [],
+    assumptions_challenged: list[str] = [],
+    ctx: Context[Any, Any, Any] | None = None,
+) -> dict[str, Any]:
+    """Add a sequential thought with its metadata.
+
+    Args:
+        thought: The content of the thought
+        thought_number: The sequence number of this thought
+        total_thoughts: The total expected thoughts in the sequence
+        next_thought_needed: Whether more thoughts are needed after this one
+        stage: The thinking stage (Problem Definition, Research, Analysis, Synthesis, Conclusion)
+        tags: Optional keywords or categories for the thought
+        axioms_used: Optional list of principles or axioms used in this thought
+        assumptions_challenged: Optional list of assumptions challenged by this thought
+        ctx: Optional MCP context object
+
+    Returns:
+        dict: Analysis of the processed thought
+    """
+    try:
+        # Log the request
+        logger.info(f"Processing thought #{thought_number}/{total_thoughts} in stage '{stage}'")
+
+        # Report progress if context is available
+        if ctx:
+            await ctx.report_progress(thought_number - 1, total_thoughts)
+
+        # Convert stage string to enum
+        thought_stage = ThoughtStage.from_string(stage)
+
+        # Create thought data object with defaults for optional fields
+        thought_data = ThoughtData(
+            thought=thought,
+            thought_number=thought_number,
+            total_thoughts=total_thoughts,
+            next_thought_needed=next_thought_needed,
+            stage=thought_stage,
+            tags=tags,
+            axioms_used=axioms_used,
+            assumptions_challenged=assumptions_challenged,
+        )
+
+        # Validate and store
+        thought_data.validate()
+        storage.add_thought(thought_data)
+
+        # Get all thoughts for analysis
+        all_thoughts = storage.get_all_thoughts()
+
+        # Analyze the thought
+        analysis = ThoughtAnalyzer.analyze_thought(thought_data, all_thoughts)
+
+        # Log success
+        logger.info(f"Successfully processed thought #{thought_number}")
+
+        return analysis
+    except Exception as e:
+        logger.error(f"Error processing thought: {e!s}")
+
+        return {"error": str(e), "status": "failed"}
+
+
+@mcp.tool()  # pyright: ignore[reportUnknownMemberType, reportUntypedFunctionDecorator]
+def generate_summary() -> dict[str, Any]:
+    """Generate a summary of the entire thinking process.
+
+    Returns:
+        dict: Summary of the thinking process
+    """
+    try:
+        logger.info("Generating thinking process summary")
+
+        # Get all thoughts
+        all_thoughts = storage.get_all_thoughts()
+
+        # Generate summary
+        return ThoughtAnalyzer.generate_summary(all_thoughts)
+    except Exception as e:
+        logger.error(f"Error generating summary: {e!s}")
+        return {"error": str(e), "status": "failed"}
+
+
+@mcp.tool()  # pyright: ignore[reportUnknownMemberType, reportUntypedFunctionDecorator]
+def clear_history() -> dict[str, Any]:
+    """Clear the thought history.
+
+    Returns:
+        dict: Status message
+    """
+    try:
+        logger.info("Clearing thought history")
+        storage.clear_history()
+        return {"status": "success", "message": "Thought history cleared"}
+    except Exception as e:
+        logger.error(f"Error clearing history: {e!s}")
+        return {"error": str(e), "status": "failed"}
+
+
+@mcp.tool()  # pyright: ignore[reportUnknownMemberType, reportUntypedFunctionDecorator]
+def export_session(file_path: str) -> dict[str, Any]:
+    """Export the current thinking session to a file.
+
+    Args:
+        file_path: Path to save the exported session
+
+    Returns:
+        dict: Status message
+    """
+    try:
+        logger.info(f"Exporting session to {file_path}")
+        storage.export_session(file_path)
+        return {"status": "success", "message": f"Session exported to {file_path}"}
+    except Exception as e:
+        logger.error(f"Error exporting session: {e!s}")
+        return {"error": str(e), "status": "failed"}
+
+
+@mcp.tool()  # pyright: ignore[reportUnknownMemberType, reportUntypedFunctionDecorator]
+def import_session(file_path: str) -> dict[str, Any]:
+    """Import a thinking session from a file.
+
+    Args:
+        file_path: Path to the file to import
+
+    Returns:
+        dict: Status message
+    """
+    try:
+        logger.info(f"Importing session from {file_path}")
+        storage.import_session(file_path)
+        return {"status": "success", "message": f"Session imported from {file_path}"}
+    except Exception as e:
+        logger.error(f"Error importing session: {e!s}")
+        return {"error": str(e), "status": "failed"}
+
+
+def main() -> None:
+    """Entry point for the MCP server."""
+    logger.info("Starting Sequential Thinking MCP server")
+
+    # Ensure UTF-8 encoding for stdin/stdout
+    if hasattr(sys.stdout, "buffer") and sys.stdout.encoding != "utf-8":
+        import io
+
+        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", line_buffering=True)
+    if hasattr(sys.stdin, "buffer") and sys.stdin.encoding != "utf-8":
+        import io
+
+        sys.stdin = io.TextIOWrapper(sys.stdin.buffer, encoding="utf-8", line_buffering=True)
+
+    # Flush stdout to ensure no buffered content remains
+    sys.stdout.flush()
+
+    # Run the MCP server
+    mcp.run()
+
+
+if __name__ == "__main__":
+    # When running the script directly, ensure we're in the right directory
+    import os
+    import sys
+
+    # Add the parent directory to sys.path if needed
+    parent_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    if parent_dir not in sys.path:
+        sys.path.insert(0, parent_dir)
+
+    # Print debug information
+    logger.info(f"Python version: {sys.version}")
+    logger.info(f"Current working directory: {os.getcwd()}")
+    logger.info(f"Script directory: {os.path.dirname(os.path.abspath(__file__))}")
+    logger.info(f"Parent directory added to path: {parent_dir}")
+
+    # Run the server
+    main()