Visum Thinker MCP Server

A Model Context Protocol (MCP) server that provides PTV Visum automation and sequential thinking capabilities for transportation planning and analysis.

🎯 Quick Start

New to Visum automation? → Start here: QUICKSTART_PRT_WORKFLOW.md

AI Assistant integration? → Read: CLAUDE_WORKFLOW_GUIDE.md

Full Documentation? → See: DOCUMENTATION_INDEX.md

✨ New Features (2025-10-10)

🚗 Interactive Visum Procedure Creation with Auto-Organization

Create and configure PTV Visum procedures with automatic organization in "Visum-BOT" group:

// 1. Create procedure → Automatic group creation + delete operation
visum_create_procedure({procedureType: "PrT_Assignment"})
// → Returns: 
//   - group_position: 577 (Visum-BOT group)
//   - delete_position: 580 (Initialize Assignment)
//   - actual_position: 581 (PrT Assignment) ⭐ Use this!

// 2. List available demand segments (numbered 1-36)
visum_list_demand_segments()

// 3. Configure with user's choice
visum_configure_dsegset({
  procedurePosition: 581,        // Use actual_position!
  segmentNumbers: "1-10"         // or filterMode: "C", etc.
})

✨ Automatic Features:

📦 Group Organization: All MCP operations in "Visum-BOT" group
🗑️ Auto-Delete: Initialize Assignment added before PrT/PuT assignments
🔄 Group Reuse: Subsequent calls add to existing group
📍 Smart Positioning: Operations added at end of group

📖 Documentation: See VISUM_BOT_GROUP.md for complete details


**Key Features:**
- ✅ **Automatic position detection** - No manual position tracking
- ✅ **Numbered segment selection** - Easy "1-10" notation instead of long codes
- ✅ **4 flexible input formats** - Numbers, mode filter, ALL keyword, or explicit codes
- ✅ **Interactive workflow** - AI assistants guide users through configuration
- ✅ **Complete validation** - Automatic verification of all configurations

**See [QUICKSTART_PRT_WORKFLOW.md](QUICKSTART_PRT_WORKFLOW.md) for the 3-step workflow!**

## Features

### 🚗 Visum Transportation Planning

- **Procedure Management**: Create PrT/PuT Assignment, Demand Models, Matrix Calculations
- **Demand Segments**: List and configure demand segments with numbered selection
- **Interactive Configuration**: Guide users through DSEGSET setup with 4 input formats
- **Smart Position Tracking**: Automatically track actual procedure positions
- **Complete Validation**: Verify all configurations before execution

### 🧠 Sequential Thinking

- **Step-by-step reasoning**: Break down complex problems into sequential thoughts
- **Dynamic revision**: Revise and refine thoughts as understanding deepens  
- **Branching logic**: Branch into alternative reasoning paths
- **Adaptive planning**: Adjust the total number of thoughts dynamically
- **State management**: Maintain thinking context across multiple tool calls
- **Progress tracking**: Monitor completion status and thought progression

### 📄 PDF Analysis

- **PDF Loading**: Load and analyze PDF documents for problem-solving context
- **Content Search**: Find relevant sections in PDFs based on queries and search terms
- **Persistent Storage**: Auto-save state to disk, survive server restarts
- **Knowledge Transfer**: Export/import thinking sessions between servers

## Installation

### Quick Installation

```bash
# Option 1: Install from NPM
npm install -g visum-thinker-mcp-server

# Option 2: Use with npx (no installation)
npx visum-thinker-mcp-server

# Option 3: Clone from GitHub
git clone https://github.com/yourusername/visum-thinker-mcp-server.git
cd visum-thinker-mcp-server
npm install && npm run build

See INSTALLATION.md for detailed setup instructions.

Prerequisites

Node.js 16 or higher
npm or yarn

Usage

With Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "visum-thinker": {
      "command": "node",
      "args": ["/absolute/path/to/sequential_thinking/build/index.js"]
    }
  }
}

With VS Code

The project includes a .vscode/mcp.json configuration file for VS Code MCP integration.

Direct Usage

npm run dev

Tools

`sequential_thinking`

Main tool for step-by-step reasoning process.

Parameters:

thought (string): The current thinking step
nextThoughtNeeded (boolean): Whether another thought step is needed
thoughtNumber (integer): Current thought number
totalThoughts (integer): Estimated total thoughts needed
isRevision (boolean, optional): Whether this revises previous thinking
revisesThought (integer, optional): Which thought is being reconsidered
branchFromThought (integer, optional): Branching point thought number
branchId (string, optional): Branch identifier
needsMoreThoughts (boolean, optional): If more thoughts are needed

`load_pdf`

Load a PDF file to provide context for analysis.

Parameters:

filePath (string): Absolute path to the PDF file

`analyze_pdf_section`

Analyze specific sections of the loaded PDF.

Parameters:

query (string): What to look for or analyze in the PDF
startPage (integer, optional): Starting page number (1-based)
endPage (integer, optional): Ending page number (1-based)
searchTerms (array of strings, optional): Specific terms to search for

`reset_thinking`

Clears the current thinking state to start fresh.

`get_thinking_summary`

Returns a summary of the current thinking session including PDF context if loaded.

`export_knowledge`

Export the current thinking state and PDF knowledge to a file.

Parameters:

exportPath (string): Absolute path where to save the exported knowledge file

`import_knowledge`

Import thinking state and PDF knowledge from an exported file.

Parameters:

importPath (string): Absolute path to the exported knowledge file to import

🚗 Visum Transportation Planning Tools

The server includes comprehensive PTV Visum integration with intelligent path learning:

check_visum: Check Visum availability and learn custom installation paths
load_visum_model: Load transportation models (.ver files)
run_visum_calculation: Execute transportation calculations and analyses
get_network_statistics: Analyze network topology and characteristics
analyze_visum_matrices: Examine demand and flow matrices
export_visum_results: Export analysis results to various formats

Key Features:

🧠 Smart Path Learning: Automatically remembers custom Visum installation paths
🔄 Zero Setup: Works seamlessly after initial path discovery
🎯 Demo Mode: Full testing capability without Visum installation
📊 Complete Analysis: All major transportation planning workflows supported

See VISUM-PATH-LEARNING.md for detailed information about the intelligent path learning system.

🤖 GitHub Copilot Integration

The Sequential Thinking MCP Server includes comprehensive GitHub Copilot integration for enhanced AI-assisted development:

🚀 Quick Start with Copilot

Server Status: Ensure MCP server is running (npm run dev)
Open Copilot Chat: Ctrl+Shift+I in VS Code
Test Integration: Ask @copilot List available MCP tools
Start Solving: @copilot Use sequential thinking to solve [your problem]

🎯 Copilot Capabilities

🧠 Sequential Thinking: AI-guided step-by-step problem solving
📄 PDF Analysis: Intelligent document processing and analysis
🚗 Transportation Planning: Expert Visum integration and workflow automation
🔧 Smart Configuration: Automatic Visum path learning and persistence
💡 Context-Aware Suggestions: Code completion with domain knowledge

💬 Example Copilot Interactions

@copilot Can you use sequential thinking to analyze this transportation network problem?

@copilot Check if Visum is available and help me load a network model

@copilot Use the PDF analysis tools to extract data from this traffic report

@copilot Create a complete workflow for transportation demand analysis

See COPILOT-INTEGRATION.md for comprehensive setup and usage guide.

Development

Project Structure

sequential_thinking/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── .vscode/
│   └── mcp.json         # VS Code MCP configuration
├── .github/
│   └── copilot-instructions.md
├── package.json
├── tsconfig.json
└── README.md

Scripts

npm run build: Compile TypeScript to JavaScript
npm run dev: Build and run the server
npm test: Run tests (placeholder)

Debugging

The server logs to stderr for compatibility with STDIO transport. Use VS Code's debugging features or add console.error statements for debugging.

Architecture

The server maintains a global thinking state that tracks:

All thoughts in the current session
Current progress and estimated completion
Revision and branching relationships
Session completion status

Each tool call updates this state and provides formatted responses that help users follow the thinking process.

License

MIT

Visum Thinker MCP Server

A Model Context Protocol (MCP) server that provides PTV Visum automation and sequential thinking capabilities for transportation planning and analysis.

🎯 Quick Start

New to Visum automation? → Start here: QUICKSTART_PRT_WORKFLOW.md

AI Assistant integration? → Read: CLAUDE_WORKFLOW_GUIDE.md

Full Documentation? → See: DOCUMENTATION_INDEX.md

✨ New Features (2025-10-10)

🚗 Interactive Visum Procedure Creation with Auto-Organization

Create and configure PTV Visum procedures with automatic organization in "Visum-BOT" group:

// 1. Create procedure → Automatic group creation + delete operation
visum_create_procedure({procedureType: "PrT_Assignment"})
// → Returns: 
//   - group_position: 577 (Visum-BOT group)
//   - delete_position: 580 (Initialize Assignment)
//   - actual_position: 581 (PrT Assignment) ⭐ Use this!

// 2. List available demand segments (numbered 1-36)
visum_list_demand_segments()

// 3. Configure with user's choice
visum_configure_dsegset({
  procedurePosition: 581,        // Use actual_position!
  segmentNumbers: "1-10"         // or filterMode: "C", etc.
})

✨ Automatic Features:

📦 Group Organization: All MCP operations in "Visum-BOT" group
🗑️ Auto-Delete: Initialize Assignment added before PrT/PuT assignments
🔄 Group Reuse: Subsequent calls add to existing group
📍 Smart Positioning: Operations added at end of group

📖 Documentation: See VISUM_BOT_GROUP.md for complete details


**Key Features:**
- ✅ **Automatic position detection** - No manual position tracking
- ✅ **Numbered segment selection** - Easy "1-10" notation instead of long codes
- ✅ **4 flexible input formats** - Numbers, mode filter, ALL keyword, or explicit codes
- ✅ **Interactive workflow** - AI assistants guide users through configuration
- ✅ **Complete validation** - Automatic verification of all configurations

**See [QUICKSTART_PRT_WORKFLOW.md](QUICKSTART_PRT_WORKFLOW.md) for the 3-step workflow!**

## Features

### 🚗 Visum Transportation Planning

- **Procedure Management**: Create PrT/PuT Assignment, Demand Models, Matrix Calculations
- **Demand Segments**: List and configure demand segments with numbered selection
- **Interactive Configuration**: Guide users through DSEGSET setup with 4 input formats
- **Smart Position Tracking**: Automatically track actual procedure positions
- **Complete Validation**: Verify all configurations before execution

### 🧠 Sequential Thinking

- **Step-by-step reasoning**: Break down complex problems into sequential thoughts
- **Dynamic revision**: Revise and refine thoughts as understanding deepens  
- **Branching logic**: Branch into alternative reasoning paths
- **Adaptive planning**: Adjust the total number of thoughts dynamically
- **State management**: Maintain thinking context across multiple tool calls
- **Progress tracking**: Monitor completion status and thought progression

### 📄 PDF Analysis

- **PDF Loading**: Load and analyze PDF documents for problem-solving context
- **Content Search**: Find relevant sections in PDFs based on queries and search terms
- **Persistent Storage**: Auto-save state to disk, survive server restarts
- **Knowledge Transfer**: Export/import thinking sessions between servers

## Installation

### Quick Installation

```bash
# Option 1: Install from NPM
npm install -g visum-thinker-mcp-server

# Option 2: Use with npx (no installation)
npx visum-thinker-mcp-server

# Option 3: Clone from GitHub
git clone https://github.com/yourusername/visum-thinker-mcp-server.git
cd visum-thinker-mcp-server
npm install && npm run build

See INSTALLATION.md for detailed setup instructions.

Prerequisites

Node.js 16 or higher
npm or yarn

Usage

With Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "visum-thinker": {
      "command": "node",
      "args": ["/absolute/path/to/sequential_thinking/build/index.js"]
    }
  }
}

With VS Code

The project includes a .vscode/mcp.json configuration file for VS Code MCP integration.

Direct Usage

npm run dev

Tools

`sequential_thinking`

Main tool for step-by-step reasoning process.

Parameters:

thought (string): The current thinking step
nextThoughtNeeded (boolean): Whether another thought step is needed
thoughtNumber (integer): Current thought number
totalThoughts (integer): Estimated total thoughts needed
isRevision (boolean, optional): Whether this revises previous thinking
revisesThought (integer, optional): Which thought is being reconsidered
branchFromThought (integer, optional): Branching point thought number
branchId (string, optional): Branch identifier
needsMoreThoughts (boolean, optional): If more thoughts are needed

`load_pdf`

Load a PDF file to provide context for analysis.

Parameters:

filePath (string): Absolute path to the PDF file

`analyze_pdf_section`

Analyze specific sections of the loaded PDF.

Parameters:

query (string): What to look for or analyze in the PDF
startPage (integer, optional): Starting page number (1-based)
endPage (integer, optional): Ending page number (1-based)
searchTerms (array of strings, optional): Specific terms to search for

`reset_thinking`

Clears the current thinking state to start fresh.

`get_thinking_summary`

Returns a summary of the current thinking session including PDF context if loaded.

`export_knowledge`

Export the current thinking state and PDF knowledge to a file.

Parameters:

exportPath (string): Absolute path where to save the exported knowledge file

`import_knowledge`

Import thinking state and PDF knowledge from an exported file.

Parameters:

importPath (string): Absolute path to the exported knowledge file to import

🚗 Visum Transportation Planning Tools

The server includes comprehensive PTV Visum integration with intelligent path learning:

check_visum: Check Visum availability and learn custom installation paths
load_visum_model: Load transportation models (.ver files)
run_visum_calculation: Execute transportation calculations and analyses
get_network_statistics: Analyze network topology and characteristics
analyze_visum_matrices: Examine demand and flow matrices
export_visum_results: Export analysis results to various formats

Key Features:

🧠 Smart Path Learning: Automatically remembers custom Visum installation paths
🔄 Zero Setup: Works seamlessly after initial path discovery
🎯 Demo Mode: Full testing capability without Visum installation
📊 Complete Analysis: All major transportation planning workflows supported

See VISUM-PATH-LEARNING.md for detailed information about the intelligent path learning system.

🤖 GitHub Copilot Integration

The Sequential Thinking MCP Server includes comprehensive GitHub Copilot integration for enhanced AI-assisted development:

🚀 Quick Start with Copilot

Server Status: Ensure MCP server is running (npm run dev)
Open Copilot Chat: Ctrl+Shift+I in VS Code
Test Integration: Ask @copilot List available MCP tools
Start Solving: @copilot Use sequential thinking to solve [your problem]

🎯 Copilot Capabilities

🧠 Sequential Thinking: AI-guided step-by-step problem solving
📄 PDF Analysis: Intelligent document processing and analysis
🚗 Transportation Planning: Expert Visum integration and workflow automation
🔧 Smart Configuration: Automatic Visum path learning and persistence
💡 Context-Aware Suggestions: Code completion with domain knowledge

💬 Example Copilot Interactions

@copilot Can you use sequential thinking to analyze this transportation network problem?

@copilot Check if Visum is available and help me load a network model

@copilot Use the PDF analysis tools to extract data from this traffic report

@copilot Create a complete workflow for transportation demand analysis

See COPILOT-INTEGRATION.md for comprehensive setup and usage guide.

Development

Project Structure

sequential_thinking/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── .vscode/
│   └── mcp.json         # VS Code MCP configuration
├── .github/
│   └── copilot-instructions.md
├── package.json
├── tsconfig.json
└── README.md

Scripts

npm run build: Compile TypeScript to JavaScript
npm run dev: Build and run the server
npm test: Run tests (placeholder)

Debugging

The server logs to stderr for compatibility with STDIO transport. Use VS Code's debugging features or add console.error statements for debugging.

Architecture

The server maintains a global thinking state that tracks:

All thoughts in the current session
Current progress and estimated completion
Revision and branching relationships
Session completion status

Each tool call updates this state and provides formatted responses that help users follow the thinking process.

License

MIT