Marketstack MCP Server

# System Patterns: Marketstack MCP Server ## System Architecture The Marketstack MCP server follows a modular architecture designed for scalability and maintainability. It is built as a Node.js application using TypeScript. The core of the architecture is the MCP server SDK, which handles tool registration and execution. All Marketstack API calls are routed through a centralized `MarketstackClient` instance, which manages caching and API key usage. ## Key Technical Decisions - **TypeScript:** Chosen for type safety, improved code quality, and maintainability. - **@modelcontextprotocol/sdk:** Used as the foundation for building the MCP server and defining tools. - **Zod for Schema Validation:** Ensures that tool inputs are correctly structured and validated before processing. - **Native Fetch:** Used for making HTTP requests to the Marketstack API, leveraging built-in Node.js capabilities (requires Node.js 18+). - **Environment Variables:** API keys and other sensitive configuration are managed via environment variables for security. - **Centralized API Client & LRU Cache:** All tool handlers use a shared `MarketstackClient` instance, which implements an LRU cache at the client level. This cache is keyed by API parameters only, ensuring cache efficiency and preventing redundant entries due to client-side filters. ## Design Patterns in Use - **Modular Design:** Each Marketstack API endpoint is implemented as a distinct tool, encapsulated within its own file with a clear schema, handler, and tool definition. - **Categorization:** Tools are grouped by Marketstack API categories (Market Data, Reference Data, Financial Instruments) into separate directories for organization. - **Index Files:** Index files (`index.ts`) within each category directory and the main `src/tools/index.ts` file are used to register and export tools, simplifying the server's main entry point (`src/index.ts`). - **Dependency Injection:** All tool handlers receive the shared `MarketstackClient` instance as a parameter, promoting testability and separation of concerns. - **Client-Level Caching:** Caching is handled exclusively by the `MarketstackClient`. ## Component Relationships - `src/index.ts`: Initializes the MCP server, creates the shared `MarketstackClient`, and imports/registers tool groups from `src/tools/index.ts`. - `src/tools/index.ts`: Imports and registers individual tool groups (e.g., `src/tools/marketData/index.ts`), passing the client instance. - `src/tools/[category]/index.ts`: Imports and registers individual tools within that category (e.g., `src/tools/marketData/getEndOfDayData.ts`), passing the client instance to each handler. - `src/tools/[category]/[toolName].ts`: Contains the Zod schema, handler function (which receives the client), and tool definition for a specific Marketstack endpoint. - All handlers use the shared `MarketstackClient` to interact with the Marketstack API and benefit from the centralized LRU cache. - The caching layer is implemented in `src/marketstackClient.ts` and is transparent to tool registration and handler logic.