# Stockflow MCP Server (JavaScript)

A Model Context Protocol (MCP) server that provides comprehensive financial data and analysis tools using Yahoo Finance. This is a JavaScript/Node.js port of the original Python version.

## Features

- **Real-time Stock Data**: Get current prices, market data, and company information
- **Historical Data**: Fetch historical price data with technical indicators
- **Technical Analysis**: Built-in SMA, EMA, RSI, MACD calculations
- **Options Chain**: Access options data with Greeks and analysis
- **Financial Statements**: Quarterly income, balance sheet, and cash flow data
- **Analyst Data**: Recommendations and price targets

## Installation

### Prerequisites

- Node.js 18.0.0 or higher
- npm or yarn package manager

### Setup

1. **Clone or create your project directory:**
   ```bash
   mkdir stockflow-mcp-server
   cd stockflow-mcp-server
   ```

2. **Initialize the project and install dependencies:**
   ```bash
   npm init -y
   npm install @modelcontextprotocol/sdk yahoo-finance2 technicalindicators
   npm install --save-dev @types/node
   ```

3. **Copy the server code** to `index.js`

4. **Update your `package.json`** to include `"type": "module"` for ES modules support

## Usage

### Running the Server

```bash
node index.js
```

Or if you've set up the npm script:

```bash
npm start
```

### Available Tools

#### 1. Get Stock Data (`get_stock_data_v2`)

Get comprehensive stock information including market data, valuation metrics, and optional financials.

**Parameters:**
- `symbol` (required): Stock ticker symbol (e.g., "AAPL")
- `include_financials` (optional): Include quarterly financial statements
- `include_analysis` (optional): Include analyst recommendations
- `include_calendar` (optional): Include calendar events

**Example:**
```json
{
  "symbol": "AAPL",
  "include_financials": true,
  "include_analysis": true
}
```

#### 2. Get Historical Data (`get_historical_data_v2`)

Fetch historical price data with technical indicators.

**Parameters:**
- `symbol` (required): Stock ticker symbol
- `period` (required): Time period (`1d`, `5d`, `1mo`, `3mo`, `6mo`, `1y`, `2y`, `5y`, `10y`, `ytd`, `max`)
- `interval` (optional): Data interval (`1m`, `2m`, `5m`, `15m`, `30m`, `60m`, `90m`, `1h`, `1d`, `5d`, `1wk`, `1mo`, `3mo`)
- `prepost` (optional): Include pre/post market data

**Example:**
```json
{
  "symbol": "TSLA",
  "period": "1y",
  "interval": "1d"
}
```

#### 3. Get Options Chain (`get_options_chain_v2`)

Access options chain data with analysis.

**Parameters:**
- `symbol` (required): Stock ticker symbol
- `expiration_date` (optional): Specific expiration date (YYYY-MM-DD)
- `include_greeks` (optional): Include options Greeks

**Example:**
```json
{
  "symbol": "SPY",
  "expiration_date": "2024-03-15"
}
```

## Technical Indicators

The server automatically calculates the following technical indicators for historical data:

- **Simple Moving Average (SMA)**: 20-day and 50-day
- **Exponential Moving Average (EMA)**: 12-day and 26-day
- **MACD**: Moving Average Convergence Divergence with signal line
- **RSI**: Relative Strength Index (14-day period)

## Error Handling

The server includes comprehensive error handling with:

- **Retry Logic**: Automatic retries for API failures
- **Validation**: Input parameter validation
- **Logging**: Detailed logging to `stockflow_v2.log`
- **Graceful Degradation**: Continues operation even if optional data fails

## Configuration

### Logging

Logs are written to **stderr only** to avoid interfering with MCP's JSON-RPC communication on stdout. The server automatically suppresses console output from the `yahoo-finance2` library to prevent protocol corruption.

**Note**: Due to MCP communication requirements, no log files are created. All logging output goes to stderr and will be visible in your terminal when running the server directly.

### Environment Variables

While not required, you can optionally set these environment variables:
- `NODE_ENV`: Set to 'development' for more verbose logging

### Console Output Suppression

The server automatically suppresses `console.log`, `console.warn`, and `console.info` output from dependencies (particularly `yahoo-finance2`) that could interfere with MCP communication. Only critical errors are redirected to stderr.

## MCP Integration

This server is designed to work with MCP-compatible clients like:
- Claude Desktop
- Cursor IDE
- Other MCP-enabled applications

### Client Configuration

Add this server to your MCP client configuration. Example for Claude Desktop:

```json
{
  "mcpServers": {
    "stockflow": {
      "command": "node",
      "args": ["/path/to/your/stockflow-server/index.js"]
    }
  }
}
```

## Differences from Python Version

This JavaScript version maintains API compatibility with the Python version while making these adaptations:

1. **Library Changes**:
   - `yfinance` → `yahoo-finance2`
   - `pandas` → Native JavaScript arrays and objects
   - `mcp.server` → `@modelcontextprotocol/sdk`

2. **Technical Indicators**:
   - Uses `technicalindicators` library instead of manual pandas calculations
   - Same calculation methods and periods for compatibility

3. **Error Handling**:
   - JavaScript Promises instead of Python async/await syntax
   - Similar retry logic and error classification

4. **Data Formats**:
   - JSON-compatible data structures throughout
   - ISO date formatting for consistency

5. **Console Output Management**:
   - Automatic suppression of library debug output to prevent MCP protocol interference
   - All logging redirected to stderr to maintain clean stdout for JSON-RPC communication

6. **Filesystem Independence**:
   - No log file creation (logs to stderr only)
   - Works in read-only and sandboxed environments

## Troubleshooting

### Common Issues

1. **Module Not Found Errors**: Ensure you have Node.js 18+ and all dependencies installed
2. **API Rate Limits**: Yahoo Finance may rate limit requests; the server includes retry logic
3. **Network Timeouts**: Check your internet connection if API calls fail consistently
4. **JSON Parse Errors in MCP Client**: This usually indicates console output is interfering with MCP communication - the server now automatically suppresses such output
5. **Read-Only Filesystem Errors**: The server no longer attempts to write log files and should work in sandboxed environments

### Debug Mode

The server logs to stderr by default. To see more detailed output, run your MCP client with verbose logging enabled, or run the server directly to see stderr output:

```bash
node index.js
```

### MCP Communication Issues

If you see JSON parsing errors in your MCP client logs:
- Ensure no other applications are writing to stdout
- Verify the server is running with the console output suppression (built-in)
- Check that you're using the latest version of the server code

## Contributing

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

## License

MIT License - see LICENSE file for details

## Acknowledgments

- Based on the original Python `stockflow` server
- Uses Yahoo Finance data via the `yahoo-finance2` library
- Built with the official MCP TypeScript/JavaScript SDK
- Technical indicators powered by `technicalindicators` library