Sequential Thinking

Un servidor que facilita el pensamiento estructurado y progresivo a través de etapas definidas.

Documentación

Servidor MCP de Pensamiento Secuencial

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona un diario de pensamiento estructurado: pensamientos validados por esquema, un registro de auditoría de solo añadido, análisis estructural y exportación/importación de sesiones. Registra y organiza un proceso de pensamiento a través de etapas definidas — no evalúa, genera ni mejora el razonamiento en sí; eso queda en manos del modelo que lo invoque.

Características

Marco de Pensamiento Estructurado: Organiza los pensamientos a través de etapas cognitivas estándar (Definición del Problema, Investigación, Análisis, Síntesis, Conclusión), con advertencias (o, en modo --strict-stages, rechazo) cuando un pensamiento omite o retrocede en una etapa
Revisiones y Ramificaciones: Revisa pensamientos anteriores o bifurca líneas alternativas de razonamiento, con análisis y resúmenes conscientes de revisiones y ramas
Seguimiento de Pensamientos: Registra y gestiona pensamientos secuenciales con metadatos como un registro de auditoría estructurado y tipado (structured_content en cada respuesta de herramienta)
Análisis de Pensamientos Relacionados: Encuentra pensamientos léxicamente similares al actual, independientemente de la etapa, además de una agrupación separada por misma etiqueta/misma etapa — una señal categórica, no una afirmación de relevancia semántica
Monitoreo de Progreso: Posición explícita en la línea principal, total de pensamientos registrados, número de ramas y número de revisiones — no un único porcentaje ambiguo
Generación de Resúmenes: Extrae el pensamiento real registrado (extractos por etapa, suposiciones desafiadas agregadas, ramas abiertas, cadenas de revisión) junto con estadísticas estructurales — una extracción determinista, no un nuevo razonamiento
Almacenamiento Persistente: Registro de sesión JSONL de solo añadido con seguridad de hilos y recuperación automática ante fallos
Importación/Exportación de Datos: Comparte y reutiliza sesiones de pensamiento
Arquitectura Extensible: Personaliza y amplía la funcionalidad fácilmente
Manejo Robusto de Errores: Los errores de protocolo/validación (etapa incorrecta, número de pensamiento duplicado, traversal de ruta) fallan la llamada directamente; los errores de ejecución a los que el llamador puede adaptarse regresan como un resultado de herramienta normal
Seguridad de Tipos: Anotaciones de tipo exhaustivas (mypy --strict limpio) y validación de Pydantic, incluidos esquemas de salida declarados para cada herramienta

Requisitos Previos

Python 3.10 o superior
Gestor de paquetes UV (Guía de instalación)

Tecnologías Clave

Pydantic: Para validación de datos, serialización y esquemas de salida de herramientas estructuradas
Portalocker: Para acceso a archivos seguro entre hilos
SDK de Python MCP 2.x (mcp.server.mcpserver.MCPServer): Para integración con el Protocolo de Contexto de Modelo

Estructura del Proyecto

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

Inicio Rápido

El paquete está publicado en PyPI como mcp-sequential-thinking. La forma más sencilla de ejecutarlo es mediante uvx — sin necesidad de instalación:

uvx mcp-sequential-thinking

O instálalo permanentemente:

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

Configuración de Desarrollo

Para trabajar en el código, clona el repositorio y configúralo desde la fuente:

Configurar el Proyecto

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

Ejecutar el Servidor

# Run directly
uv run -m mcp_sequential_thinking.server

# Or use the installed script
mcp-sequential-thinking

Ejecutar Pruebas

# Run all tests
pytest

# Run with coverage report
pytest --cov=mcp_sequential_thinking

Integración con Claude Desktop

Añade a tu configuración de 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

Opción 1: Usando uvx con el paquete de PyPI (recomendado)

Sin clonar, sin venv, sin actualizaciones manuales — uvx obtiene el paquete de PyPI y lo ejecuta:

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

Para probar cambios no publicados, apunta uvx al repositorio en su lugar:

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

Opción 2: Usando el punto de entrada instalado

Si has instalado el paquete con pip install mcp-sequential-thinking (o pip install -e . desde un clon):

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

Opción 3: Usando el entorno virtual de un clon local (desarrollo)

Si has configurado el proyecto con uv venv && uv pip install -e ., apunta directamente al intérprete de Python del venv. Esto evita problemas de resolución de dependencias (p. ej., en sistemas con 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"
    }
  }
}

Opción 4: Usando uv run en un clon local (desarrollo)

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

Integración con Editores e IDEs

Cursor

Añade a tu configuración de MCP de Cursor en .cursor/mcp.json en la raíz de tu proyecto (o globalmente en ~/.cursor/mcp.json):

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

VS Code (Copilot MCP)

VS Code admite servidores MCP desde la versión 1.99+. Añade a .vscode/mcp.json en tu espacio de trabajo o a tu settings.json de usuario:

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

Nota: Habilita el soporte de MCP en VS Code mediante "chat.mcp.enabled": true en tu configuración.

Zed

Añade a tu configuración de Zed (~/.config/zed/settings.json):

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

Claude Code (CLI)

Añade el servidor usando la CLI:

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

O crea/edita manualmente .mcp.json en la raíz de tu proyecto:

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

Windsurf

Añade a tu configuración de MCP de Windsurf en ~/.codeium/windsurf/mcp_config.json:

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

CLI de Gemini

Añade a tu configuración de CLI de Gemini en ~/.gemini/settings.json:

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

Consejo: Todas las configuraciones de editores anteriores ejecutan el paquete publicado de PyPI mediante uvx. Para ejecutar desde un clon local en su lugar (p. ej., para desarrollo), usa uv run --directory /path/to/mcp-sequential-thinking -m mcp_sequential_thinking.server o apunta directamente al intérprete de Python del venv (consulta Opciones 3 y 4 de Claude Desktop).

Cómo Funciona

El servidor mantiene un historial de pensamientos y los procesa mediante un flujo de trabajo estructurado. Cada pensamiento se valida con modelos de Pydantic, se categoriza en etapas de pensamiento y se almacena con metadatos relevantes en un sistema de almacenamiento seguro entre hilos. El servidor gestiona automáticamente la persistencia de datos, la creación de copias de seguridad y proporciona herramientas para analizar relaciones entre pensamientos.

Las sesiones se persisten como un registro JSONL de solo añadido en ~/.mcp_sequential_thinking/current_session.jsonl (anula el directorio con la variable de entorno MCP_STORAGE_DIR). Cada llamada a process_thought añade una línea única con fsync, por lo que el archivo sirve como registro de auditoría y una línea final truncada de una escritura interrumpida se recupera automáticamente. Las sesiones de v0.5.x (current_session.json) se migran sin pérdidas en el primer inicio; el archivo original se conserva como current_session.json.migrated-to-v2.

Guía de Uso

El servidor de Pensamiento Secuencial expone cinco herramientas principales:

1. `process_thought`

Registra y analiza un nuevo pensamiento en tu proceso de pensamiento secuencial.

Parámetros:

thought (cadena): El contenido de tu pensamiento
thought_number (entero): Posición en tu secuencia (p. ej., 1 para el primer pensamiento)
total_thoughts (entero): Total esperado de pensamientos en la secuencia
next_thought_needed (booleano): Si se necesitan más pensamientos después de este
stage (cadena): La etapa de pensamiento — debe ser una de:
- "Definición del Problema"
- "Investigación"
- "Análisis"
- "Síntesis"
- "Conclusión"
tags (lista de cadenas, opcional): Palabras clave o categorías para tu pensamiento
axioms_used (lista de cadenas, opcional): Principios o axiomas aplicados en tu pensamiento
assumptions_challenged (lista de cadenas, opcional): Suposiciones que tu pensamiento cuestiona o desafía
is_revision (booleano, opcional): Si este pensamiento revisa uno anterior
revises_thought_number (entero, opcional): El número del pensamiento anterior que se revisa (requerido junto con is_revision)
branch_from_thought (entero, opcional): El número de pensamiento desde el que bifurcar al explorar una ruta alternativa
branch_id (cadena, opcional): Identificador de la rama (letras, dígitos, -, _; máximo 64 caracteres; requiere branch_from_thought)

Ejemplo:

# 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`

Genera un resumen de todo tu proceso de pensamiento.

Ejemplo de salida:

{
  "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`

Reinicia el proceso de pensamiento borrando todos los pensamientos registrados.

4. `export_session`

Exporta la sesión de pensamiento actual a un archivo JSON para compartir o hacer copias de seguridad.

Parámetros:

file_path (cadena): Ruta al archivo JSON de salida. Desde v0.6.0, las exportaciones se limitan al subdirectorio exports/ del directorio de almacenamiento; las rutas relativas se resuelven en ~/.mcp_sequential_thinking/exports/ y los directorios padre se crean automáticamente.

Ejemplo:

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

5. `import_session`

Importa una sesión de pensamiento exportada previamente desde un archivo JSON. Las exportaciones creadas con v0.5.x siguen siendo importables.

Parámetros:

file_path (cadena): Ruta al archivo JSON a importar. Al igual que las exportaciones, se resuelve dentro del subdirectorio exports/ del directorio de almacenamiento.

Comparación con el servidor oficial de pensamiento secuencial

El servidor oficial de MCP de pensamiento secuencial proporciona el paradigma central: pensamientos numerados con revisiones y ramificaciones, mantenidos en memoria durante la duración del proceso. Este servidor implementa el mismo paradigma y añade:

Persistencia: las sesiones sobreviven a reinicios (registro JSONL de solo añadido con recuperación ante fallos y migración automática), y se pueden exportar, compartir y reimportar como JSON.
Etapas de pensamiento: los pensamientos se categorizan en etapas cognitivas (Definición del Problema, Investigación, Análisis, Síntesis, Conclusión), lo que permite filtrado por etapa y comprobaciones de completitud.
Análisis: detección de pensamientos relacionados mediante etapas y etiquetas, progreso por pensamiento y resúmenes enriquecidos que incluyen estadísticas de ramas y revisiones.

Si solo necesitas un andamiaje efímero de cadena de pensamiento, el servidor oficial es una opción más ligera; si quieres sesiones de pensamiento duraderas y analizables, este está construido para eso.

Aplicaciones Prácticas

Toma de Decisiones: Trabaja decisiones importantes de manera metódica
Resolución de Problemas: Divide problemas complejos en componentes manejables
Planificación de Investigación: Estructura tu enfoque de investigación con etapas claras
Organización de Escritura: Desarrolla ideas progresivamente antes de escribir
Análisis de Proyectos: Evalúa proyectos a través de etapas analíticas definidas

Cómo Empezar

Con la configuración de MCP adecuada, simplemente usa la herramienta process_thought para comenzar a trabajar con tus pensamientos en secuencia. A medida que avanzas, puedes obtener una visión general con generate_summary y reiniciar cuando sea necesario con clear_history.

Personalización del Servidor de Pensamiento Secuencial

Para ejemplos detallados de cómo personalizar y ampliar el servidor de Pensamiento Secuencial, consulta example.md. Incluye ejemplos de código para:

Modificar etapas de pensamiento
Mejorar estructuras de datos de pensamiento con Pydantic
Añadir persistencia con bases de datos
Implementar análisis mejorado con PLN
Crear indicaciones personalizadas
Configurar configuraciones avanzadas
Construir integraciones de interfaz web
Implementar herramientas de visualización
Conectar a servicios externos
Crear entornos colaborativos
Separar código de pruebas
Construir utilidades reutilizables

Licencia

Licencia MIT

Sequential Thinking

Documentación

Servidor MCP de Pensamiento Secuencial

Características

Requisitos Previos

Tecnologías Clave

Estructura del Proyecto

Inicio Rápido

Configuración de Desarrollo

Integración con Claude Desktop

Opción 1: Usando uvx con el paquete de PyPI (recomendado)

Opción 2: Usando el punto de entrada instalado

Opción 3: Usando el entorno virtual de un clon local (desarrollo)

Opción 4: Usando uv run en un clon local (desarrollo)

Integración con Editores e IDEs

Cursor

VS Code (Copilot MCP)

Zed

Claude Code (CLI)

Windsurf

CLI de Gemini

Cómo Funciona

Guía de Uso

1. process_thought

2. generate_summary

3. clear_history

4. export_session

5. import_session

Comparación con el servidor oficial de pensamiento secuencial

Aplicaciones Prácticas

Cómo Empezar

Personalización del Servidor de Pensamiento Secuencial

Licencia

1. `process_thought`

2. `generate_summary`

3. `clear_history`

4. `export_session`

5. `import_session`