buildworksai/decision-mcp

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.

🚀 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:

npx decisions-maker

Global Installation (Optional)

npm install -g decisions-maker

Development Setup

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:

decisions-maker

Install from GitHub Packages (private/org registry)

1. Create ~/.npmrc with:

@buildworksai:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

2. Install the scoped package:

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:

{
  "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):

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

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 .

Maintained by BuildWorks.AI

Examples

Example 1: Complete Decision Making

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

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

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

Example 4: Session Management

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

Example 5: Logic Validation

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

API Reference

make_decision

Complete decision-making workflow tool.

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.

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.

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.

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.

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:

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