diff options
Diffstat (limited to 'cmd/sequential-thinking/README.md')
| -rw-r--r-- | cmd/sequential-thinking/README.md | 361 |
1 files changed, 0 insertions, 361 deletions
diff --git a/cmd/sequential-thinking/README.md b/cmd/sequential-thinking/README.md deleted file mode 100644 index 1d25fb3..0000000 --- a/cmd/sequential-thinking/README.md +++ /dev/null @@ -1,361 +0,0 @@ -# Sequential Thinking MCP Server - -A Model Context Protocol (MCP) server that provides structured thinking workflows with persistent session management and branch tracking for AI assistants to break down complex problems step-by-step. - -## Overview - -The Sequential Thinking MCP server enables AI assistants to engage in structured, step-by-step reasoning through a standardized protocol. It provides tools for organizing thoughts, breaking down complex problems, maintaining logical flow in problem-solving processes, and **persisting thought history across sessions** with full **branch tracking** for alternative reasoning paths. - -## Installation - -### From Source -```bash -# Build the binary -make sequential-thinking - -# Install system-wide (requires sudo) -sudo make install -``` - -### Direct Build -```bash -go build -o mcp-sequential-thinking ./cmd/sequential-thinking -``` - -## Usage - -### Command Line Arguments - -```bash -mcp-sequential-thinking [--session-file <path>] [--help] -``` - -**Options:** -- `--session-file <path>`: Optional file path for persisting thinking sessions across server restarts -- `--help`: Show help message with usage information - -**Example:** -```bash -# Run without persistence (sessions lost on restart) -mcp-sequential-thinking - -# Run with session persistence -mcp-sequential-thinking --session-file /path/to/sessions.json -``` - -### Examples - -#### Basic Testing -```bash -# Test server initialization -echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | timeout 5s mcp-sequential-thinking - -# List available tools -echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | timeout 5s mcp-sequential-thinking - -# Start a thinking process -echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"problem": "How to design a scalable web application?"}}}' | timeout 5s mcp-sequential-thinking -``` - -#### Sequential Thinking Process -```bash -# Start a thinking session with first thought -echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "I need to analyze whether migrating to microservices makes sense for our current system", "nextThoughtNeeded": true, "thoughtNumber": 1, "totalThoughts": 5}}}' | timeout 5s mcp-sequential-thinking - -# Continue with second thought (sessionId will be returned from first call) -echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "Let me first evaluate our current monolith - it serves 10M users with a team of 50 developers", "nextThoughtNeeded": true, "thoughtNumber": 2, "totalThoughts": 5, "sessionId": "session_123456789"}}}' | timeout 5s mcp-sequential-thinking - -# Create a branch for alternative reasoning -echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "What if we consider a hybrid approach instead of full microservices?", "nextThoughtNeeded": true, "thoughtNumber": 3, "totalThoughts": 4, "branchFromThought": 2, "branchId": "hybrid-approach", "sessionId": "session_123456789"}}}' | timeout 5s mcp-sequential-thinking -``` - -## Available Tools - -### Core Thinking Tool -- **`sequentialthinking`**: Engage in step-by-step problem analysis with session persistence - - **Parameters:** - - `thought` (required): Your current thinking step - - `nextThoughtNeeded` (required): Whether another thought step is needed - - `thoughtNumber` (required): Current thought number (1-based) - - `totalThoughts` (required): Estimated total thoughts needed - - `isRevision` (optional): Whether this revises previous thinking - - `revisesThought` (optional): Which thought number is being reconsidered - - `branchFromThought` (optional): Branching point thought number - - `branchId` (optional): Branch identifier for alternative reasoning paths - - `needsMoreThoughts` (optional): If more thoughts are needed beyond initial estimate - - `sessionId` (optional): Session ID for thought continuity (auto-generated if not provided) - - **Returns:** Structured thinking process with session context and persistence - -### Session Management Tools -- **`get_session_history`**: Get the complete thought history for a thinking session - - **Parameters:** - - `sessionId` (required): Session ID to get history for - - **Returns:** Complete session data with all thoughts and metadata - -- **`list_sessions`**: List all active thinking sessions - - **Parameters:** None - - **Returns:** Array of all sessions with summary information - -- **`get_branch_history`**: Get the thought history for a specific reasoning branch - - **Parameters:** - - `branchId` (required): Branch ID to get history for - - **Returns:** Complete branch data with all thoughts and metadata - -- **`clear_session`**: Clear a thinking session and all its branches - - **Parameters:** - - `sessionId` (required): Session ID to clear - - **Returns:** Confirmation message with cleared session details - -## Thinking Frameworks - -### Problem Types -- **Technical Problems**: Software design, architecture decisions, debugging -- **Business Problems**: Strategic decisions, process optimization, market analysis -- **Creative Problems**: Brainstorming, innovation, design thinking -- **Analytical Problems**: Data analysis, research, hypothesis testing - -### Depth Levels -1. **Surface (1)**: Basic overview and immediate considerations -2. **Standard (2)**: Common approach with key factors identified -3. **Detailed (3)**: Comprehensive analysis with multiple perspectives (default) -4. **Deep (4)**: Thorough examination with edge cases and implications -5. **Exhaustive (5)**: Complete analysis with all possible angles and contingencies - -### Focus Areas -- **Technical**: Implementation details, architecture, performance, scalability -- **Business**: ROI, market impact, stakeholder concerns, strategic alignment -- **Creative**: Innovation, user experience, design alternatives, brainstorming -- **Analytical**: Data-driven insights, metrics, testing, validation - -## Configuration Examples - -### Claude Desktop Integration -```json -{ - "mcpServers": { - "sequential-thinking": { - "command": "/usr/local/bin/mcp-sequential-thinking" - } - } -} -``` - -### With Session Persistence -```json -{ - "mcpServers": { - "sequential-thinking": { - "command": "/usr/local/bin/mcp-sequential-thinking", - "args": ["--session-file", "/home/user/.mcp/thinking-sessions.json"] - } - } -} -``` - -## Example Workflows - -### Basic Sequential Thinking -```bash -# Start a new thinking session -echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "I need to decide whether to implement caching for our API", "nextThoughtNeeded": true, "thoughtNumber": 1, "totalThoughts": 4}}}' | mcp-sequential-thinking - -# Continue the thinking process -echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "Current performance metrics show 500ms average response time with 10K requests/min", "nextThoughtNeeded": true, "thoughtNumber": 2, "totalThoughts": 4, "sessionId": "session_1735056789"}}}' | mcp-sequential-thinking - -# Revise a previous thought -echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "Actually, let me reconsider - the 500ms includes database queries, not just API processing", "nextThoughtNeeded": true, "thoughtNumber": 3, "totalThoughts": 4, "isRevision": true, "revisesThought": 2, "sessionId": "session_1735056789"}}}' | mcp-sequential-thinking -``` - -### Branching Alternative Approaches -```bash -# Create a branch for alternative reasoning -echo '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "What if we optimize the database queries instead of adding caching?", "nextThoughtNeeded": true, "thoughtNumber": 1, "totalThoughts": 3, "branchFromThought": 2, "branchId": "db-optimization", "sessionId": "session_1735056789"}}}' | mcp-sequential-thinking - -# Continue in the branch -echo '{"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "Database optimization would require indexing and query restructuring", "nextThoughtNeeded": false, "thoughtNumber": 2, "totalThoughts": 3, "branchId": "db-optimization", "sessionId": "session_1735056789"}}}' | mcp-sequential-thinking -``` - -### Session Management -```bash -# List all active sessions -echo '{"jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": {"name": "list_sessions", "arguments": {}}}' | mcp-sequential-thinking - -# Get complete history of a session -echo '{"jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": {"name": "get_session_history", "arguments": {"sessionId": "session_1735056789"}}}' | mcp-sequential-thinking - -# Get history of a specific branch -echo '{"jsonrpc": "2.0", "id": 8, "method": "tools/call", "params": {"name": "get_branch_history", "arguments": {"branchId": "db-optimization"}}}' | mcp-sequential-thinking - -# Clear a completed session -echo '{"jsonrpc": "2.0", "id": 9, "method": "tools/call", "params": {"name": "clear_session", "arguments": {"sessionId": "session_1735056789"}}}' | mcp-sequential-thinking -``` - -## Advanced Features - -### Session Persistence -- **Cross-Session Continuity**: Thinking sessions persist across server restarts -- **JSON File Storage**: Sessions stored in human-readable JSON format -- **Automatic Session IDs**: Unique session identifiers generated automatically -- **Thread-Safe Operations**: Concurrent access to sessions handled safely - -### Branch Tracking -- **Alternative Reasoning Paths**: Create branches from any thought in the main sequence -- **Branch Isolation**: Each branch maintains its own thought sequence -- **Branch Relationships**: Track which thought each branch originated from -- **Cross-Branch Navigation**: Access both main session and branch histories - -### Enhanced Output Format -- **Rich Visual Formatting**: Progress bars, emojis, and structured sections -- **Session Context**: Always shows current session ID and branch information -- **Structured JSON Data**: Programmatic access to all thinking data -- **Solution Extraction**: Automatic extraction of solutions from final thoughts - -### Revision Support -- **Thought Revision**: Mark thoughts as revisions of previous thoughts -- **Revision Tracking**: Keep track of which thoughts were revised -- **Context Preservation**: Revisions maintain context of original reasoning -- **Dynamic Estimation**: Adjust total thought count as thinking evolves - -## Use Cases - -### Software Development -- Architecture design decisions -- Technology stack selection -- Performance optimization strategies -- Code review and refactoring plans -- Testing strategy development - -### Product Management -- Feature prioritization -- User story analysis -- Competitive analysis -- Go-to-market strategy -- Product roadmap planning - -### Business Strategy -- Market entry decisions -- Investment evaluations -- Risk assessment -- Process optimization -- Team structure planning - -### Research and Development -- Hypothesis formation -- Experimental design -- Literature review structure -- Data analysis approaches -- Innovation opportunities - -## Performance - -- **Startup Time**: <100ms (with session loading) -- **Memory Usage**: <5MB (scales with session count) -- **Response Time**: <50ms per tool call (excluding thinking time) -- **Persistence**: Efficient JSON serialization for session storage -- **Scalability**: Handles hundreds of concurrent sessions with branch tracking - -## Best Practices - -### Session Management -1. **Plan Thought Sequence**: Estimate total thoughts needed at the start -2. **Use Descriptive Thoughts**: Each thought should be self-contained and clear -3. **Leverage Sessions**: Keep related thoughts in the same session -4. **Clean Up Sessions**: Clear completed sessions to manage memory - -### Branch Strategy -1. **Branch Strategically**: Create branches for major alternative approaches -2. **Name Branches Clearly**: Use descriptive branch IDs like "cost-analysis" or "tech-alternative" -3. **Track Branch Origins**: Note which thought triggered the need for branching -4. **Compare Branches**: Use branch history to compare different reasoning paths - -### Revision Best Practices -1. **Mark Revisions Clearly**: Always use `isRevision: true` when reconsidering -2. **Reference Original**: Specify which thought is being revised -3. **Explain Changes**: Make the revision reasoning explicit -4. **Update Estimates**: Adjust total thoughts if revision changes the scope - -## Data Structures - -### Session Data -```json -{ - "id": "session_1735056789", - "thoughts": [ - { - "number": 1, - "content": "Initial thought content", - "isRevision": false, - "needsMoreThoughts": false - } - ], - "currentThought": 3, - "totalThoughts": 5, - "status": "active", - "createdAt": "2024-12-25T10:30:00Z", - "lastActivity": "2024-12-25T10:35:00Z", - "activeBranches": ["branch-1", "branch-2"] -} -``` - -### Branch Data -```json -{ - "id": "optimization-branch", - "sessionId": "session_1735056789", - "fromThought": 2, - "thoughts": [ - { - "number": 1, - "content": "Alternative approach thought", - "branchFromThought": 2, - "branchId": "optimization-branch" - } - ], - "createdAt": "2024-12-25T10:32:00Z", - "lastActivity": "2024-12-25T10:34:00Z" -} -``` - -## Troubleshooting - -### Common Issues - -1. **Session not persisting** - ```bash - # Ensure session file is specified and writable - mcp-sequential-thinking --session-file /writable/path/sessions.json - - # Check file permissions - ls -la /path/to/sessions.json - ``` - -2. **Missing required parameters** - ```bash - # All these parameters are required for sequentialthinking tool: - echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "My analysis of the problem", "nextThoughtNeeded": true, "thoughtNumber": 1, "totalThoughts": 3}}}' | mcp-sequential-thinking - ``` - -3. **Branch creation without sessionId** - ```bash - # Branches require an existing session - # First create/continue a session, get the sessionId from response - # Then use that sessionId for branch creation - echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "sequentialthinking", "arguments": {"thought": "Alternative approach", "nextThoughtNeeded": true, "thoughtNumber": 1, "totalThoughts": 2, "branchFromThought": 3, "branchId": "alt-approach", "sessionId": "session_123456789"}}}' | mcp-sequential-thinking - ``` - -4. **Session ID not found** - ```bash - # List sessions to find correct ID - echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "list_sessions", "arguments": {}}}' | mcp-sequential-thinking - - # Or check if persistence file exists and is readable - cat /path/to/sessions.json - ``` - -## Contributing - -See the main project README for contribution guidelines. - -## License - -This project is licensed under the same terms as the parent MCP project.
\ No newline at end of file |