# arben-adm/mcp-sequential-thinking architecture

> Architecture diagram of the GitHub repository arben-adm/mcp-sequential-thinking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arben-adm/mcp-sequential-thinking
- Repository: https://github.com/arben-adm/mcp-sequential-thinking

## Overview

MCP Sequential Thinking is a local MCP server for durable, resumable working notes—not a reasoning generator. A client invokes session tools to create a session, record linked evidence or decisions, read or finalize the notes, and optionally export or import an archive; the server delegates session operations to a SQLite repository. A deprecated legacy-tools branch remains, alongside analysis, migration, and whole-store backup. Relationships reflect the excerpts, SOURCE INDEX references, and README; unsampled implementation details are not inferred.

Main entry points: [`mcp_sequential_thinking/server.py`](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/server.py) (MCP Server), [`mcp_sequential_thinking/sessions.py`](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/sessions.py) (Session Repository), [`mcp_sequential_thinking/legacy.py`](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/legacy.py) (Legacy Adapter), [`mcp_sequential_thinking/analysis.py`](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/analysis.py) (Thought Analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["MCP Interface"]
  node_server["MCP Server<br/>[server.py]"]
  node_session_tools["Session Tools<br/>[session_tools.py]"]
  node_protocol["Protocol Helpers<br/>[protocol.py]"]
  node_response_limits["Response Limits<br/>[response_limits.py]"]
end

subgraph group_sessions["Session Workflows"]
  node_legacy["Legacy Adapter<br/>[legacy.py]"]
  node_sessions_repo["Session Repository<br/>[sessions.py]"]
  node_analysis["Thought Analysis<br/>[analysis.py]"]
  node_models["Thought Models<br/>[models.py]"]
  node_schemas["Result Schemas<br/>[schemas.py]"]
end

subgraph group_persistence["Persistence"]
  node_archive["Session Archives<br/>[session_archive.py]"]
  node_sqlite[("SQLite Store<br/>[sessions.py]")]
  node_storage["Legacy Storage<br/>[storage.py]"]
  node_storage_utils["Storage Utilities<br/>[storage_utils.py]"]
  node_backup["Store Backup<br/>[backup.py]"]
end

subgraph group_support["Analysis and Operations"]
  node_logging["Logging<br/>[logging_conf.py]"]
  node_version["Version<br/>[_version.py]"]
end

node_client(("MCP Client"))

node_client -->|"invokes tools"| node_server
node_server -->|"registers tools"| node_session_tools
node_server -->|"dispatches legacy"| node_legacy
node_server -->|"analyzes thoughts"| node_analysis
node_server -->|"uses helpers"| node_protocol
node_server -->|"limits responses"| node_response_limits
node_server -->|"creates repository"| node_sessions_repo
node_session_tools -->|"calls operations"| node_sessions_repo
node_legacy -->|"adapts legacy data"| node_sessions_repo
node_sessions_repo -->|"reads and writes"| node_sqlite
node_analysis -->|"analyzes records"| node_models
node_analysis -->|"builds results"| node_schemas
node_legacy -->|"checks stages"| node_analysis
node_session_tools -->|"validates inputs"| node_models
node_server -->|"dispatches archives"| node_archive
node_archive -->|"imports and exports"| node_sessions_repo
node_archive -->|"confines export paths"| node_storage
node_storage -->|"uses file helpers"| node_storage_utils
node_legacy -->|"uses legacy storage"| node_storage
node_backup -->|"backs up store"| node_sessions_repo
node_server -->|"configures logging"| node_logging
node_server -->|"reports version"| node_version

click node_server "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/server.py"
click node_session_tools "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/session_tools.py"
click node_protocol "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/protocol.py"
click node_response_limits "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/response_limits.py"
click node_legacy "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/legacy.py"
click node_sessions_repo "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/sessions.py"
click node_analysis "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/analysis.py"
click node_models "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/models.py"
click node_schemas "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/schemas.py"
click node_archive "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/session_archive.py"
click node_sqlite "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/sessions.py"
click node_storage "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/storage.py"
click node_storage_utils "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/storage_utils.py"
click node_backup "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/backup.py"
click node_logging "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/logging_conf.py"
click node_version "https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/_version.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_session_tools,node_protocol,node_response_limits,node_client toneBlue
class node_legacy,node_sessions_repo,node_analysis,node_models,node_schemas toneAmber
class node_archive,node_sqlite,node_storage,node_storage_utils,node_backup toneMint
class node_logging,node_version toneRose
```

## Components

### MCP Interface

- [MCP Server](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/server.py): `mcp_sequential_thinking/server.py`
- [Session Tools](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/session_tools.py): `mcp_sequential_thinking/session_tools.py`
- [Protocol Helpers](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/protocol.py): `mcp_sequential_thinking/protocol.py`
- [Response Limits](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/response_limits.py): `mcp_sequential_thinking/response_limits.py`

### Session Workflows

- [Legacy Adapter](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/legacy.py): `mcp_sequential_thinking/legacy.py`
- [Session Repository](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/sessions.py): `mcp_sequential_thinking/sessions.py`
- [Thought Analysis](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/analysis.py): `mcp_sequential_thinking/analysis.py`
- [Thought Models](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/models.py): `mcp_sequential_thinking/models.py`
- [Result Schemas](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/schemas.py): `mcp_sequential_thinking/schemas.py`

### Persistence

- [Session Archives](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/session_archive.py): `mcp_sequential_thinking/session_archive.py`
- [SQLite Store](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/sessions.py): `mcp_sequential_thinking/sessions.py`
- [Legacy Storage](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/storage.py): `mcp_sequential_thinking/storage.py`
- [Storage Utilities](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/storage_utils.py): `mcp_sequential_thinking/storage_utils.py`
- [Store Backup](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/backup.py): `mcp_sequential_thinking/backup.py`

### Analysis and Operations

- [Logging](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/logging_conf.py): `mcp_sequential_thinking/logging_conf.py`
- [Version](https://github.com/arben-adm/mcp-sequential-thinking/blob/master/mcp_sequential_thinking/_version.py): `mcp_sequential_thinking/_version.py`

### Other components

- **MCP Client**

## Connections

- MCP Client → MCP Server: invokes tools (evidence: `README.md`)
- MCP Server → Session Tools: registers tools (evidence: `mcp_sequential_thinking/server.py`)
- MCP Server → Legacy Adapter: dispatches legacy (evidence: `mcp_sequential_thinking/server.py`)
- MCP Server → Thought Analysis: analyzes thoughts (evidence: `mcp_sequential_thinking/server.py`)
- MCP Server → Protocol Helpers: uses helpers (evidence: `mcp_sequential_thinking/server.py`)
- MCP Server → Response Limits: limits responses (evidence: `mcp_sequential_thinking/server.py`)
- MCP Server → Session Repository: creates repository (evidence: `mcp_sequential_thinking/server.py`)
- Session Tools → Session Repository: calls operations (evidence: `mcp_sequential_thinking/session_tools.py`)
- Legacy Adapter → Session Repository: adapts legacy data (evidence: `mcp_sequential_thinking/legacy.py`)
- Session Repository → SQLite Store: reads and writes (evidence: `mcp_sequential_thinking/sessions.py`)
- Thought Analysis → Thought Models: analyzes records (evidence: `mcp_sequential_thinking/analysis.py`)
- Thought Analysis → Result Schemas: builds results (evidence: `mcp_sequential_thinking/analysis.py`)
- Legacy Adapter → Thought Analysis: checks stages (evidence: `mcp_sequential_thinking/legacy.py`)
- Session Tools → Thought Models: validates inputs (evidence: `mcp_sequential_thinking/session_tools.py`)
- MCP Server → Session Archives: dispatches archives (evidence: `mcp_sequential_thinking/server.py`)
- Session Archives → Session Repository: imports and exports (evidence: `mcp_sequential_thinking/session_archive.py`)
- Session Archives → Legacy Storage: confines export paths (evidence: `mcp_sequential_thinking/session_archive.py`)
- Legacy Storage → Storage Utilities: uses file helpers (evidence: `mcp_sequential_thinking/storage.py`)
- Legacy Adapter → Legacy Storage: uses legacy storage (evidence: `mcp_sequential_thinking/legacy.py`)
- Store Backup → Session Repository: backs up store (evidence: `mcp_sequential_thinking/backup.py`)
- MCP Server → Logging: configures logging (evidence: `mcp_sequential_thinking/server.py`)
- MCP Server → Version: reports version (evidence: `mcp_sequential_thinking/server.py`)
