@equidam/mcp-server/README.md

Equidam MCP Server - Bridge between AI assistants and Equidam's company valuation API

# @equidam/mcp-server

> Bridge between AI assistants and Equidam's company valuation API using the Model Context Protocol (MCP)

## Overview

The Equidam MCP Server enables AI assistants like Claude and ChatGPT to access Equidam's company valuation tools directly within conversations. Users can get professional-grade company valuations, industry classifications, and market insights through natural language interactions.

## Features

- **Industry Classification**: Classify companies from natural language descriptions
- **Company Valuation**: Get professional valuations based on financial projections
- **MCP Protocol**: Standard interface compatible with multiple AI assistants
- **Retry Logic**: Robust error handling with exponential backoff
- **Rate Limiting**: Built-in respect for API rate limits
- **Security**: No token persistence or logging

## Valuation Methodology

Equidam provides comprehensive valuations using a **five-method synthesis approach** that adapts to your company's development stage:

### The Five Methods

1. **Qualitative Methods** (weighted heavily for early-stage):
   - **Scorecard Method**: Compares your startup to average peers across 6 criteria
   - **Checklist Method**: Values company as sum of core achievements

2. **Discounted Cash Flow (DCF)** (intrinsic value approach):
   - **DCF with Long-Term Growth**: Assumes perpetual growth (0.1-2.5% annually)
   - **DCF with Multiple**: Assumes exit at industry-specific EBITDA multiple

3. **Venture Capital Method** (investor perspective):
   - Works backward from exit value using stage-specific required returns (35-94% ROI)

### Stage-Based Weighting

The methods are weighted dynamically based on company stage:
- **Idea Stage**: 76% qualitative, 8% DCF, 16% VC
- **Development**: 60% qualitative, 24% DCF, 16% VC  
- **Growth**: 0% qualitative, 80% DCF, 20% VC
- **Maturity**: 0% qualitative, 100% DCF, 0% VC

### Key Adjustments

- **Survival Rates**: Country-specific startup survival probabilities
- **Illiquidity Discount**: Adjustment for private company shares
- **Risk Factors**: 4-factor beta based on industry, size, profitability, and age

### Important Notes

- This **10-question estimate** provides quick indicative valuations
- For serious negotiations or financial planning, obtain a **detailed valuation report** from Equidam
- Full reports include 50+ data points and comprehensive documentation
- Valuations should not be considered financial advice

### Resources

- **Methodology Details**: https://www.equidam.com/resources/Equidam-Valuation-Methodology.pdf
- **How the 10 Question Valuate Estimate works** https://support.equidam.com/en/articles/9149899-how-the-10-question-valuation-estimate-works
- **Sample Report**: https://www.equidam.com/resources/Equidam-Benchmarked-Valuation-Report-Sample.pdf
- **Pitch Deck Review**: https://chat.openai.com/g/g-sz9iMqwSL-pitchdeck-review-by-equidam

## Quick Start

### 1. Get Your API Token

Visit [https://www.equidam.com/contacts/](https://www.equidam.com/contacts/) to request your API token.

### 2. Configure Your AI Assistant

#### Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "equidam": {
      "command": "npx",
      "args": ["@equidam/mcp-server", "--api-key", "YOUR_API_TOKEN_HERE"]
    }
  }
}
```

#### ChatGPT (when MCP support is available)

```json
{
  "mcpServers": {
    "equidam": {
      "command": "npx",
      "args": ["@equidam/mcp-server", "--api-key", "YOUR_API_TOKEN_HERE"]
    }
  }
}
```

### 3. Restart Your AI Assistant

Restart Claude Desktop or your AI assistant to load the new MCP server.

### 4. Start Using

Ask your AI assistant questions like:
- "What's the valuation for a SaaS company with $500k current revenue?"
- "Classify this company: 'We build AI-powered medical diagnostic software'"
- "Value my e-commerce startup with $200k revenue growing to $1M in 4 years"

## Configuration Options

```bash
npx @equidam/mcp-server [options]

Required:
  --api-key <key>     Your Equidam API token

Optional:
  --base-url <url>    API base URL (default: https://app.equidam.com/api/v3)
  --debug             Enable debug logging to stderr
  -V, --version       Show version number
  -h, --help          Show help
```

### Configuration File Locations

#### Claude Desktop

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

## Available Tools

### 1. classify_company_industry

Classifies a company's industry from natural language description.

**Parameters:**
- `description` (required): Company description (3-1000 characters)
- `context` (optional): Array of additional context strings

**Example:**
```json
{
  "description": "A software company that builds project management tools for remote teams",
  "context": ["B2B", "SaaS", "productivity software"]
}
```

**Response:**
```json
{
  "success": true,
  "industry_code": "5720102010",
  "industry_name": "Software Development",
  "confidence": 0.85,
  "confidence_level": "High",
  "alternatives": [...],
  "usage_note": "Use the 'industry_code' from this result as input for the get_company_valuation tool."
}
```

### 2. get_company_valuation

Gets company valuation based on financial and business information.

**Parameters:**
- `industry_code` (required): 10-digit code from classification tool
- `revenue_y1` (required): Current year revenue
- `revenue_y4` (required): Year 4 projected revenue  
- `country` (required): 2-letter country code (e.g., "US", "GB")
- `currency` (optional): 3-letter currency code (e.g., "USD", "EUR")
- `employees` (optional): Number of employees
- `founders` (optional): Number of founders
- `started_year` (optional): Year company was founded

**Example:**
```json
{
  "industry_code": "5720102010",
  "revenue_y1": 500000,
  "revenue_y4": 2000000,
  "country": "US",
  "currency": "USD",
  "employees": 15,
  "founders": 2,
  "started_year": 2020
}
```

**Response:**
```json
{
  "success": true,
  "valuation": {
    "lower": 1200000,
    "higher": 2100000,
    "avg": 1650000,
    "currency": "USD"
  },
  "summary": {
    "valuation_range": "1.20M USD - 2.10M USD",
    "average_valuation": "1.65M USD",
    "revenue_multiple_y1": 3.30
  },
  "methodology": {
    "primary_method": "Revenue Multiple",
    "benchmark_companies": 42,
    "confidence_level": "High"
  },
  "market_data": {
    "industry_growth_rate": 25.5,
    "market_size": "Large",
    "competitive_landscape": "Moderate"
  }
}
```

## Typical Workflow

1. **Classify Industry**: Use natural language to identify the company's industry
2. **Get Valuation**: Use the industry code with financial data for valuation
3. **Interpret Results**: Review valuation range, methodology, and market context

```
User: "What's the valuation for a food delivery app with $1M revenue?"

AI: Let me help you with that valuation. First, I'll classify the industry, then calculate the valuation.

[Calls classify_company_industry with "food delivery app"]
→ Returns industry code "6220101010"

[Calls get_company_valuation with the industry code and financial data]
→ Returns valuation range $2.5M - $4.2M

Based on the analysis, your food delivery app has an estimated valuation of $2.5M - $4.2M, with an average of $3.35M USD.
```

## Error Handling

The server includes comprehensive error handling:

- **Authentication Errors**: Invalid API key messages
- **Rate Limits**: Automatic retry with exponential backoff
- **Network Issues**: Connection retry logic
- **Validation Errors**: Clear parameter validation messages
- **Server Errors**: Graceful degradation

## Rate Limits

- **20 requests per hour** per API token
- Automatic retry for rate limit errors
- Exponential backoff prevents overwhelming the API

## Troubleshooting

### Common Issues

**"Authentication failed"**
- Check your API token is correct
- Ensure token has proper permissions
- Token might be expired - generate a new one

**"Rate limit exceeded"**
- Wait a few minutes before retrying
- You've exceeded 20 requests per hour
- Consider upgrading your Equidam plan

**"Connection failed"**
- Check internet connection
- Firewall might be blocking requests
- API service might be temporarily down

**"Unknown tool" error**
- Restart your AI assistant
- Check MCP server configuration
- Ensure latest version is installed

### Debug Mode

Enable debug logging to troubleshoot issues:

```json
{
  "mcpServers": {
    "equidam": {
      "command": "npx",
      "args": ["@equidam/mcp-server", "--api-key", "YOUR_TOKEN", "--debug"]
    }
  }
}
```

Debug information appears in your AI assistant's console/logs.

### Version Check

```bash
npx @equidam/mcp-server --version
```

## Security

- **No Token Storage**: API tokens are not persisted or logged
- **HTTPS Only**: All API communication uses secure HTTPS
- **No Telemetry**: No usage data collection or tracking
- **Process Isolation**: Runs in isolated Node.js process

## Requirements

- **Node.js**: Version 18.0.0 or higher
- **Network**: Internet connection for API access
- **AI Assistant**: MCP-compatible assistant (Claude Desktop, etc.)

## Support

- **Documentation**: [Equidam API Docs](https://docs.equidam.com)
- **Issues**: [GitHub Issues](https://github.com/equidam/mcp-server/issues)
- **API Support**: support@equidam.com

## Examples

### SaaS Company Valuation
```
"Value a B2B SaaS company with $250k ARR, projecting $1.5M in year 4, based in Germany"
```

### E-commerce Startup
```
"What's the valuation for an e-commerce platform selling handmade goods, $100k current revenue, expecting $800k in 4 years?"
```

### Tech Startup Classification
```
"Classify this company: 'We use AI and machine learning to optimize supply chain logistics for retail companies'"
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

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

## Changelog

### v1.0.0
- Initial release
- Industry classification tool
- Company valuation tool
- MCP protocol implementation
- Comprehensive error handling
- Retry logic with exponential backoff