amotivv/soulver-mcp-server

🧮 SoulverCore MCP Server

Natural Language Mathematical Expression Evaluation for Claude Desktop

A comprehensive Model Context Protocol (MCP) server that integrates SoulverCore with Claude Desktop, enabling powerful natural language mathematical calculations, unit conversions, date arithmetic, and financial computations.

🤔 What is Soulver?

Soulver is a revolutionary calculator that understands natural language mathematical expressions. Unlike traditional calculators that require precise syntax, Soulver lets you write math the way you think about it:

• Natural Language: Write $25k over 10 years at 7.5% instead of complex formulas
• Context Aware: Understands units, currencies, dates, and percentages automatically
• Human Readable: Results are formatted in a way that makes sense to humans
• Powerful Engine: Handles complex financial, scientific, and everyday calculations

SoulverCore is the command-line version that powers this MCP server, bringing Soulver's natural language math capabilities to Claude Desktop.

🧠 Why This Helps Claude with Math

This integration significantly enhances Claude's mathematical capabilities in several key ways:

🎯 Precision & Reliability

• Eliminates Calculation Errors: Claude's built-in math can sometimes produce approximations or errors, especially with complex financial calculations. SoulverCore provides precise, reliable results.
• Consistent Results: Every calculation is processed by the same proven mathematical engine, ensuring consistency across sessions.

🌍 Real-World Context

• Natural Language Processing: Claude can now handle math requests exactly as users write them, without needing to translate to programming syntax.
• Unit Intelligence: Automatic handling of currencies, measurements, dates, and percentages without manual conversion.
• Financial Expertise: Specialized functions for compound interest, loans, tips, and business calculations that Claude can now access reliably.

📚 Enhanced Learning

• Syntax Guidance: The MCP Resources provide Claude with comprehensive documentation about mathematical expression patterns.
• Error Resolution: Built-in troubleshooting guides help Claude assist users when calculations don't work as expected.
• Example Library: Extensive examples help Claude suggest the right syntax for complex calculations.

🔄 Interactive Workflows

• Guided Calculations: MCP Prompts provide structured templates for common calculations, making it easier for Claude to help users step through complex problems.
• Progressive Assistance: Claude can start with simple calculations and build up to more complex scenarios using the provided examples.

💡 Why This Matters

Before this integration, Claude might struggle with:

• Complex percentage calculations ($150 is 25% on what)
• Financial projections ($25k over 10 years at 7.5%)
• Unit conversions with context (65 kg in pounds)
• Date arithmetic (January 30 2020 + 3 months 2 weeks 5 days)

Now Claude can handle these naturally and accurately, making it a more reliable mathematical assistant for real-world problems.

✨ Features

🛠️ MCP Tools

• calculate - Evaluate natural language mathematical expressions
• soulver_status - Check SoulverCore CLI installation and version

💬 MCP Prompts

• compound_interest - Calculate compound interest with guided inputs
• tip_calculator - Calculate total cost including tips
• weight_conversion - Convert between weight units
• date_addition - Add time periods to dates
• percentage_calculation - Various percentage calculations

📚 MCP Resources

• Syntax Guide - Complete SoulverCore syntax reference
• Quick Reference - Common syntax patterns
• Financial Examples - Real-world financial calculations
• Conversion Examples - Unit conversion examples
• Date Examples - Date arithmetic examples
• Troubleshooting - Common errors and solutions

🚀 Quick Start

Prerequisites

• Node.js 18+
• SoulverCore CLI - Install with: brew install soulver-cli
• Claude Desktop with MCP support

Installation

1. Clone the repository

   git clone https://github.com/amotivv/soulver-mcp-server.git
   cd soulver-mcp-server
   

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

4. Test the server

   npm test
   

Claude Desktop Configuration

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "soulver": {
      "command": "node",
      "args": ["/absolute/path/to/soulver-mcp-server/dist/index.js"]
    }
  }
}

Important: Use the absolute path to your project directory.

📖 Usage Examples

Basic Calculations

Calculate: $25k over 10 years at 7.5%
→ $51,525.79

Calculate: 65 kg in pounds  
→ 143.3 lb

Calculate: $25/hour * 14 hours of work
→ $350.00

Financial Calculations

Calculate: $150 is 25% on what
→ $600.00

Calculate: $10 for lunch + 15% tip
→ $11.50

Calculate: 40 as % of 90
→ 44.44%

Date Arithmetic

Calculate: January 30 2020 + 3 months 2 weeks 5 days
→ May 19, 2020

Calculate: 9:35am in New York to Japan
→ 10:35 pm

Unit Conversions

Calculate: 32 fahrenheit in celsius
→ 0°C

Calculate: 10 miles in km
→ 16.09 km

🏗️ Architecture

graph TB
    A[Claude Desktop] -->|MCP Protocol| B[SoulverCore MCP Server]
    B -->|CLI Execution| C[SoulverCore CLI]
    B -->|Prompts| D[Interactive Templates]
    B -->|Resources| E[Documentation]
    B -->|Tools| F[Mathematical Engine]
    
    D --> G[Compound Interest]
    D --> H[Tip Calculator]
    D --> I[Unit Conversion]
    
    E --> J[Syntax Guide]
    E --> K[Examples]
    E --> L[Troubleshooting]
    
    F --> M[Expression Parser]
    F --> N[Result Formatter]

🔧 Development

Project Structure

soulver-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── soulver-cli.ts        # CLI wrapper
│   ├── test.ts               # Test suite
│   ├── prompts/              # MCP prompt definitions
│   │   ├── financial.ts
│   │   ├── conversions.ts
│   │   └── dates.ts
│   └── resources/            # MCP resource definitions
│       ├── syntax-guide.ts
│       └── examples.ts
├── dist/                     # Compiled JavaScript
├── memory-bank/              # Project documentation
├── package.json
├── tsconfig.json
└── README.md

Available Scripts

npm run build    # Compile TypeScript
npm test         # Run test suite
npm run dev      # Development mode (if configured)

Testing

The project includes a comprehensive test suite that validates:

• ✅ SoulverCore CLI availability
• ✅ Mathematical expression evaluation
• ✅ Error handling and edge cases
• ✅ MCP protocol compliance

npm test

📋 Supported Expression Types

Financial Calculations

• Compound Interest: $25k over 10 years at 7.5%
• Hourly Wages: $25/hour * 14 hours of work
• Tips: $10 for lunch + 15% tip
• Percentages: 40 as % of 90, $150 is 25% on what

Unit Conversions

• Weight: 65 kg in pounds, 150 lbs in kg
• Distance: 10 miles in km, 5 km in miles
• Temperature: 32 fahrenheit in celsius, 100 celsius in fahrenheit

Date Arithmetic

• Addition: January 30 2020 + 3 months 2 weeks 5 days
• Differences: December 31 2024 - January 1 2024
• Time Zones: 9:35am in New York to Japan

Basic Math

• Arithmetic: 100 + 200, 50% of 200
• Currency: $100 + $50, €200 - €75

🛡️ Security & Error Handling

• Input Sanitization: All expressions are validated before execution
• Process Timeout: CLI calls timeout after 10 seconds
• Error Recovery: Graceful handling of invalid expressions
• Resource Management: Proper cleanup of child processes
• Type Safety: Full TypeScript implementation with strict mode

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• SoulverCore - The powerful natural language math engine
• Model Context Protocol - The protocol enabling AI tool integration
• Claude Desktop - The AI assistant platform

📞 Support

• Issues: GitHub Issues
• Documentation: MCP Documentation
• SoulverCore: Official Documentation