techgopal/ultrafast-mcp-sequential-thinking repository overview

⁠UltraFast MCP Sequential Thinking

Official Docker image available at techgopal/ultrafast-mcp-sequential-thinking⁠

A high-performance, Rust-based Model Context Protocol (MCP) server and client implementation for sequential thinking, built on the UltraFast MCP framework.

⁠🚀 Overview

UltraFast MCP Sequential Thinking provides a structured approach to problem-solving through dynamic and reflective thinking processes. This implementation offers significant performance advantages over the official TypeScript version while maintaining full compatibility with the MCP 2025-06-18 specification.

⁠✨ Features

⁠Core Capabilities

• Dynamic Problem Breakdown: Break complex problems into manageable steps
• Reflective Thinking: Revise and refine thoughts as understanding deepens
• Branching Logic: Explore alternative paths of reasoning
• Adaptive Planning: Adjust the total number of thoughts dynamically
• Solution Verification: Generate and verify solution hypotheses
• Context Preservation: Maintain thinking context across multiple steps

⁠Enhanced Features

• Progress Tracking: Real-time progress notifications for long thinking sessions
• Cancellation Support: Interrupt thinking processes when needed
• Session Management: Persistent thinking sessions across connections
• Export Capabilities: Export thinking sessions in various formats
• Analytics: Detailed analytics on thinking patterns and efficiency

⁠Quick Start with Docker

⁠1. Use the Official Docker Image

# Pull the latest image from Docker Hub
docker pull techgopal/ultrafast-mcp-sequential-thinking:latest

# Run HTTP server on port 8080
docker run --rm -p 8080:8080 techgopal/ultrafast-mcp-sequential-thinking:latest

# Run with custom configuration
docker run --rm -p 8080:8080 -e MAX_THOUGHTS=200 techgopal/ultrafast-mcp-sequential-thinking:latest

# Run in detached mode
docker run -d --name thinking-server -p 8080:8080 techgopal/ultrafast-mcp-sequential-thinking:latest

⁠2. (Optional) Build the Docker Image Locally

# Build the server image locally (if you want to make changes)
docker build -t sequential-thinking-server .

# Verify the image was created
docker images | grep sequential-thinking-server

⁠3. Connect Client to Docker Server

# Connect to HTTP server running in Docker
cargo run --bin sequential-thinking-client -- --server http://localhost:8080

# Or use curl to test the server
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18"},"id":1}'

⁠Example MCP Inspector Docker Configuration

If you want to use MCP Inspector or other tools to launch the server in a Docker container with advanced options (such as analytics and increased max thoughts), use the following configuration:

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "techgopal/ultrafast-mcp-sequential-thinking:latest",
        "/usr/local/bin/sequential-thinking-server",
        "--transport",
        "stdio",
        "--max-thoughts",
        "200",
        "--enable-analytics"
      ],
      "env": {}
    }
  }
}

This configuration will start the server in a Docker container using STDIO transport, with analytics enabled and a higher max thoughts limit. Adjust the arguments as needed for your use case.

⁠4. Docker Compose (Optional)

# Create docker-compose.yml for easy deployment
cat > docker-compose.yml << EOF
version: '3.8'
services:
  sequential-thinking-server:
    build: .
    ports:
      - "8080:8080"
    environment:
      - MAX_THOUGHTS=100
      - ENABLE_ANALYTICS=true
    restart: unless-stopped
EOF

# Start with Docker Compose
docker-compose up -d

# Stop the service
docker-compose down

⁠🔧 Configuration

⁠MCP Inspector

This project includes an MCP Inspector configuration file (mcp-inspector-config.json) that supports both HTTP and STDIO transport modes.

⁠Using MCP Inspector

1. Start the server (choose one):

   # HTTP transport (recommended for Inspector)
   cargo run --bin sequential-thinking-server -- --transport http --port 8080
   
   # STDIO transport
   cargo run --bin sequential-thinking-server -- --transport stdio
   

   Copy

2. Open MCP Inspector and load the config file:

   • Navigate to the project directory
   • Select mcp-inspector-config.json
   • Choose your preferred transport mode:
     • HTTP: sequential-thinking-server-http (default)
     • STDIO: sequential-thinking-server-stdio

3. Test the tools:

   • sequential_thinking: Main thinking tool for problem-solving
   • export_session: Export sessions in various formats
   • analyze_session: Get analytics and insights
   • merge_sessions: Combine multiple sessions

⁠Config File Structure

The mcp-inspector-config.json includes:

• HTTP Server: http://localhost:8080/mcp
• STDIO Server: Cargo subprocess with stdio transport
• Tool Schemas: Complete input/output schemas for all tools
• Documentation: Detailed descriptions for each tool

⁠Server Configuration

# config.toml
[server]
name = "ultrafast-sequential-thinking"
version = "1.0.0"
transport = "http"
port = 8080

[thinking]
max_thoughts_per_session = 100
max_branches_per_session = 10
session_timeout_seconds = 3600
enable_analytics = true

[export]
formats = ["json", "markdown", "pdf"]
auto_export = false

⁠Client Configuration

# client_config.toml
[client]
server_url = "http://localhost:8080"
timeout_seconds = 30
retry_attempts = 3

[thinking]
auto_save_interval = 60
enable_progress_tracking = true
show_thought_visualization = true

⁠📊 API Reference

⁠Core Types

⁠ThoughtData

pub struct ThoughtData {
    pub thought: String,
    pub thought_number: u32,
    pub total_thoughts: u32,
    pub next_thought_needed: bool,
    pub is_revision: Option<bool>,
    pub revises_thought: Option<u32>,
    pub branch_from_thought: Option<u32>,
    pub branch_id: Option<String>,
    pub needs_more_thoughts: Option<bool>,
}

⁠ThinkingSession

pub struct ThinkingSession {
    pub session_id: String,
    pub title: String,
    pub thoughts: Vec<ThoughtData>,
    pub branches: HashMap<String, Vec<ThoughtData>>,
    pub metadata: SessionMetadata,
}

⁠Server Endpoints

⁠Tools

• sequential_thinking: Main thinking tool (MCP 2025-06-18 compliant)
• export_session: Export thinking session in various formats
• analyze_session: Get analytics and insights from session
• merge_sessions: Merge multiple thinking sessions

⁠Resources

• session_history: Access to thinking session history
• analytics_data: Session analytics and metrics
• export_templates: Export format templates

⁠🧪 Testing

⁠Run Tests

# Run all tests
cargo test

# Run specific test suite
cargo test --test thinking_tests

# Run with coverage
cargo tarpaulin

⁠Integration Tests

# Run integration tests
cargo test --test integration_tests

# Run performance benchmarks
cargo bench

⁠📈 Performance

⁠Benchmarks

• Thought Processing: ~0.1ms per thought (vs 1-5ms in TypeScript)
• Session Creation: ~0.5ms (vs 10-20ms in TypeScript)
• Branch Management: ~0.2ms per branch (vs 2-8ms in TypeScript)
• Export Operations: ~1ms for JSON, ~5ms for Markdown (vs 50-200ms in TypeScript)

⁠Memory Usage

• Per Session: ~2KB base + 100 bytes per thought
• Server Memory: ~10MB base + 1KB per active session
• Client Memory: ~5MB base + 500 bytes per session

⁠🔒 Security

⁠Features

• Input Validation: Comprehensive validation of all inputs
• Session Isolation: Complete isolation between sessions
• Rate Limiting: Built-in rate limiting for API endpoints
• Authentication: Optional OAuth 2.1 support
• Audit Logging: Complete audit trail for all operations

⁠Best Practices

• Validate all user inputs before processing
• Implement proper session cleanup
• Use HTTPS for all HTTP communications
• Regular security audits and updates

⁠🤝 Contributing

⁠Development Setup

# Clone repository
git clone https://github.com/techgopal/ultrafast-mcp-sequential-thinking.git
cd ultrafast-mcp-sequential-thinking

# Install dependencies
cargo build

# Run development server
cargo run --bin sequential-thinking-server -- --dev

# Run tests
cargo test

⁠Code Style

• Follow Rust coding standards
• Use cargo fmt for formatting
• Use cargo clippy for linting
• Write comprehensive tests

⁠Pull Request Process

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Update documentation
6. Submit a pull request

⁠📄 License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠🙏 Acknowledgments

• Model Context Protocol: For the excellent protocol specification
• UltraFast MCP: For the high-performance Rust framework
• Official Sequential Thinking Server: For the original TypeScript implementation

⁠🔄 Changelog

⁠v1.0.0

• Initial release
• Full MCP 2025-06-18 compliance
• High-performance Rust implementation
• Comprehensive testing suite
• Production-ready features

Built with ❤️ using UltraFast MCP