Sequential Thinking

Um servidor que facilita o pensamento estruturado e progressivo por meio de etapas definidas.

Documentação

Servidor MCP de Pensamento Sequencial

Um servidor Model Context Protocol (MCP) que fornece um diário de pensamento estruturado: pensamentos validados por esquema, trilha de auditoria somente de acréscimo, análise estrutural e exportação/importação de sessão. Ele registra e organiza um processo de pensamento por meio de etapas definidas — não avalia, gera ou melhora o raciocínio em si; isso permanece com o modelo que o está chamando.

Recursos

Estrutura de Pensamento Estruturado: Organiza pensamentos por meio de etapas cognitivas padrão (Definição do Problema, Pesquisa, Análise, Síntese, Conclusão), com avisos (ou, no modo --strict-stages, rejeição) quando um pensamento pula ou retrocede uma etapa
Revisões e Ramificações: Revise pensamentos anteriores ou bifurque linhas alternativas de raciocínio, com análise e resumos cientes de revisão e ramificação
Rastreamento de Pensamentos: Registra e gerencia pensamentos sequenciais com metadados como uma trilha de auditoria estruturada e tipada (structured_content em cada resposta de ferramenta)
Análise de Pensamentos Relacionados: Encontra pensamentos lexicalmente semelhantes ao atual, independentemente da etapa, além de um agrupamento separado por mesma tag/mesma etapa — um sinal categórico, não uma afirmação de relevância semântica
Monitoramento de Progresso: Posição explícita na linha principal, total de pensamentos registrados, contagem de ramificações e contagem de revisões — não uma única porcentagem ambígua
Geração de Resumos: Extrai o pensamento real registrado (trechos por etapa, suposições desafiadas agregadas, ramificações abertas, cadeias de revisão) juntamente com estatísticas estruturais — uma extração determinística, não um novo raciocínio
Armazenamento Persistente: Log de sessão JSONL somente de acréscimo com segurança de thread e recuperação automática de falhas
Importação/Exportação de Dados: Compartilhe e reutilize sessões de pensamento
Arquitetura Extensível: Personalize e estenda facilmente a funcionalidade
Tratamento Robusto de Erros: Erros de protocolo/validação (etapa inválida, número de pensamento duplicado, travessia de caminho) falham a chamada imediatamente; erros de execução aos quais o chamador pode se adaptar retornam como resultado normal de ferramenta
Segurança de Tipos: Anotações de tipo abrangentes (mypy --strict limpo) e validação Pydantic, incluindo esquemas de saída declarados para cada ferramenta

Pré-requisitos

Python 3.10 ou superior
Gerenciador de pacotes UV (Guia de Instalação)

Tecnologias-chave

Pydantic: Para validação de dados, serialização e esquemas de saída de ferramentas estruturadas
Portalocker: Para acesso a arquivos com segurança de thread
MCP Python SDK 2.x (mcp.server.mcpserver.MCPServer): Para integração com Model Context Protocol

Estrutura do Projeto

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_storage.py  # Tests for persistence layer
│   └── __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

Início Rápido

O pacote está publicado no PyPI como mcp-sequential-thinking. A maneira mais fácil de executá-lo é via uvx — sem necessidade de etapa de instalação:

uvx mcp-sequential-thinking

Ou instale-o permanentemente:

pip install mcp-sequential-thinking
mcp-sequential-thinking

Configuração de Desenvolvimento

Para trabalhar no código, clone o repositório e configure-o a partir da fonte:

Configurar o Projeto

# 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 pip install -e ".[dev]"

# For all optional dependencies
uv pip install -e ".[all]"

Executar o Servidor

# Run directly
uv run -m mcp_sequential_thinking.server

# Or use the installed script
mcp-sequential-thinking

Executar Testes

# Run all tests
pytest

# Run with coverage report
pytest --cov=mcp_sequential_thinking

Integração com Claude Desktop

Adicione à sua configuração do Claude Desktop:

Linux: ~/.config/Claude/claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Opção 1: Usando uvx com o pacote PyPI (recomendado)

Sem clone, sem venv, sem atualizações manuais — o uvx busca o pacote do PyPI e o executa:

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "uvx",
      "args": ["mcp-sequential-thinking"]
    }
  }
}

Para testar alterações não lançadas, aponte o uvx para o repositório:

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/arben-adm/mcp-sequential-thinking",
        "mcp-sequential-thinking"
      ]
    }
  }
}

Opção 2: Usando o ponto de entrada instalado

Se você instalou o pacote com pip install mcp-sequential-thinking (ou pip install -e . de um clone):

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "mcp-sequential-thinking"
    }
  }
}

Opção 3: Usando o ambiente virtual de um clone local (desenvolvimento)

Se você configurou o projeto com uv venv && uv pip install -e ., aponte diretamente para o interpretador Python do venv. Isso evita problemas de resolução de dependências (por exemplo, em sistemas com Python 3.14+):

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "/path/to/mcp-sequential-thinking/.venv/bin/python",
      "args": [
        "-m",
        "mcp_sequential_thinking.server"
      ],
      "cwd": "/path/to/mcp-sequential-thinking"
    }
  }
}

Opção 4: Usando uv run em um clone local (desenvolvimento)

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mcp-sequential-thinking",
        "-m",
        "mcp_sequential_thinking.server"
      ]
    }
  }
}

Integração com Editores e IDEs

Cursor

Adicione à sua configuração MCP do Cursor em .cursor/mcp.json na raiz do seu projeto (ou globalmente em ~/.cursor/mcp.json):

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "uvx",
      "args": ["mcp-sequential-thinking"]
    }
  }
}

VS Code (Copilot MCP)

O VS Code suporta servidores MCP desde a versão 1.99+. Adicione a .vscode/mcp.json no seu workspace ou ao seu usuário settings.json:

{
  "servers": {
    "sequential-thinking": {
      "command": "uvx",
      "args": ["mcp-sequential-thinking"]
    }
  }
}

Nota: Habilite o suporte MCP no VS Code via "chat.mcp.enabled": true nas suas configurações.

Zed

Adicione às suas configurações do Zed (~/.config/zed/settings.json):

{
  "context_servers": {
    "sequential-thinking": {
      "command": {
        "path": "uvx",
        "args": ["mcp-sequential-thinking"]
      }
    }
  }
}

Claude Code (CLI)

Adicione o servidor usando a CLI:

claude mcp add sequential-thinking -- uvx mcp-sequential-thinking

Ou crie/edite manualmente .mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "uvx",
      "args": ["mcp-sequential-thinking"]
    }
  }
}

Windsurf

Adicione à sua configuração MCP do Windsurf em ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "uvx",
      "args": ["mcp-sequential-thinking"]
    }
  }
}

Gemini CLI

Adicione às suas configurações do Gemini CLI em ~/.gemini/settings.json:

{
  "mcpServers": {
    "sequential-thinking": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-sequential-thinking"],
      "env": {}
    }
  }
}

Dica: Todas as configurações de editores acima executam o pacote PyPI publicado via uvx. Para executar a partir de um clone local (por exemplo, para desenvolvimento), use uv run --directory /path/to/mcp-sequential-thinking -m mcp_sequential_thinking.server ou aponte diretamente para o interpretador Python do venv (veja Opções 3 e 4 do Claude Desktop).

Como Funciona

O servidor mantém um histórico de pensamentos e os processa por meio de um fluxo de trabalho estruturado. Cada pensamento é validado usando modelos Pydantic, categorizado em etapas de pensamento e armazenado com metadados relevantes em um sistema de armazenamento com segurança de thread. O servidor lida automaticamente com persistência de dados, criação de backups e fornece ferramentas para analisar relações entre pensamentos.

As sessões são persistidas como um log JSONL somente de acréscimo em ~/.mcp_sequential_thinking/current_session.jsonl (substitua o diretório com a variável de ambiente MCP_STORAGE_DIR). Cada chamada de process_thought acrescenta uma única linha com fsync, então o arquivo serve como trilha de auditoria e uma linha final truncada de uma gravação interrompida é recuperada automaticamente. Sessões da v0.5.x (current_session.json) são migradas sem perda na primeira inicialização; o arquivo original é mantido como current_session.json.migrated-to-v2.

Guia de Uso

O servidor de Pensamento Sequencial expõe cinco ferramentas principais:

1. `process_thought`

Registra e analisa um novo pensamento no seu processo de pensamento sequencial.

Parâmetros:

thought (string): O conteúdo do seu pensamento
thought_number (inteiro): Posição na sua sequência (por exemplo, 1 para o primeiro pensamento)
total_thoughts (inteiro): Total esperado de pensamentos na sequência
next_thought_needed (booleano): Se mais pensamentos são necessários após este
stage (string): A etapa do pensamento — deve ser uma de:
- "Definição do Problema"
- "Pesquisa"
- "Análise"
- "Síntese"
- "Conclusão"
tags (lista de strings, opcional): Palavras-chave ou categorias para o seu pensamento
axioms_used (lista de strings, opcional): Princípios ou axiomas aplicados no seu pensamento
assumptions_challenged (lista de strings, opcional): Suposições que seu pensamento questiona ou desafia
is_revision (booleano, opcional): Se este pensamento revisa um anterior
revises_thought_number (inteiro, opcional): O número do pensamento anterior sendo revisado (obrigatório junto com is_revision)
branch_from_thought (inteiro, opcional): O número do pensamento para bifurcar ao explorar um caminho alternativo
branch_id (string, opcional): Identificador para a ramificação (letras, dígitos, -, _; máximo 64 caracteres; requer branch_from_thought)

Exemplo:

# 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"],
)

# Revise an earlier thought
process_thought(
    thought="Framing the problem purely around emissions was too narrow; adaptation matters equally.",
    thought_number=6,
    total_thoughts=6,
    next_thought_needed=True,
    stage="Problem Definition",
    is_revision=True,
    revises_thought_number=1,
)

# Fork an alternative line of reasoning
process_thought(
    thought="What if we approach this from a market-incentive angle instead?",
    thought_number=7,
    total_thoughts=7,
    next_thought_needed=True,
    stage="Analysis",
    branch_from_thought=3,
    branch_id="market-incentives",
)

2. `generate_summary`

Gera um resumo de todo o seu processo de pensamento.

Exemplo de saída:

{
  "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"},
      {"number": 6, "stage": "Problem Definition", "isRevision": true},
      {"number": 7, "stage": "Analysis", "branchId": "market-incentives"}
    ],
    "branches": {
      "market-incentives": {"fromThought": 3, "thoughtCount": 1}
    },
    "revisionCount": 1
  }
}

3. `clear_history`

Redefine o processo de pensamento limpando todos os pensamentos registrados.

4. `export_session`

Exporta a sessão de pensamento atual para um arquivo JSON para compartilhamento ou backup.

Parâmetros:

file_path (string): Caminho para o arquivo JSON de saída. Desde a v0.6.0, as exportações são confinadas ao subdiretório exports/ do diretório de armazenamento; caminhos relativos resolvem para ~/.mcp_sequential_thinking/exports/ e diretórios pai são criados automaticamente.

Exemplo:

export_session(file_path="my-analysis.json")
# -> written to ~/.mcp_sequential_thinking/exports/my-analysis.json

5. `import_session`

Importa uma sessão de pensamento exportada anteriormente de um arquivo JSON. Exportações criadas com v0.5.x permanecem importáveis.

Parâmetros:

file_path (string): Caminho para o arquivo JSON a importar. Como exportações, resolvido dentro do subdiretório exports/ do diretório de armazenamento.

Comparação com o servidor oficial de pensamento sequencial

O servidor MCP oficial de pensamento sequencial fornece o paradigma central: pensamentos numerados com revisões e ramificações, mantidos em memória durante o processo. Este servidor implementa o mesmo paradigma e adiciona:

Persistência: sessões sobrevivem a reinicializações (log JSONL somente de acréscimo com recuperação de falhas e migração automática) e podem ser exportadas, compartilhadas e reimportadas como JSON.
Etapas de pensamento: pensamentos são categorizados em etapas cognitivas (Definição do Problema, Pesquisa, Análise, Síntese, Conclusão), permitindo filtragem por etapa e verificações de completude.
Análise: detecção de pensamentos relacionados via etapas e tags, progresso por pensamento e resumos ricos incluindo estatísticas de ramificação e revisão.

Se você só precisa de um arcabouço efêmero de cadeia de pensamento, o servidor oficial é uma escolha mais leve; se você quer sessões de pensamento duráveis e analisáveis, este foi construído para isso.

Aplicações Práticas

Tomada de Decisão: Trabalhe decisões importantes metodicamente
Resolução de Problemas: Divida problemas complexos em componentes gerenciáveis
Planejamento de Pesquisa: Estruture sua abordagem de pesquisa com etapas claras
Organização de Escrita: Desenvolva ideias progressivamente antes de escrever
Análise de Projetos: Avalie projetos por meio de etapas analíticas definidas

Começando

Com a configuração MCP adequada, simplesmente use a ferramenta process_thought para começar a trabalhar seus pensamentos em sequência. Conforme você avança, pode obter uma visão geral com generate_summary e redefinir quando necessário com clear_history.

Personalizando o Servidor de Pensamento Sequencial

Para exemplos detalhados de como personalizar e estender o servidor de Pensamento Sequencial, veja example.md. Inclui amostras de código para:

Modificar etapas de pensamento
Aprimorar estruturas de dados de pensamento com Pydantic
Adicionar persistência com bancos de dados
Implementar análise aprimorada com PLN
Criar prompts personalizados
Configurar configurações avançadas
Construir integrações de interface web
Implementar ferramentas de visualização
Conectar a serviços externos
Criar ambientes colaborativos
Separar código de teste
Construir utilitários reutilizáveis

Licença

Licença MIT

Sequential Thinking

Documentação

Servidor MCP de Pensamento Sequencial

Recursos

Pré-requisitos

Tecnologias-chave

Estrutura do Projeto

Início Rápido

Configuração de Desenvolvimento

Integração com Claude Desktop

Opção 1: Usando uvx com o pacote PyPI (recomendado)

Opção 2: Usando o ponto de entrada instalado

Opção 3: Usando o ambiente virtual de um clone local (desenvolvimento)

Opção 4: Usando uv run em um clone local (desenvolvimento)

Integração com Editores e IDEs

Cursor

VS Code (Copilot MCP)

Zed

Claude Code (CLI)

Windsurf

Gemini CLI

Como Funciona

Guia de Uso

1. process_thought

2. generate_summary

3. clear_history

4. export_session

5. import_session

Comparação com o servidor oficial de pensamento sequencial

Aplicações Práticas

Começando

Personalizando o Servidor de Pensamento Sequencial

Licença

1. `process_thought`

2. `generate_summary`

3. `clear_history`

4. `export_session`

5. `import_session`