# Marketstack MCP Server

A Model Context Protocol (MCP) server that exposes various Marketstack API endpoints as MCP tools, providing access to financial data including end-of-day, intraday, splits, dividends, tickers, exchanges, currencies, timezones, bonds, and ETF data. This server simplifies integrating Marketstack data into MCP-compatible agents and systems.

## Prerequisites

- Node.js (v18 or later recommended)
- npm (comes with Node.js)
- Marketstack API key
- (Optional) MCP-compatible client or runner (e.g., VSCode extension, CLI)

## Setup

1. **Clone the repository or ensure you are in the project directory.**

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Configuration:**
   * Obtain a Marketstack API key from [https://marketstack.com/](https://marketstack.com/).
   * Configure the `MARKETSTACK_API_KEY` environment variable via your MCP runner's settings. This is the recommended method for seamless integration with the MCP client. Avoid using `.env` files for this purpose when running via an MCP runner.

## Building and Running

1. **Build the server:**
   ```bash
   npm run build
   ```
   This will create a `build` directory with the compiled JavaScript code.

2. **Run the server:**
   ```bash
   npm run start
   ```
   or directly:
   ```bash
   node build/index.js
   ```

3. **Via MCP runner:**
   Configure your MCP client to run the server using stdio transport.
   Example MCP settings entry (adjust `/path/to/mcp-marketstack` to your actual path and replace `YOUR_API_KEY_HERE` with your actual key):
   ```json
   "marketstack": {
     "transportType": "stdio",
     "command": "node",
     "args": [
       "/path/to/mcp-marketstack/build/index.js"
     ],
     "env": {
       "MARKETSTACK_API_KEY": "YOUR_API_KEY_HERE"
     }
     // ... other optional settings ...
   }
   ```

## Available Tools

The server exposes Marketstack API endpoints as distinct MCP tools, categorized by function:

- Market Data
- Reference Data
- Financial Instruments

Detailed input schemas and descriptions for each tool are automatically discoverable by MCP agents connecting to the server via introspection.

## Project Structure

The project follows a modular structure:

```
.
├── src/
│   ├── index.ts          # Server entry point
│   ├── marketstackClient.ts # Centralized API client with caching
│   ├── cacheConfig.ts    # Cache TTL configurations
│   └── tools/
│       ├── index.ts      # Registers all tool categories
│       ├── marketData/ # Market Data tools
│       │   └── ...
│       ├── referenceData/ # Reference Data tools
│       │   └── ...
│       ├── financialInstruments/ # Financial Instruments tools
│       │   └── ...
│       └── wrapToolHandler.ts # Wrapper for tool handlers
├── memory-bank/          # Project documentation
│   └── ...
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── eslint.config.js      # ESLint configuration
├── .prettierrc           # Prettier configuration
├── LICENSE               # Project license
└── README.md             # This file
```

## Caching

The server implements an in-memory Least Recently Used (LRU) cache for tool responses. This helps reduce redundant calls to the Marketstack API, improving performance and adhering to rate limits.

- **Mechanism:** The cache stores responses based on the tool name and input parameters.
- **Configurable TTLs:** Each tool has a configurable Time To Live (TTL) for its cached data, defined in `src/cacheConfig.ts`. This allows for different caching durations based on the update frequency of the data provided by each Marketstack endpoint.

## Licensing

This project is licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See the `LICENSE` file for details.

## Contributing

Contributions are welcome! Please follow the standard fork-and-pull request workflow.

## Support

For issues or questions, please open an issue on the GitHub repository.