sequential-thinking 0.6.0__tar.gz

sequential_thinking-0.6.0/.envrc

@@ -0,0 +1,3 @@
+export PROJECT_ROOT=$(pwd)
+source_env_if_exists ~/.envrc
+source_env_if_exists .envrc.local

sequential_thinking-0.6.0/.gitignore

@@ -0,0 +1,6 @@
+.venv
+__pycache__
+*.pyc
+.coverage
+.ruff_cache
+.pytest_cache

sequential_thinking-0.6.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+## Version 0.5.0 (Unreleased)
+
+### Code Quality Improvements
+
+#### 1. Separation of Test Code from Production Code
+- Created a new `testing.py` module for test-specific utilities
+- Implemented conditional test detection using `importlib.util`
+- Improved code clarity by moving test-specific logic out of main modules
+- Enhanced maintainability by clearly separating test and production code paths
+- Replaced hardcoded test strings with named constants
+
+#### 2. Reduced Code Duplication in Storage Layer
+- Created a new `storage_utils.py` module with shared utility functions
+- Implemented reusable functions for file operations and serialization
+- Standardized error handling and backup creation
+- Improved consistency across serialization operations
+- Optimized resource management with cleaner context handling
+
+#### 3. API and Data Structure Improvements
+- Added explicit parameter for ID inclusion in `to_dict()` method
+- Created utility module with snake_case/camelCase conversion functions
+- Eliminated flag-based solution in favor of explicit method parameters
+- Improved readability with clearer, more explicit list comprehensions
+- Eliminated duplicate calculations in analysis methods
+
+## Version 0.4.0
+
+### Major Improvements
+
+#### 1. Serialization & Validation with Pydantic
+- Converted `ThoughtData` from dataclass to Pydantic model
+- Added automatic validation with field validators
+- Maintained backward compatibility with existing code
+
+#### 2. Thread-Safety in Storage Layer
+- Added file locking with `portalocker` to prevent race conditions
+- Added thread locks to protect shared data structures
+- Made all methods thread-safe
+
+#### 3. Fixed Division-by-Zero in Analysis
+- Added proper error handling in `generate_summary` method
+- Added safe calculation of percent complete with default values
+
+#### 4. Case-Insensitive Stage Comparison
+- Updated `ThoughtStage.from_string` to use case-insensitive comparison
+- Improved user experience by accepting any case for stage names
+
+#### 5. Added UUID to ThoughtData
+- Added a unique identifier to each thought for better tracking
+- Maintained backward compatibility with existing code
+
+#### 6. Consolidated Logging Setup
+- Created a central logging configuration in `logging_conf.py`
+- Standardized logging across all modules
+
+#### 7. Improved Package Entry Point
+- Cleaned up the path handling in `run_server.py`
+- Removed redundant code
+
+### New Dependencies
+- Added `portalocker` for file locking
+- Added `pydantic` for data validation
+
+## Version 0.3.0
+
+Initial release with basic functionality:
+- Sequential thinking process with defined stages
+- Thought storage and retrieval
+- Analysis and summary generation

sequential_thinking-0.6.0/CLAUDE.md

@@ -0,0 +1,100 @@
+# CLAUDE.md — Project Working Rules
+
+These rules apply to every task in this repository unless the user explicitly overrides them.
+Bias toward caution on non-trivial work; use judgment and move quickly on trivial, reversible tasks.
+
+## Project Snapshot
+
+This is a Python MCP server for sequential thinking tools.
+
+Common commands:
+
+- Run tests with coverage: `uv run --group dev pytest`
+- Run a focused test: `uv run --group dev pytest tests/test_models.py -q`
+- Format Python: `uv run --group dev ruff format .`
+- Lint/fix Python: `uv run --group dev ruff check --fix .`
+- Type check: `uv run --group dev basedpyright`
+
+If a command is unavailable in the current environment, say so and choose the closest useful verification.
+
+## Rule 1 — Think Before Coding
+
+State assumptions when they affect the solution.
+If the request is ambiguous, present the plausible interpretations and ask before making high-impact changes.
+Push back when a simpler approach would solve the problem.
+If confused, stop and name what is unclear.
+
+## Rule 2 — Simplicity First
+
+Write the minimum code that solves the stated problem.
+Do not add speculative features, broad abstractions, or one-off frameworks.
+Prefer boring, explicit code over clever code.
+Test: would a senior maintainer call this overbuilt? If yes, simplify.
+
+## Rule 3 — Surgical Changes
+
+Touch only the files needed for the task.
+Do not refactor, reformat, rename, or "clean up" adjacent code unless required.
+Preserve existing style, public APIs, and behavior unless changing them is the point of the task.
+Clean up only the mess introduced by this change.
+
+## Rule 4 — Goal-Driven Execution
+
+Define the success criteria before implementing.
+Do not blindly follow a checklist; use the checklist to reach verified success.
+Keep iterating until the success criteria are met or a blocker is surfaced.
+
+## Rule 5 — Use Tools for Deterministic Work
+
+Use the language model for judgment: design tradeoffs, classification, drafting, summarization, and explanation.
+Use code, tests, search, and scripts for deterministic work: routing, counting, parsing, retries, formatting, and verification.
+If code can answer a factual question reliably, let code answer it.
+
+## Rule 6 — Manage Context and Token Budget
+
+Keep each task focused.
+If the work is becoming large, summarize the current state, decisions, and remaining work before continuing.
+Do not silently exceed the scope implied by the request.
+Surface when a task needs a fresh session, a separate plan, or user prioritization.
+
+## Rule 7 — Surface Conflicts, Don't Average Them
+
+If two patterns, requirements, or sources disagree, choose one intentionally.
+Prefer the more local, recent, tested, or user-provided source.
+Explain the choice briefly and flag the conflicting pattern for follow-up if needed.
+Do not blend incompatible conventions.
+
+## Rule 8 — Read Before Writing
+
+Before changing code, inspect the relevant exports, immediate callers, tests, and shared utilities.
+Do not assume a file is isolated just because it looks small.
+If the structure seems odd, look for the reason before changing it.
+
+## Rule 9 — Tests Verify Intent
+
+Tests should encode why the behavior matters, not just what happens today.
+Add or update tests when behavior changes or when fixing a bug.
+A test that would still pass after breaking the intended behavior is not good enough.
+
+## Rule 10 — Checkpoint on Significant Work
+
+After each significant step, be able to state:
+
+- What changed
+- What was verified
+- What remains
+- Any uncertainty or blocker
+
+For trivial edits, keep the checkpoint brief.
+
+## Rule 11 — Match Repository Conventions
+
+Conformance beats personal taste inside this codebase.
+Follow existing naming, layout, dependency, typing, testing, and error-handling patterns.
+If a convention appears harmful, surface it instead of silently forking the style.
+
+## Rule 12 — Fail Loud
+
+Do not claim completion if anything important was skipped.
+Do not claim tests pass if tests were not run, failed, or were only partially run.
+Report skipped verification, environmental limits, assumptions, and risks plainly.

sequential_thinking-0.6.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Otaegui
+Copyright (c) 2025 Arben Ademi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sequential_thinking-0.6.0/PKG-INFO

@@ -0,0 +1,475 @@
+Metadata-Version: 2.4
+Name: sequential-thinking
+Version: 0.6.0
+Summary: A Sequential Thinking MCP Server for advanced problem solving
+Project-URL: Source, https://github.com/feniix/mcp-sequential-thinking
+Project-URL: Original, https://github.com/arben-adm/mcp-sequential-thinking
+Author-email: Sebastian Otaegui <feniix@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,mcp,problem-solving,sequential-thinking
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.27.1
+Requires-Dist: portalocker>=3.2.0
+Requires-Dist: pydantic>=2.13.4
+Description-Content-Type: text/markdown
+
+# Sequential Thinking MCP Server
+
+A Model Context Protocol (MCP) server that facilitates structured, progressive thinking through defined stages. This tool helps break down complex problems into sequential thoughts, track the progression of your thinking process, and generate summaries.
+
+Maintained by **Sebastian Otaegui <feniix@gmail.com>**.
+
+This project is based on the original [`arben-adm/mcp-sequential-thinking`](https://github.com/arben-adm/mcp-sequential-thinking) project by Arben Ademi. See [Attribution](#attribution) for details.
+
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Lint: Ruff](https://img.shields.io/badge/lint-ruff-46a4f5.svg)](https://docs.astral.sh/ruff/)
+
+## Features
+
+- **Structured Thinking Framework**: Organizes thoughts through standard cognitive stages (Problem Definition, Research, Analysis, Synthesis, Conclusion)
+- **Thought Tracking**: Records and manages sequential thoughts with metadata
+- **Related Thought Analysis**: Identifies connections between similar thoughts
+- **Progress Monitoring**: Tracks your position in the overall thinking sequence
+- **Summary Generation**: Creates concise overviews of the entire thought process
+- **Persistent Storage**: Automatically saves your thinking sessions with thread-safety
+- **Data Import/Export**: Share and reuse thinking sessions
+- **Extensible Architecture**: Easily customize and extend functionality
+- **Robust Error Handling**: Graceful handling of edge cases and corrupted data
+- **Type Safety**: Comprehensive type annotations and validation
+
+## Prerequisites
+
+- Python 3.10 or higher
+- UV package manager ([Install Guide](https://github.com/astral-sh/uv))
+
+## Key Technologies
+
+- **MCP Python SDK / FastMCP**: For Model Context Protocol integration
+- **Pydantic**: For data validation and serialization
+- **Portalocker**: For thread-safe file access
+- **uv**: For dependency management and reproducible development environments
+- **Ruff + basedpyright**: For linting, formatting, and strict type checking
+
+## Project Structure
+
+```
+mcp-sequential-thinking/
+├── mcp_sequential_thinking/
+│   ├── server.py       # Main server implementation and MCP tools
+│   ├── models.py       # Data models with Pydantic validation
+│   ├── storage.py      # Thread-safe persistence layer
+│   ├── storage_utils.py # Shared utilities for storage operations
+│   ├── analysis.py     # Thought analysis and pattern detection
+│   ├── utils.py        # Common utilities and helper functions
+│   ├── logging_conf.py # Centralized logging configuration
+│   └── __init__.py     # Package initialization
+├── tests/
+│   ├── test_analysis.py # Tests for analysis functionality
+│   ├── test_models.py   # Tests for data models
+│   ├── test_server.py   # Tests for MCP server tools
+│   ├── test_storage.py  # Tests for persistence layer
+│   ├── test_storage_utils.py # Tests for storage utility edge cases
+│   ├── test_utils.py    # Tests for common utilities
+│   └── __init__.py
+├── run_server.py       # Server entry point script
+├── debug_mcp_connection.py # Utility for debugging connections
+├── README.md           # Main documentation
+├── CHANGELOG.md        # Version history and changes
+├── example.md          # Customization examples
+├── LICENSE             # MIT License
+└── pyproject.toml      # Project configuration and dependencies
+```
+
+## Quick Start
+
+1. **Set Up Project**
+   ```bash
+   # Create and activate virtual environment
+   uv venv
+   .venv\Scripts\activate  # Windows
+   source .venv/bin/activate  # Unix
+
+   # Install package and dependencies
+   uv pip install -e .
+
+   # For development with testing tools
+   uv sync --group dev
+   ```
+
+2. **Run the Server**
+   ```bash
+   # Run directly
+   uv run -m mcp_sequential_thinking.server
+
+   # Or use the installed script
+   mcp-sequential-thinking
+   ```
+
+3. **Run Tests**
+   ```bash
+   # Run all tests with coverage
+   uv run --group dev pytest
+
+   # Run linting and type checks
+   uv run --group dev ruff check .
+   uv run --group dev basedpyright
+   ```
+
+## Claude Desktop Integration
+
+Add to your Claude Desktop configuration:
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Option 1: Using the virtual environment (recommended for Linux/macOS)
+
+If you have set up the project with `uv venv && uv pip install -e .`, point directly to the venv Python interpreter. This avoids dependency resolution issues (e.g., on systems with Python 3.14+):
+
+```json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "/path/to/mcp-sequential-thinking/.venv/bin/python",
+      "args": [
+        "-m",
+        "mcp_sequential_thinking.server"
+      ],
+      "cwd": "/path/to/mcp-sequential-thinking"
+    }
+  }
+}
+```
+
+### Option 2: Using uv run
+
+```json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/path/to/mcp-sequential-thinking",
+        "-m",
+        "mcp_sequential_thinking.server"
+      ]
+    }
+  }
+}
+```
+
+### Option 3: Using the installed entry point
+
+If you've installed the package globally with `pip install -e .`:
+
+```json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "mcp-sequential-thinking"
+    }
+  }
+}
+```
+
+### Option 4: Using uvx (no local install needed)
+
+```json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/feniix/mcp-sequential-thinking",
+        "mcp-sequential-thinking"
+      ]
+    }
+  }
+}
+```
+
+## Editor & IDE Integration
+
+### Cursor
+
+Add to your Cursor MCP configuration at `.cursor/mcp.json` in your project root (or globally at `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/path/to/mcp-sequential-thinking",
+        "-m",
+        "mcp_sequential_thinking.server"
+      ]
+    }
+  }
+}
+```
+
+### VS Code (Copilot MCP)
+
+VS Code supports MCP servers since version 1.99+. Add to `.vscode/mcp.json` in your workspace or to your user `settings.json`:
+
+```json
+{
+  "servers": {
+    "sequential-thinking": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/path/to/mcp-sequential-thinking",
+        "-m",
+        "mcp_sequential_thinking.server"
+      ]
+    }
+  }
+}
+```
+
+> **Note:** Enable MCP support in VS Code via `"chat.mcp.enabled": true` in your settings.
+
+### Zed
+
+Add to your Zed settings (`~/.config/zed/settings.json`):
+
+```json
+{
+  "context_servers": {
+    "sequential-thinking": {
+      "command": {
+        "path": "uv",
+        "args": [
+          "run",
+          "--directory",
+          "/path/to/mcp-sequential-thinking",
+          "-m",
+          "mcp_sequential_thinking.server"
+        ]
+      }
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+Add the server using the CLI:
+
+```bash
+claude mcp add sequential-thinking -- uv run --directory /path/to/mcp-sequential-thinking -m mcp_sequential_thinking.server
+```
+
+Or manually create/edit `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/path/to/mcp-sequential-thinking",
+        "-m",
+        "mcp_sequential_thinking.server"
+      ]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to your Windsurf MCP configuration at `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/path/to/mcp-sequential-thinking",
+        "-m",
+        "mcp_sequential_thinking.server"
+      ]
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add to your Gemini CLI settings at `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/feniix/mcp-sequential-thinking",
+        "mcp-sequential-thinking"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+> **Tip:** All editor configurations above use `uv run` or `uvx`. You can also point directly to the venv Python interpreter (see [Claude Desktop Option 1](#option-1-using-the-virtual-environment-recommended-for-linuxmacos)) or use `uvx` (see [Option 4](#option-4-using-uvx-no-local-install-needed)) if you prefer not to clone the repository.
+
+# How It Works
+
+The server maintains a history of thoughts and processes them through a structured workflow. Each thought is validated using Pydantic models, categorized into thinking stages, and stored with relevant metadata in a thread-safe storage system. The server automatically handles data persistence, backup creation, and provides tools for analyzing relationships between thoughts.
+
+## Usage Guide
+
+The Sequential Thinking server exposes five main tools:
+
+### 1. `process_thought`
+
+Records and analyzes a new thought in your sequential thinking process.
+
+**Parameters:**
+
+- `thought` (string): The content of your thought
+- `thought_number` (integer): Position in your sequence (e.g., 1 for first thought)
+- `total_thoughts` (integer): Expected total thoughts in the sequence
+- `next_thought_needed` (boolean): Whether more thoughts are needed after this one
+- `stage` (string): The thinking stage - must be one of:
+  - "Problem Definition"
+  - "Research"
+  - "Analysis"
+  - "Synthesis"
+  - "Conclusion"
+- `tags` (list of strings, optional): Keywords or categories for your thought
+- `axioms_used` (list of strings, optional): Principles or axioms applied in your thought
+- `assumptions_challenged` (list of strings, optional): Assumptions your thought questions or challenges
+
+**Example:**
+
+```python
+# First thought in a 5-thought sequence
+process_thought(
+    thought="The problem of climate change requires analysis of multiple factors including emissions, policy, and technology adoption.",
+    thought_number=1,
+    total_thoughts=5,
+    next_thought_needed=True,
+    stage="Problem Definition",
+    tags=["climate", "global policy", "systems thinking"],
+    axioms_used=["Complex problems require multifaceted solutions"],
+    assumptions_challenged=["Technology alone can solve climate change"]
+)
+```
+
+### 2. `generate_summary`
+
+Generates a summary of your entire thinking process.
+
+**Example output:**
+
+```json
+{
+  "summary": {
+    "totalThoughts": 5,
+    "stages": {
+      "Problem Definition": 1,
+      "Research": 1,
+      "Analysis": 1,
+      "Synthesis": 1,
+      "Conclusion": 1
+    },
+    "timeline": [
+      {"number": 1, "stage": "Problem Definition"},
+      {"number": 2, "stage": "Research"},
+      {"number": 3, "stage": "Analysis"},
+      {"number": 4, "stage": "Synthesis"},
+      {"number": 5, "stage": "Conclusion"}
+    ]
+  }
+}
+```
+
+### 3. `clear_history`
+
+Resets the thinking process by clearing all recorded thoughts.
+
+### 4. `export_session`
+
+Exports the current thinking session to a JSON file for sharing or backup.
+
+**Parameters:**
+
+- `file_path` (string): Path to the output JSON file (parent directories are created automatically)
+
+**Example:**
+
+```python
+export_session(file_path="/home/user/exports/my-analysis.json")
+```
+
+### 5. `import_session`
+
+Imports a previously exported thinking session from a JSON file.
+
+**Parameters:**
+
+- `file_path` (string): Path to the JSON file to import
+
+## Practical Applications
+
+- **Decision Making**: Work through important decisions methodically
+- **Problem Solving**: Break complex problems into manageable components
+- **Research Planning**: Structure your research approach with clear stages
+- **Writing Organization**: Develop ideas progressively before writing
+- **Project Analysis**: Evaluate projects through defined analytical stages
+
+
+## Getting Started
+
+With the proper MCP setup, simply use the `process_thought` tool to begin working through your thoughts in sequence. As you progress, you can get an overview with `generate_summary` and reset when needed with `clear_history`.
+
+
+
+# Customizing the Sequential Thinking Server
+
+For detailed examples of how to customize and extend the Sequential Thinking server, see [example.md](example.md). It includes code samples for:
+
+- Modifying thinking stages
+- Enhancing thought data structures with Pydantic
+- Adding persistence with databases
+- Implementing enhanced analysis with NLP
+- Creating custom prompts
+- Setting up advanced configurations
+- Building web UI integrations
+- Implementing visualization tools
+- Connecting to external services
+- Creating collaborative environments
+- Separating test code
+- Building reusable utilities
+
+## Attribution
+
+This project is maintained by Sebastian Otaegui <feniix@gmail.com>.
+
+It is based on the original [`arben-adm/mcp-sequential-thinking`](https://github.com/arben-adm/mcp-sequential-thinking) project by Arben Ademi. The original project is also licensed under the MIT License.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for the full license text.
+