decisions-maker/README.md

Decisions Maker — sequential thinking, decision-making, and analysis server for MCP-compatible IDEs.

# Decisions Maker

[![npm version](https://badge.fury.io/js/decisions-maker.svg)](https://badge.fury.io/js/decisions-maker)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub Actions](https://github.com/buildworksai/decision-mcp/workflows/Publish/badge.svg)](https://github.com/buildworksai/decision-mcp/actions)
[![CI](https://github.com/buildworksai/decision-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/buildworksai/decision-mcp/actions/workflows/ci.yml)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
[![Downloads](https://img.shields.io/npm/dm/decisions-maker.svg)](https://www.npmjs.com/package/decisions-maker)

Decisions Maker is a production-grade Model Context Protocol (MCP) server providing ultra-optimized decision making and structured thinking capabilities. Features 10 powerful tools for comprehensive decision analysis, prediction, and data processing. Works with Cursor, Windsurf, and Claude via stdio. Distributed via npm and Docker. Built and maintained by [BuildWorks.AI](https://buildworks.ai).

## 🚀 Comprehensive 10-Tool Architecture

**Complete decision-making ecosystem** - 10 powerful tools providing comprehensive decision analysis, prediction, data processing, and visualization capabilities for maximum productivity.

### 🎯 1. `make_decision` - Complete Decision Workflow
**Advanced decision-making capabilities:**
- Create decision sessions with context
- Add multiple criteria with weights and types
- Define options with pros, cons, and risks
- Auto-generate or provide custom evaluations
- Generate comprehensive analysis and recommendations
- **One tool call = Complete decision from start to finish**

### 🔍 2. `analyze_decision` - Deep Analysis Suite
**Comprehensive decision analysis:**
- Bias detection and mitigation strategies
- Logic validation and consistency checking
- Risk assessment with probability and impact analysis
- Alternative generation with feasibility scoring
- Comprehensive analysis combining all insights

### 🧠 3. `structured_thinking` - Complete Thinking Workflow
**Advanced structured thinking capabilities:**
- Start thinking sessions with problems and context
- Add, revise, and branch thoughts dynamically
- Analyze progress and identify key insights
- Conclude with final conclusions and confidence levels

### 📋 4. `manage_sessions` - Universal Session Management
**Universal session management:**
- Get individual sessions (decision or thinking)
- List all sessions with filtering by type and status
- Universal session management across all tool types

### ✅ 5. `validate_logic` - Quick Logic Validation
**Logic validation and consistency checking:**
- Quick logic consistency checking
- Strict or relaxed validation modes
- Perfect for quality assurance workflows

### 🌐 6. `external_data` - Data Fetching & Processing
**External data integration:**
- Fetch data from REST APIs, JSON endpoints, CSV files
- Built-in support for Yahoo Finance, GitHub, and more
- Automatic data validation and error handling
- Configurable timeouts and retry mechanisms

### 📝 7. `nlp` - Natural Language Processing
**Advanced text analysis:**
- Keyword extraction and analysis
- Text summarization and similarity analysis
- Sentiment analysis and entity extraction
- Text classification and language detection

### 📊 8. `visualization` - Data Visualization
**Comprehensive visualization tools:**
- Generate Mermaid diagrams for thinking and decision flows
- Export to JSON, Markdown, and multiple formats
- Multiple themes and customization options
- Support for complex decision trees and thought processes

### 🔮 9. `prediction` - Advanced Prediction & Forecasting
**Powerful prediction capabilities:**
- Time series prediction and forecasting
- Classification and regression analysis
- Trend analysis and correlation detection
- Standard statistical analysis with large dataset support (up to 1M inputs)
- Data quality assessment and insights generation

### 💚 10. `health_status` - System Health Monitoring
**System health and monitoring:**
- Real-time system health status
- Performance metrics and resource usage
- Service availability and error tracking

### ⚡ Performance & Reliability
- **In-Memory Storage**: Fast, efficient session management
- **Performance Monitoring**: Built-in performance metrics and monitoring
- **Rate Limiting**: Configurable rate limits to prevent abuse
- **Session Management**: Automatic cleanup of old sessions

### 🔒 Security & Validation
- **Input Validation**: Comprehensive input sanitization and validation
- **Security Auditing**: Complete audit trail of all actions
- **Session Security**: Secure session management with lifetime limits
- **Error Handling**: Robust error handling and recovery

## Installation

### Quick Start (Recommended)
No installation required! Use `npx` to run the latest version:

```bash
npx decisions-maker
```

### Global Installation (Optional)
```bash
npm install -g decisions-maker
```

### Development Setup
```bash
git clone https://github.com/buildworksai/decision-mcp.git
cd decision-mcp
npm install
npm run build
npm start
```

## Usage

### Starting the MCP Server

The server runs on stdio and can be integrated with MCP-compatible AI assistants:

```bash
decisions-maker
```

### Install from GitHub Packages (private/org registry)

1) Create `~/.npmrc` with:
```ini
@buildworksai:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
```

2) Install the scoped package:
```bash
npm install -g @buildworksai/decision-mcp
```

## Technical Architecture

### 🏗️ Core Components
- **MCP Server**: Standard Model Context Protocol server with stdio transport
- **Environment Config Manager**: zod-validated env with safe defaults (log level/dir, rate limits)
- **Structured Logger**: Winston-based, console in dev, file transports in prod
- **Audit Trail**: Buffered JSONL with periodic flush, query and summary APIs
- **Health Monitor**: Memory/config/performance checks and metrics snapshot
- **Security Layer**: Input validation, sanitization, SQLi/XSS/command detection
- **Rate Limiting**: Configurable global/session/analysis limits from env
- **RBAC & Tenant Isolation**: Guard hooks at tool boundaries
- **Performance Monitoring**: Built-in metrics and performance tracking

### 📊 Data Flow
1. **Input Validation**: All inputs are validated and sanitized
2. **RBAC & Tenant Checks**: Requests are authorized and isolated
3. **Rate Limiting**: Requests are checked against configured limits
4. **Processing**: Core decision-making logic executes (wrapped by a standard pipeline)
5. **Audit**: Success/failure recorded to JSONL with duration and context
6. **Observability**: Health status and metrics available for diagnostics

## Configure in IDE (Cursor/Windsurf/Claude)

Add to your MCP settings:
```json
{
  "mcpServers": {
    "decisions-maker": {
      "command": "npx",
      "args": ["decisions-maker"],
      "env": {},
      "disabled": false
    }
  }
}
```

**Note**: Using `npx` ensures you always get the latest version and avoids global installation issues.

## v3 Additions

### Health Tool
- New MCP tool: `health_status`
- Returns overall status (`healthy|degraded|unhealthy`), checks, and metrics (memory/performance/config).

Example call (conceptual):

```json
{
  "name": "health_status",
  "arguments": {}
}
```

### Environment Variables
- `DECISION_LOG_LEVEL` (debug|info|warn|error, default: info)
- `DECISION_LOG_DIR` (default: ./logs, resolved to absolute)
- `DECISION_RATE_WINDOW_MS` (default: 60000)
- `DECISION_RATE_MAX_REQUESTS` (default: 100)

### RBAC and Tenant Isolation
- RBAC check is performed before tool execution using `request.meta.userId`, `request.meta.tenantId`, and `request.meta.roles` when available.
- Add roles in your IDE integration if you need fine-grained control.

### Audit Trail
- Buffered JSONL stored under `<logDir>/audit/audit-YYYY-MM-DD.jsonl`.
- Query and summary APIs available internally; health and pipeline audits on every call.

### Stress Test
- Run a lightweight stress test to gauge average and p95 latencies:

```bash
node ./scripts/stress-test.js # after build, or tsx scripts/stress-test.ts in dev
# Optional overrides
STRESS_REQUESTS=500 STRESS_CONCURRENCY=50 node ./scripts/stress-test.js
```

## License

Licensed under the MIT License. See [LICENSE](./LICENSE).

---

Maintained by [BuildWorks.AI](https://buildworks.ai)

## Examples

### Example 1: Complete Decision Making

```json
{
  "tool": "make_decision",
  "arguments": {
    "context": "Choose between three software vendors for our new CRM system",
    "criteria": [
      {
        "name": "Cost",
        "description": "Total cost of ownership",
        "weight": 0.3,
        "type": "cost"
      },
      {
        "name": "Features",
        "description": "Feature completeness and quality",
        "weight": 0.4,
        "type": "benefit"
      },
      {
        "name": "Support",
        "description": "Quality of customer support",
        "weight": 0.3,
        "type": "benefit"
      }
    ],
    "options": [
      {
        "name": "Vendor A",
        "description": "Enterprise-focused solution",
        "pros": ["Comprehensive features", "24/7 support"],
        "cons": ["Higher cost", "Complex setup"],
        "risks": ["Vendor lock-in", "Long implementation"],
        "estimatedCost": 50000,
        "estimatedTime": "6 months"
      },
      {
        "name": "Vendor B",
        "description": "Mid-market solution",
        "pros": ["Good balance", "Easy integration"],
        "cons": ["Limited customization", "Basic reporting"],
        "risks": ["Scalability concerns"],
        "estimatedCost": 30000,
        "estimatedTime": "4 months"
      }
    ]
  }
}
```

### Example 2: Structured Thinking

```json
{
  "tool": "structured_thinking",
  "arguments": {
    "problem": "How can we improve customer satisfaction in our e-commerce platform?",
    "context": "We've seen a 15% drop in customer satisfaction scores over the past quarter",
    "action": "start"
  }
}
```

### Example 3: Decision Analysis

```json
{
  "tool": "analyze_decision",
  "arguments": {
    "sessionId": "decision-session-123",
    "includeBias": true,
    "includeLogic": true,
    "includeRisks": true,
    "includeAlternatives": true,
    "maxAlternatives": 3
  }
}
```

### Example 4: Session Management

```json
{
  "tool": "manage_sessions",
  "arguments": {
    "action": "list",
    "type": "all",
    "status": "active"
  }
}
```

### Example 5: Logic Validation

```json
{
  "tool": "validate_logic",
  "arguments": {
    "sessionId": "decision-session-123",
    "strictMode": false
  }
}
```

## API Reference

### make_decision
Complete decision-making workflow tool.

```typescript
interface MakeDecisionParams {
  context: string;
  criteria?: Array<{
    name: string;
    description: string;
    weight: number; // 0-1
    type: 'benefit' | 'cost' | 'risk' | 'feasibility';
  }>;
  options?: Array<{
    name: string;
    description: string;
    pros: string[];
    cons: string[];
    risks: string[];
    estimatedCost?: number;
    estimatedTime?: string;
  }>;
  evaluations?: Array<{
    optionId: string;
    scores: Array<{
      criteriaId: string;
      score: number; // 0-10
      reasoning: string;
    }>;
  }>;
  minConfidence?: number; // 0-1, default: 0.3
}
```

### analyze_decision
Comprehensive decision analysis tool.

```typescript
interface AnalyzeDecisionParams {
  sessionId: string;
  includeBias?: boolean; // default: true
  includeLogic?: boolean; // default: true
  includeRisks?: boolean; // default: true
  includeAlternatives?: boolean; // default: true
  maxAlternatives?: number; // default: 3
}
```

### structured_thinking
Complete structured thinking workflow tool.

```typescript
interface StructuredThinkingParams {
  problem: string;
  context?: string;
  action?: 'start' | 'add_thought' | 'revise_thought' | 'branch' | 'analyze' | 'conclude';
  sessionId?: string; // required for non-start actions
  thought?: string; // for add_thought
  thoughtId?: string; // for revise_thought/branch
  newThought?: string; // for revise_thought
  newDirection?: string; // for branch
  conclusion?: string; // for conclude
  maxThoughts?: number; // default: 50
}
```

### manage_sessions
Universal session management tool.

```typescript
interface ManageSessionsParams {
  action: 'get' | 'list' | 'delete';
  sessionId?: string; // required for get/delete
  type?: 'decision' | 'thinking' | 'all'; // default: all
  status?: 'active' | 'completed' | 'archived' | 'all'; // default: all
}
```

### validate_logic
Quick logic validation tool.

```typescript
interface ValidateLogicParams {
  sessionId: string;
  strictMode?: boolean; // default: false
}
```

## Error Handling

The server provides comprehensive error handling:

- **Validation Errors**: Input validation with detailed error messages
- **Session Errors**: Session not found or invalid state
- **Analysis Errors**: Insufficient data for analysis
- **System Errors**: Internal server errors with logging

## Performance Considerations

- **Memory Management**: Sessions are stored in memory for fast access
- **Concurrent Sessions**: Supports multiple simultaneous sessions
- **Analysis Performance**: Optimized algorithms for real-time analysis
- **Validation Speed**: Fast input validation with early returns

## Security

- **Input Sanitization**: All inputs are validated and sanitized
- **Session Isolation**: Sessions are isolated and cannot access each other
- **Error Information**: Sensitive information is not exposed in error messages
- **Resource Limits**: Built-in limits to prevent resource exhaustion

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## Support

For issues and questions:
- Create an issue on GitHub
- Check the documentation
- Review the examples

## Changelog

### v3.0.2 (2025-10-06) - Repository URL Fixes & Version Consistency

#### 🔧 Bug Fixes
- Fixed incorrect repository URLs in README, package.json, and Dockerfile
- Updated all GitHub repository references from decisions-maker to decision-mcp
- Corrected package.json repository, homepage, and bugs URLs
- Updated Dockerfile image source and documentation URLs

#### 📦 Version & Packaging
- Bumped version to 3.0.2 across codebase (server banner, health, Docker label, README)
- All URLs now correctly point to the actual repository name

### v3.0.0 (2025-10-06) - Architecture Hardening & Observability

#### ✨ New
- **Environment Config Manager** (zod): Validated env with safe defaults; absolute log dir resolution.
- **Structured Logger** (winston): Console in dev; file transports in prod.
- **Audit Trail**: Buffered JSONL with async flush and env-controlled console mirroring (`DECISION_AUDIT_MIRROR=false`).
- **Health Tool**: `health_status` returns status, checks, and metrics (memory/performance/config).
- **RBAC & Tenant Isolation**: Guard hooks applied at tool boundaries using `request.meta` (userId, tenantId, roles).
- **Standard Pipeline**: Rate-limit → execute → audit success/failure with duration.

#### 🔒 Security & Validation
- Extended sanitization and detection for SQLi/XSS/command injection.
- Path traversal checks and max-length validations.

#### ⚙️ Reliability & Limits
- Rate limiting sourced from env (global/session/analysis scopes).
- Typed errors and `withRetry` backoff for network/storage/timeouts.

#### 🧪 Testing & Tooling
- Added unit tests: config manager, validation/security, error handler, audit trail, health monitor.
- Added stress test script with clean shutdown and concurrency controls.

#### 📦 Version & Packaging
- Bumped version to 3.0.0 across codebase (server banner, health, Docker label, README).
- No breaking changes to tool names or inputs.

#### 📘 Upgrade Notes
- Optional envs: `DECISION_LOG_LEVEL`, `DECISION_LOG_DIR`, `DECISION_RATE_WINDOW_MS`, `DECISION_RATE_MAX_REQUESTS`, `DECISION_AUDIT_MIRROR`.
- Existing MCP configurations continue working without changes.

## CI & Quality Gates

The CI workflow runs on PRs and main:
- Lint, Build, Unit Tests
- Smoke: start stdio server for 2 seconds and exit
- Quick Stress: 100 requests @ 20 concurrency to verify audit/health

## RBAC Meta Requirements (MCP Clients)

For fine-grained authorization, include `meta` in tool requests:
- `meta.userId`: string (required for non-public operations)
- `meta.tenantId`: string (for multi-tenant isolation)
- `meta.roles`: array of roles (`admin` | `editor` | `viewer`)

If `meta` is omitted, the server treats the request as minimal access (viewer) and may deny actions requiring higher roles. Ensure your MCP integration populates these fields.

## Docker Logging Guidance

- The server writes JSONL audits under `<logDir>/audit` and may add file transports in production.
- In containers, mount a writable log volume and/or set a log dir env:

```bash
# Example
mkdir -p /var/log/decisions-maker
docker run \
  -e DECISION_LOG_LEVEL=info \
  -e DECISION_LOG_DIR=/var/log/decisions-maker \
  -v /host/logs/decisions-maker:/var/log/decisions-maker \
  buildworks-ai/decisions-maker:latest
```

The health endpoint reports `logging` as warn if the directory is missing; logging will automatically degrade to console-only.