# Sequential Thinking MVP Server

A production-ready Model Context Protocol (MCP) server that enables AI assistants to perform structured, step-by-step reasoning through sequential thinking. This server facilitates breaking down complex problems into manageable steps, revising thoughts as understanding deepens, and exploring alternative reasoning paths.

## ✨ Latest Updates (v1.0.0)

**All critical security and architectural issues have been fixed!**

- ✅ **Multi-User Support**: Fixed shared state bug - each user now has isolated sessions
- ✅ **Modern MCP Protocol**: Upgraded to Streamable HTTP transport (MCP 2025-03-26 spec)
- ✅ **Cloudflare Workers**: Fully functional with Durable Objects for persistent state
- ✅ **Comprehensive Validation**: All inputs validated with proper error handling
- ✅ **Security Hardened**: Cryptographically secure session IDs, configurable CORS, rate limiting
- ✅ **Memory Management**: Automatic session cleanup with TTL to prevent memory leaks
- ✅ **Production Ready**: Proper error handling, graceful shutdown, health checks

See [CODE_REVIEW.md](CODE_REVIEW.md) for details on all fixes.

## Features

- **Sequential Thinking**: Step-by-step problem-solving with numbered thoughts
- **Thought Revision**: Ability to revise and refine previous reasoning steps
- **Branching Paths**: Explore multiple alternative reasoning approaches
- **Multi-User Session Management**: Isolated sessions for concurrent users
- **Input Validation**: Comprehensive validation with helpful error messages
- **Rate Limiting**: DoS protection (100 requests per 15 minutes per IP)
- **Security**: Secure session IDs, configurable CORS, proper authentication headers
- **Multiple Deployment Options**:
  - Stdio (for Claude Desktop and local MCP clients)
  - HTTP Server with Streamable HTTP (for remote access)
  - Cloudflare Workers with Durable Objects (for serverless deployment)

## Installation

```bash
npm install
npm run build
```

## Usage

### Option 1: Stdio Mode (Claude Desktop)

Use with Claude Desktop or any MCP-compatible client:

```bash
npm start
```

Or use directly with npx:

```bash
npx sequential-thinking-mvp-server
```

#### Claude Desktop Configuration

Add to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "sequential-thinking": {
      "command": "node",
      "args": ["/path/to/sequential-thinking-mvp-server/dist/index.js"]
    }
  }
}
```

### Option 2: HTTP Server Mode

Start the HTTP server for remote access:

```bash
npm run start:http
```

By default, the server runs on port 3000. Set a custom port:

```bash
PORT=8080 npm run start:http
```

#### Configuration

**Environment Variables:**
- `PORT`: HTTP server port (default: 3000)
- `NODE_ENV`: Environment (development/production)
- `ALLOWED_ORIGINS`: Comma-separated list of allowed CORS origins (default: all in dev, none in prod)

**Example:**
```bash
PORT=8080 NODE_ENV=production ALLOWED_ORIGINS=https://example.com npm run start:http
```

#### Endpoints

- `GET /` or `/info` - Server information
- `GET /health` - Health check with session stats
- `POST /mcp` - MCP Streamable HTTP endpoint

#### Session Management

Send a session ID to maintain state across requests:

**Via Header:**
```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "x-session-id: your-session-id" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{...},"id":1}'
```

**Via Query Parameter:**
```bash
curl -X POST "http://localhost:3000/mcp?sessionId=your-session-id" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{...},"id":1}'
```

#### Features

- **Multi-user support**: Each session ID gets isolated state
- **Rate limiting**: 100 requests per 15 minutes per IP
- **CORS**: Configurable via ALLOWED_ORIGINS environment variable
- **Automatic cleanup**: Sessions expire after 1 hour of inactivity
- **Health monitoring**: `/health` endpoint shows active sessions and uptime

### Option 3: Cloudflare Workers

Deploy to Cloudflare Workers with Durable Objects for serverless, globally distributed deployment with persistent state:

```bash
# Development
npm run dev:workers

# Production deployment
npm run deploy:workers
```

#### Cloudflare Workers Features

- **Persistent State**: Uses Durable Objects for reliable data persistence
- **Global Distribution**: Deployed to Cloudflare's edge network
- **Auto-scaling**: Handles traffic spikes automatically
- **Zero Maintenance**: Fully managed infrastructure

#### REST API Endpoints

- `GET /` or `/info` - Server information
- `GET /health` - Health check
- `POST /think` - Add a thought to the sequence
- `GET /sequence` - Get current thought sequence
- `POST /reset` - Reset session

**Example:**
```bash
curl -X POST https://your-worker.workers.dev/think \
  -H "Content-Type: application/json" \
  -d '{
    "thought": "Analyze the problem requirements",
    "thoughtNumber": 1,
    "totalThoughts": 5,
    "nextThoughtNeeded": true
  }'
```

#### Durable Objects Configuration

The server uses Cloudflare Durable Objects to persist state across requests. Each Durable Object instance maintains its own session data, which survives worker restarts and is replicated for reliability.

See `wrangler.toml` for configuration details.

## Tools

### 1. sequential_thinking

The core tool for step-by-step reasoning.

**Required Parameters:**
- `thought` (string): The current reasoning step
- `nextThoughtNeeded` (boolean): Whether more steps are needed
- `thoughtNumber` (number): Sequential number of this thought
- `totalThoughts` (number): Estimated total thoughts needed

**Optional Parameters:**
- `isRevision` (boolean): Marks this as a revision of a previous thought
- `revisesThought` (number): The thought number being revised
- `branchFromThought` (number): Starting point for alternative reasoning
- `branchId` (string): Identifier for alternative reasoning branch
- `needsMoreThoughts` (boolean): Signal to expand total thought count

**Example:**

```json
{
  "thought": "First, I need to understand the problem requirements",
  "nextThoughtNeeded": true,
  "thoughtNumber": 1,
  "totalThoughts": 5
}
```

### 2. get_thought_sequence

Retrieves the complete sequence of thoughts.

**Optional Parameters:**
- `sessionId` (string): Specific session ID (defaults to current)

### 3. get_thought_branch

Retrieves a specific branch of alternative reasoning.

**Required Parameters:**
- `branchId` (string): The branch identifier

**Optional Parameters:**
- `sessionId` (string): Specific session ID (defaults to current)

### 4. reset_thinking_session

Starts a new thinking session, clearing the current sequence.

### 5. get_session_summary

Gets a summary of the current thinking session.

**Optional Parameters:**
- `sessionId` (string): Specific session ID (defaults to current)

## Use Cases

### Example 1: Basic Sequential Reasoning

```
User: How would I design a scalable chat application?

AI uses sequential_thinking:
Thought 1: "First, identify the core requirements: real-time messaging, user presence, message history"
Thought 2: "Consider the architecture: need WebSocket connections for real-time, database for persistence"
Thought 3: "Evaluate scalability: load balancing, message queuing, database sharding"
Thought 4: "Design the tech stack: Node.js + Socket.io, Redis for pub/sub, PostgreSQL for storage"
Thought 5: "Plan for growth: horizontal scaling, CDN for assets, monitoring and metrics"
```

### Example 2: Thought Revision

```
Thought 1: "Use MySQL for the database"
Thought 2: "Implement real-time features with polling"
Thought 3 (revision of 2): "Actually, WebSockets would be more efficient than polling for real-time updates"
Thought 4 (revision of 1): "PostgreSQL would be better than MySQL for JSON support and advanced features"
```

### Example 3: Alternative Reasoning Branches

```
Main path:
Thought 1: "Consider a monolithic architecture"
Thought 2: "This would be simpler to deploy and maintain"

Branch "microservices":
Thought 1: "Alternatively, use microservices architecture"
Thought 2: "This provides better scalability and team independence"
Thought 3: "Trade-off: increased complexity in deployment and monitoring"
```

## API Examples (Cloudflare Workers / HTTP)

### Add a thought

```bash
curl -X POST https://your-worker.workers.dev/think \
  -H "Content-Type: application/json" \
  -d '{
    "thought": "First, analyze the requirements",
    "nextThoughtNeeded": true,
    "thoughtNumber": 1,
    "totalThoughts": 5
  }'
```

### Get thought sequence

```bash
curl https://your-worker.workers.dev/sequence
```

### Reset session

```bash
curl -X POST https://your-worker.workers.dev/reset
```

## Architecture

```
src/
├── types.ts          # TypeScript type definitions
├── lib.ts            # Core sequential thinking logic
├── index.ts          # Stdio MCP server (Claude Desktop)
├── server-http.ts    # HTTP server with SSE transport
└── worker.ts         # Cloudflare Workers implementation
```

## Development

Watch mode for development:

```bash
npm run dev
```

Build the project:

```bash
npm run build
```

## Benefits of Sequential Thinking

1. **Transparency**: See the AI's reasoning process step-by-step
2. **Quality**: Encourages thorough analysis and consideration
3. **Revision**: Allows the AI to reconsider and improve earlier steps
4. **Exploration**: Supports exploring multiple solution paths
5. **Accountability**: Clear audit trail of the reasoning process

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## Related

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Anthropic MCP Servers](https://github.com/modelcontextprotocol/servers)
- [Chain-of-Thought Prompting](https://arxiv.org/abs/2201.11903)