finmap-mcp 2.0.8 → 3.0.0

package/README.md

@@ -11,7 +11,7 @@ The finmap.org MCP server provides comprehensive historical data from the US, UK
 | American Stock Exchange | `amex` | United States | 2024-12-09 | Daily |
 | US Combined (AMEX + NASDAQ + NYSE) | `us-all` | United States | 2024-12-09 | Daily |
 | London Stock Exchange | `lse` | United Kingdom | 2025-02-07 | Hourly (weekdays) |
-| Hong Kong Stock Exchange | `hkex` | Hong Kong | 2025-09-26 | Every 30 minutes (weekdays) |
+| Hong Kong Stock Exchange | `hkex` | Hong Kong | 2025-09-29 | Every 30 minutes (weekdays) |
 | Borsa Istanbul | `bist` | Turkey | 2015-11-30 | Every two months |
 | Moscow Exchange | `moex` | Russia | 2011-12-19 | Every 15 minutes (weekdays) |
 
@@ -59,13 +59,31 @@ npx finmap-mcp
 }
 ```
 
+
+## HTTP API Wrapper
+
+The server also exposes a compact HTTP API for GPT Actions and direct integration.
+
+- `GET /api/openapi.json`
+- `GET /api/list-exchanges`
+- `POST /api/list-sectors`
+- `POST /api/list-sector-companies`
+- `POST /api/search-companies`
+- `POST /api/market-overview`
+- `POST /api/sector-performance`
+- `POST /api/rank-stocks`
+- `POST /api/stock-snapshot`
+- `POST /api/company-profile`
+
+A ready-to-import GPT Actions schema is available in `gpt-actions.yaml`.
+
 ## Available Tools
 
-### 1. `list_exchanges`
-  - Title: List exchanges
-  - Description: Return supported exchanges with IDs, names, country, currency, earliest available date, and update frequency.
+### 1. `list_supported_exchanges`
+  - Title: List supported stock exchanges
+  - Description: Return metadata for all supported stock exchanges in the Finmap dataset. Includes exchange ID, exchange name, country, currency, earliest available historical data date, and update frequency.
 
-  **Example Promt:** `#finmap-mcp list available stock exchanges`
+  **Example Prompt:** `#finmap-mcp list available stock exchanges`
 
   **Example Response:**
   ```json
@@ -132,18 +150,18 @@ npx finmap-mcp
         "name": "Hong Kong Stock Exchange",
         "country": "Hong Kong",
         "currency": "HKD",
-        "availableSince": "2025-09-26",
+        "availableSince": "2025-09-29",
         "updateFrequency": "Every 30 minutes (weekdays)"
       }
     ]
   }
   ```
 
-### 2. `list_sectors`
-  - Title: List sectors
-  - Description: List available business sectors for an exchange on a specific date, including item counts.
+### 2. `list_exchange_sectors`
+  - Title: List sectors for a stock exchange
+  - Description: Return all business sectors available on a specific exchange and trading date. Each sector includes the number of companies in that sector.
 
-  **Example Promt:** `#finmap-mcp List sectors for the Turkish stock exchange`
+  **Example Prompt:** `#finmap-mcp List sectors for the Turkish stock exchange`
   
   **Example Response:**
   ```json
@@ -236,11 +254,11 @@ npx finmap-mcp
   }
   ```
 
-### 3. `list_tickers`
-  - Title: List tickers by sector
-  - Description: Return company tickers and names for an exchange on a specific date, grouped by sector.
+### 3. `list_sector_companies`
+  - Title: List companies by sector
+  - Description: Return company tickers and names grouped by sector for an exchange on a specific trading date. Optionally filter results by a single sector.
 
-  **Example Promt:** `#finmap-mcp List companies in the Real Estate sector`
+  **Example Prompt:** `#finmap-mcp List companies in the Real Estate sector`
   
   **Example Response:**
   ```json
@@ -271,11 +289,11 @@ npx finmap-mcp
   }
   ```
 
-### 4. `search_companies`
-  - Title: Search companies
-  - Description: Find companies by partial name or ticker on an exchange and return best matches.
+### 4. `search_exchange_companies`
+  - Title: Search companies by name or ticker
+  - Description: Search for companies on a specific exchange by partial ticker symbol or company name. Results are ranked by relevance using ticker and name similarity.
 
-  **Example Promt:** `#finmap-mcp Search for companies named 'Sprouts'`
+  **Example Prompt:** `#finmap-mcp Search for companies named 'Sprouts'`
 
   **Example Response:**
   ```json
@@ -295,11 +313,11 @@ npx finmap-mcp
   }
   ```
 
-### 5. `get_market_overview`
-  - Title: Market overview
-  - Description: Get total market cap, volume, value, and performance for an exchange on a specific date with a sector breakdown.
+### 5. `analyze_market_overview`
+  - Title: Analyze market overview
+  - Description: Return aggregated statistics for a stock exchange on a specific date. Includes total market capitalization, trading volume, total traded value, number of trades, and sector-level market breakdown.
 
-  **Example Promt:** `#finmap-mcp market overview for Nasdaq`
+  **Example Prompt:** `#finmap-mcp market overview for Nasdaq`
   
   **Example Response:**
   ```json
@@ -358,11 +376,11 @@ npx finmap-mcp
   }
   ```
 
-### 6. `get_sectors_overview`
-  - Title: Sector performance
-  - Description: Get aggregated performance metrics by sector for an exchange on a specific date.
+### 6. `analyze_sector_performance`
+  - Title: Analyze sector performance
+  - Description: Return aggregated metrics for each sector in a stock exchange. Includes sector market capitalization, price change percentage, trading volume, traded value, number of trades, and number of companies in the sector.
 
-  **Example Promt:** `#finmap-mcp Get overview for the Utilities sector`
+  **Example Prompt:** `#finmap-mcp Get overview for the Utilities sector`
   
   **Example Response:**
   ```json
@@ -384,11 +402,11 @@ npx finmap-mcp
   }
   ```
 
-### 7. `get_stock_data`
-  - Title: Stock data by ticker
-  - Description: Get detailed market data for a specific ticker on an exchange and date, including price, change, volume, value, market cap, and trades.
+### 7. `get_stock_snapshot`
+  - Title: Get stock market snapshot
+  - Description: Return detailed trading metrics for a single stock ticker on a specific exchange and trading date. Includes price open, last sale price, price change percentage, trading volume, traded value, number of trades, and market capitalization.
 
-  **Example Promt:** `#finmap-mcp Dominion Energy, stock data`
+  **Example Prompt:** `#finmap-mcp Dominion Energy, stock data`
   
   **Example Response:**
   ```json
@@ -412,11 +430,11 @@ npx finmap-mcp
   }
   ```
 
-### 8. `rank_stocks`
-  - Title: Rank stocks
-  - Description: Rank stocks on an exchange by a chosen metric (marketCap, priceChangePct, volume, value, numTrades) for a specific date with order and limit.
+### 8. `rank_exchange_companies`
+  - Title: Rank companies by market metric
+  - Description: Return companies ranked by a selected market metric on a specific exchange. Supported ranking metrics: market capitalization, price change percentage, trading volume, traded value, and number of trades. Results can be limited and optionally filtered by sector.
 
-  **Example Promt:** `#finmap-mcp UK, rank stocks by market cap`
+  **Example Prompt:** `#finmap-mcp UK, rank stocks by market cap`
   
   **Example Response:**
   ```json
@@ -488,11 +506,11 @@ npx finmap-mcp
   }
   ```
 
-### 9. `get_company_profile`
-  - Title: Company profile (US)
-  - Description: Get business description, industry, and background for a US-listed company by ticker.
+### 9. `get_company_profile_us`
+  - Title: Get US company profile
+  - Description: Return business description and background information for a US-listed company. Supported exchanges: NASDAQ, NYSE, and AMEX.
 
-  **Example Promt:** `#finmap-mcp Sprouts Farmers Market, get company profile`
+  **Example Prompt:** `#finmap-mcp Sprouts Farmers Market, get company profile`
   
   **Example Response:**
   ```json

package/dist/core.js

@@ -1,71 +1,4 @@
-import { z } from "zod";
-const BASE_URL = "https://finmap.org";
-const DATA_BASE_URL = "https://raw.githubusercontent.com/finmap-org";
-const INFO = {
-    provider: "finmap.org",
-    description: "Discover interactive stock charts and curated news at finmap.org",
-    github: "https://github.com/finmap-org",
-    donate: {
-        patreon: "https://patreon.com/finmap",
-        boosty: "https://boosty.to/finmap",
-    },
-    issues: "https://github.com/finmap-org/mcp-server/issues",
-    feedback: "contact@finmap.org",
-};
-const STOCK_EXCHANGES = [
-    "amex",
-    "nasdaq",
-    "nyse",
-    "us-all",
-    "lse",
-    "moex",
-    "bist",
-    "hkex",
-];
-const US_EXCHANGES = ["amex", "nasdaq", "nyse"];
-const SORT_FIELDS = [
-    "priceChangePct",
-    "marketCap",
-    "value",
-    "volume",
-    "numTrades",
-];
-const SORT_ORDERS = ["asc", "desc"];
-const INDICES = {
-    EXCHANGE: 0,
-    COUNTRY: 1,
-    TYPE: 2,
-    SECTOR: 3,
-    INDUSTRY: 4,
-    CURRENCY_ID: 5,
-    TICKER: 6,
-    NAME_ENG: 7,
-    NAME_ENG_SHORT: 8,
-    NAME_ORIGINAL: 9,
-    NAME_ORIGINAL_SHORT: 10,
-    PRICE_OPEN: 11,
-    PRICE_LAST_SALE: 12,
-    PRICE_CHANGE_PCT: 13,
-    VOLUME: 14,
-    VALUE: 15,
-    NUM_TRADES: 16,
-    MARKET_CAP: 17,
-    LISTED_FROM: 18,
-    LISTED_TILL: 19,
-    WIKI_PAGE_ID_ENG: 20,
-    WIKI_PAGE_ID_ORIGINAL: 21,
-    ITEMS_PER_SECTOR: 22,
-};
-const EXCHANGE_TO_COUNTRY_MAP = {
-    amex: "us",
-    nasdaq: "us",
-    nyse: "us",
-    "us-all": "us",
-    lse: "uk",
-    moex: "russia",
-    bist: "turkey",
-    hkex: "hongkong",
-};
+import { companyProfileSchema, getCompanyProfile, getMarketOverview, getSectorsOverview, getStockData, listExchanges, listSectors, listSectorsSchema, listTickers, listTickersSchema, marketOverviewSchema, rankStocks, rankStocksSchema, searchCompanies, searchCompaniesSchema, sectorsOverviewSchema, stockDataSchema, } from "./api.js";
 function createResponse(data) {
     return {
         content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -74,475 +7,110 @@ function createResponse(data) {
 function createErrorResponse(error) {
     return createResponse(`ERROR: ${error instanceof Error ? error.message : String(error)}`);
 }
-function createCharts(exchange, date) {
-    return {
-        histogram: `${BASE_URL}/?chart=histogram&data=marketcap&currency=USD&exchange=${exchange}`,
-        treemap: `${BASE_URL}/?chart=treemap&data=marketcap&currency=USD&exchange=${exchange}${date ? `&date=${date.replaceAll("-", "/")}` : ""}`,
-    };
-}
-function calculateMatchScore(ticker, name, searchTerm) {
-    const tickerLower = ticker.toLowerCase();
-    const nameLower = name.toLowerCase();
-    if (tickerLower === searchTerm)
-        return 100;
-    if (tickerLower.startsWith(searchTerm))
-        return 90;
-    if (tickerLower.includes(searchTerm))
-        return 80;
-    if (nameLower.includes(searchTerm))
-        return 70;
-    return 0;
-}
-const EXCHANGE_INFO = {
-    amex: {
-        name: "American Stock Exchange",
-        country: "United States",
-        currency: "USD",
-        availableSince: "2024-12-09",
-        updateFrequency: "Daily",
-    },
-    nasdaq: {
-        name: "NASDAQ Stock Market",
-        country: "United States",
-        currency: "USD",
-        availableSince: "2024-12-09",
-        updateFrequency: "Daily",
-    },
-    nyse: {
-        name: "New York Stock Exchange",
-        country: "United States",
-        currency: "USD",
-        availableSince: "2024-12-09",
-        updateFrequency: "Daily",
-    },
-    "us-all": {
-        name: "US Combined (AMEX + NASDAQ + NYSE)",
-        country: "United States",
-        currency: "USD",
-        availableSince: "2024-12-09",
-        updateFrequency: "Daily",
-    },
-    lse: {
-        name: "London Stock Exchange",
-        country: "United Kingdom",
-        currency: "GBP",
-        availableSince: "2025-02-07",
-        updateFrequency: "Hourly (weekdays)",
-    },
-    moex: {
-        name: "Moscow Exchange",
-        country: "Russia",
-        currency: "RUB",
-        availableSince: "2011-12-19",
-        updateFrequency: "Every 15 minutes (weekdays)",
-    },
-    bist: {
-        name: "Borsa Istanbul",
-        country: "Turkey",
-        currency: "TRY",
-        availableSince: "2015-11-30",
-        updateFrequency: "Every two months",
-    },
-    hkex: {
-        name: "Hong Kong Stock Exchange",
-        country: "Hong Kong",
-        currency: "HKD",
-        availableSince: "2025-09-29",
-        updateFrequency: "Every 30 minutes (weekdays)",
-    },
-};
-const exchangeSchema = z
-    .enum(STOCK_EXCHANGES)
-    .describe("Stock exchange: amex, nasdaq, nyse, us-all, lse, moex, bist, hkex");
-const dateSchema = {
-    year: z.number().int().min(2012).optional(),
-    month: z.number().int().min(1).max(12).optional(),
-    day: z.number().int().min(1).max(31).optional(),
-};
-function buildDateString(year, month, day) {
-    const currentDate = new Date();
-    const y = year ?? currentDate.getFullYear();
-    const m = month ?? currentDate.getMonth() + 1;
-    const d = day ?? currentDate.getDate();
-    return `${y.toString()}/${m.toString().padStart(2, "0")}/${d.toString().padStart(2, "0")}`;
-}
-function validateAndFormatDate(dateString) {
-    const date = dateString.replaceAll("/", "-");
-    z.string().date().parse(date);
-    const dayOfWeek = new Date(date).getDay();
-    if (dayOfWeek === 0 || dayOfWeek === 6) {
-        throw new Error("Data is only available for work days (Monday to Friday)");
-    }
-    return date;
-}
-function getDate(year, month, day) {
-    const dateString = buildDateString(year, month, day);
-    return validateAndFormatDate(dateString);
-}
-async function fetchMarketData(stockExchange, formattedDate) {
-    const country = EXCHANGE_TO_COUNTRY_MAP[stockExchange];
-    const date = formattedDate.replaceAll("-", "/");
-    const url = `${DATA_BASE_URL}/data-${country}/refs/heads/main/marketdata/${date}/${stockExchange}.json`;
-    const response = await fetch(url);
-    if (response.status === 404) {
-        throw new Error(`Not found, try another date. The date must be on or after ${EXCHANGE_INFO[stockExchange].availableSince} for ${stockExchange}`);
-    }
-    return response.json();
-}
-async function fetchSecurityInfo(exchange, ticker) {
-    const firstLetter = ticker.charAt(0).toUpperCase();
-    const url = `${DATA_BASE_URL}/data-us/refs/heads/main/securities/${exchange}/${firstLetter}/${ticker}.json`;
-    const response = await fetch(url);
-    if (response.status === 404) {
-        throw new Error(`Security ${ticker} not found on ${exchange}`);
-    }
-    const data = (await response.json());
-    return data;
-}
 export function registerFinmapTools(server) {
-    server.registerTool("list_exchanges", {
-        title: "List exchanges",
-        description: "Return supported exchanges with IDs, names, country, currency, earliest available date, and update frequency.",
+    server.registerTool("list_supported_exchanges", {
+        title: "List supported stock exchanges",
+        description: "Return metadata for all supported stock exchanges in the Finmap dataset, including exchange ID, exchange name, country, currency, earliest available historical data date, and update frequency.",
         inputSchema: {},
     }, async () => {
         try {
-            const exchanges = Object.entries(EXCHANGE_INFO).map(([id, info]) => ({
-                id,
-                ...info,
-            }));
-            return createResponse({ info: INFO, exchanges });
+            return createResponse(listExchanges());
         }
         catch (error) {
             return createErrorResponse(error);
         }
     });
-    server.registerTool("list_sectors", {
-        title: "List sectors",
-        description: "List available business sectors for an exchange on a specific date, including item counts.",
-        inputSchema: { stockExchange: exchangeSchema, ...dateSchema },
-    }, async ({ stockExchange, year, month, day, }) => {
+    server.registerTool("list_exchange_sectors", {
+        title: "List sectors for a stock exchange",
+        description: "Return all business sectors available on a specific exchange and trading date. Each sector includes the number of companies in that sector.",
+        inputSchema: listSectorsSchema.shape,
+    }, async (input) => {
         try {
-            const formattedDate = getDate(year, month, day);
-            const marketDataResponse = await fetchMarketData(stockExchange, formattedDate);
-            const sectorCounts = {};
-            marketDataResponse.securities.data.forEach((item) => {
-                if (item[INDICES.TYPE] !== "sector" && item[INDICES.SECTOR]) {
-                    sectorCounts[item[INDICES.SECTOR]] =
-                        (sectorCounts[item[INDICES.SECTOR]] || 0) + 1;
-                }
-            });
-            const sectors = Object.entries(sectorCounts).map(([name, count]) => ({
-                name,
-                itemsPerSector: count,
-            }));
-            return createResponse({
-                info: INFO,
-                date: formattedDate,
-                exchange: stockExchange.toUpperCase(),
-                currency: EXCHANGE_INFO[stockExchange].currency,
-                sectors,
-            });
+            return createResponse(await listSectors(listSectorsSchema.parse(input)));
         }
         catch (error) {
             return createErrorResponse(error);
         }
     });
-    server.registerTool("list_tickers", {
-        title: "List tickers by sector",
-        description: "Return company tickers and names for an exchange on a specific date, grouped by sector.",
-        inputSchema: {
-            stockExchange: exchangeSchema,
-            ...dateSchema,
-            sector: z.string().optional().describe("Filter by specific sector"),
-            englishNames: z
-                .boolean()
-                .default(true)
-                .describe("Use English names if available"),
-        },
-    }, async ({ stockExchange, year, month, day, sector, englishNames, }) => {
+    server.registerTool("list_sector_companies", {
+        title: "List companies by sector",
+        description: "Return company tickers and names grouped by sector for an exchange on a specific trading date. Optionally filter results by a single sector.",
+        inputSchema: listTickersSchema.shape,
+    }, async (input) => {
         try {
-            const formattedDate = getDate(year, month, day);
-            const marketDataResponse = await fetchMarketData(stockExchange, formattedDate);
-            const sectorGroups = {};
-            marketDataResponse.securities.data.forEach((item) => {
-                if (item[INDICES.TYPE] !== "sector" &&
-                    item[INDICES.SECTOR] &&
-                    (!sector || item[INDICES.SECTOR] === sector)) {
-                    const sectorName = item[INDICES.SECTOR];
-                    const ticker = item[INDICES.TICKER];
-                    const name = englishNames
-                        ? item[INDICES.NAME_ENG]
-                        : item[INDICES.NAME_ORIGINAL_SHORT] || item[INDICES.NAME_ENG];
-                    if (ticker && name) {
-                        if (!sectorGroups[sectorName])
-                            sectorGroups[sectorName] = [];
-                        sectorGroups[sectorName].push({ ticker, name });
-                    }
-                }
-            });
-            Object.values(sectorGroups).forEach((companies) => {
-                companies.sort((a, b) => a.ticker.localeCompare(b.ticker));
-            });
-            return createResponse({
-                info: INFO,
-                date: formattedDate,
-                exchange: stockExchange.toUpperCase(),
-                currency: EXCHANGE_INFO[stockExchange].currency,
-                sectors: sectorGroups,
-            });
+            return createResponse(await listTickers(listTickersSchema.parse(input)));
         }
         catch (error) {
             return createErrorResponse(error);
         }
     });
-    server.registerTool("search_companies", {
-        title: "Search companies",
-        description: "Find companies by partial name or ticker on an exchange and return best matches",
-        inputSchema: {
-            stockExchange: exchangeSchema,
-            ...dateSchema,
-            query: z
-                .string()
-                .describe("Search term (partial ticker or company name)"),
-            limit: z
-                .number()
-                .int()
-                .min(1)
-                .max(50)
-                .default(10)
-                .describe("Maximum results"),
-        },
-    }, async ({ stockExchange, year, month, day, query, limit, }) => {
+    server.registerTool("search_exchange_companies", {
+        title: "Search companies by name or ticker",
+        description: "Search for companies on a specific exchange by partial ticker symbol or company name. Results are ranked by relevance using ticker and name similarity.",
+        inputSchema: searchCompaniesSchema.shape,
+    }, async (input) => {
         try {
-            const formattedDate = getDate(year, month, day);
-            const marketDataResponse = await fetchMarketData(stockExchange, formattedDate);
-            const searchTerm = query.toLowerCase();
-            const matches = marketDataResponse.securities.data
-                .filter((item) => item[INDICES.TYPE] !== "sector" && item[INDICES.SECTOR])
-                .map((item) => ({
-                ticker: item[INDICES.TICKER],
-                name: item[INDICES.NAME_ENG],
-                sector: item[INDICES.SECTOR],
-                score: calculateMatchScore(item[INDICES.TICKER], item[INDICES.NAME_ENG], searchTerm),
-            }))
-                .filter((match) => match.score > 0)
-                .sort((a, b) => b.score - a.score)
-                .slice(0, limit);
-            return createResponse({
-                info: INFO,
-                date: formattedDate,
-                exchange: stockExchange.toUpperCase(),
-                currency: EXCHANGE_INFO[stockExchange].currency,
-                query,
-                matches,
-            });
+            return createResponse(await searchCompanies(searchCompaniesSchema.parse(input)));
         }
         catch (error) {
             return createErrorResponse(error);
         }
     });
-    server.registerTool("get_market_overview", {
-        title: "Market overview",
-        description: "Get total market cap, volume, value, and performance for an exchange on a specific date with a sector breakdown.",
-        inputSchema: { stockExchange: exchangeSchema, ...dateSchema },
-    }, async ({ stockExchange, year, month, day, }) => {
+    server.registerTool("analyze_market_overview", {
+        title: "Analyze market overview",
+        description: "Return aggregated statistics for a stock exchange on a specific date, including total market capitalization, trading volume, total traded value, number of trades, and sector-level market breakdown.",
+        inputSchema: marketOverviewSchema.shape,
+    }, async (input) => {
         try {
-            const formattedDate = getDate(year, month, day);
-            const marketDataResponse = await fetchMarketData(stockExchange, formattedDate);
-            const sectorItems = marketDataResponse.securities.data.filter((item) => item[INDICES.TYPE] === "sector");
-            let marketTotal = {};
-            const sectors = [];
-            sectorItems.forEach((item) => {
-                const sectorData = {
-                    name: item[INDICES.TICKER],
-                    marketCap: item[INDICES.MARKET_CAP],
-                    marketCapChangePct: item[INDICES.PRICE_CHANGE_PCT],
-                    volume: item[INDICES.VOLUME],
-                    value: item[INDICES.VALUE],
-                    numTrades: item[INDICES.NUM_TRADES],
-                    itemsPerSector: item[INDICES.ITEMS_PER_SECTOR],
-                };
-                if (item[INDICES.SECTOR] === "") {
-                    marketTotal = sectorData;
-                }
-                else {
-                    sectors.push(sectorData);
-                }
-            });
-            return createResponse({
-                info: INFO,
-                charts: createCharts(stockExchange, formattedDate),
-                date: formattedDate,
-                exchange: stockExchange.toUpperCase(),
-                currency: EXCHANGE_INFO[stockExchange].currency,
-                marketTotal,
-                sectors,
-            });
+            return createResponse(await getMarketOverview(marketOverviewSchema.parse(input)));
         }
         catch (error) {
             return createErrorResponse(error);
         }
     });
-    server.registerTool("get_sectors_overview", {
-        title: "Sector performance",
-        description: "Get aggregated performance metrics by sector for an exchange on a specific date.",
-        inputSchema: {
-            stockExchange: exchangeSchema,
-            ...dateSchema,
-            sector: z
-                .string()
-                .optional()
-                .describe("Get data for specific sector only"),
-        },
-    }, async ({ stockExchange, year, month, day, sector, }) => {
+    server.registerTool("analyze_sector_performance", {
+        title: "Analyze sector performance",
+        description: "Return aggregated metrics for each sector in a stock exchange, including sector market capitalization, price change percentage, trading volume, traded value, number of trades, and number of companies in the sector. Optionally filter for a single sector.",
+        inputSchema: sectorsOverviewSchema.shape,
+    }, async (input) => {
         try {
-            const formattedDate = getDate(year, month, day);
-            const marketDataResponse = await fetchMarketData(stockExchange, formattedDate);
-            const sectors = marketDataResponse.securities.data
-                .filter((item) => item[INDICES.TYPE] === "sector" && item[INDICES.SECTOR] !== "")
-                .filter((item) => !sector || item[INDICES.TICKER] === sector)
-                .map((item) => ({
-                name: item[INDICES.TICKER],
-                marketCap: item[INDICES.MARKET_CAP],
-                marketCapChangePct: item[INDICES.PRICE_CHANGE_PCT],
-                volume: item[INDICES.VOLUME],
-                value: item[INDICES.VALUE],
-                numTrades: item[INDICES.NUM_TRADES],
-                itemsPerSector: item[INDICES.ITEMS_PER_SECTOR],
-            }));
-            return createResponse({
-                info: INFO,
-                charts: createCharts(stockExchange, formattedDate),
-                date: formattedDate,
-                exchange: stockExchange.toUpperCase(),
-                currency: EXCHANGE_INFO[stockExchange].currency,
-                sectors,
-            });
+            return createResponse(await getSectorsOverview(sectorsOverviewSchema.parse(input)));
         }
         catch (error) {
             return createErrorResponse(error);
         }
     });
-    server.registerTool("get_stock_data", {
-        title: "Stock data by ticker",
-        description: "Get detailed market data for a specific ticker on an exchange and date, including price, change, volume, value, market cap, and trades.",
-        inputSchema: {
-            stockExchange: exchangeSchema,
-            ...dateSchema,
-            ticker: z.string().describe("Stock ticker symbol (case-sensitive)"),
-        },
-    }, async ({ stockExchange, year, month, day, ticker, }) => {
+    server.registerTool("get_stock_snapshot", {
+        title: "Get stock market snapshot",
+        description: "Return detailed trading metrics for a single stock ticker on a specific exchange and trading date, including price open, last sale price, price change percentage, trading volume, traded value, number of trades, and market capitalization.",
+        inputSchema: stockDataSchema.shape,
+    }, async (input) => {
         try {
-            const formattedDate = getDate(year, month, day);
-            const marketDataResponse = await fetchMarketData(stockExchange, formattedDate);
-            const stockData = marketDataResponse.securities.data.find((item) => item[INDICES.TYPE] !== "sector" && item[INDICES.TICKER] === ticker);
-            if (!stockData) {
-                throw new Error(`Ticker ${ticker} not found on ${stockExchange} for date ${formattedDate}`);
-            }
-            return createResponse({
-                info: INFO,
-                charts: createCharts(stockExchange, formattedDate),
-                exchange: stockData[INDICES.EXCHANGE],
-                country: stockData[INDICES.COUNTRY],
-                currency: EXCHANGE_INFO[stockExchange].currency,
-                sector: stockData[INDICES.SECTOR],
-                ticker: stockData[INDICES.TICKER],
-                nameEng: stockData[INDICES.NAME_ENG],
-                nameOriginal: stockData[INDICES.NAME_ORIGINAL],
-                priceOpen: stockData[INDICES.PRICE_OPEN],
-                priceLastSale: stockData[INDICES.PRICE_LAST_SALE],
-                priceChangePct: stockData[INDICES.PRICE_CHANGE_PCT],
-                volume: stockData[INDICES.VOLUME],
-                value: stockData[INDICES.VALUE],
-                numTrades: stockData[INDICES.NUM_TRADES],
-                marketCap: stockData[INDICES.MARKET_CAP],
-                listedFrom: stockData[INDICES.LISTED_FROM],
-                listedTill: stockData[INDICES.LISTED_TILL],
-            });
+            return createResponse(await getStockData(stockDataSchema.parse(input)));
         }
         catch (error) {
             return createErrorResponse(error);
         }
     });
-    server.registerTool("rank_stocks", {
-        title: "Rank stocks",
-        description: "Rank stocks on an exchange by a chosen metric (marketCap, priceChangePct, volume, value, numTrades) for a specific date with order and limit.",
-        inputSchema: {
-            stockExchange: exchangeSchema,
-            ...dateSchema,
-            sortBy: z
-                .enum(SORT_FIELDS)
-                .describe("Sort by: marketCap, priceChangePct, volume, value, numTrades"),
-            order: z
-                .enum(SORT_ORDERS)
-                .default("desc")
-                .describe("Sort order: asc or desc"),
-            limit: z
-                .number()
-                .int()
-                .min(1)
-                .max(500)
-                .default(10)
-                .describe("Number of results"),
-            sector: z.string().optional().describe("Filter by specific sector"),
-        },
-    }, async ({ stockExchange, year, month, day, sortBy, order, limit, sector, }) => {
+    server.registerTool("rank_exchange_companies", {
+        title: "Rank companies by market metric",
+        description: "Return companies ranked by a selected market metric on a specific exchange and date. Supported metrics: market capitalization, price change percentage, trading volume, traded value, and number of trades. Results can be limited and optionally filtered by sector.",
+        inputSchema: rankStocksSchema.shape,
+    }, async (input) => {
         try {
-            const formattedDate = getDate(year, month, day);
-            const marketDataResponse = await fetchMarketData(stockExchange, formattedDate);
-            const stocks = marketDataResponse.securities.data
-                .filter((item) => item[INDICES.TYPE] !== "sector" && item[INDICES.SECTOR] !== "")
-                .filter((item) => !sector || item[INDICES.SECTOR] === sector)
-                .map((item) => ({
-                ticker: item[INDICES.TICKER],
-                name: item[INDICES.NAME_ENG],
-                sector: item[INDICES.SECTOR],
-                priceLastSale: item[INDICES.PRICE_LAST_SALE],
-                priceChangePct: item[INDICES.PRICE_CHANGE_PCT],
-                marketCap: item[INDICES.MARKET_CAP],
-                volume: item[INDICES.VOLUME],
-                value: item[INDICES.VALUE],
-                numTrades: item[INDICES.NUM_TRADES],
-            }))
-                .sort((a, b) => {
-                const aVal = a[sortBy], bVal = b[sortBy];
-                return order === "desc" ? bVal - aVal : aVal - bVal;
-            })
-                .slice(0, limit);
-            return createResponse({
-                info: INFO,
-                charts: createCharts(stockExchange, formattedDate),
-                date: formattedDate,
-                exchange: stockExchange.toUpperCase(),
-                currency: EXCHANGE_INFO[stockExchange].currency,
-                sortBy,
-                order,
-                limit,
-                count: stocks.length,
-                stocks,
-            });
+            return createResponse(await rankStocks(rankStocksSchema.parse(input)));
         }
         catch (error) {
             return createErrorResponse(error);
         }
     });
-    server.registerTool("get_company_profile", {
-        title: "Company profile (US)",
-        description: "Get business description, industry, and background for a US-listed company by ticker.",
-        inputSchema: {
-            exchange: z
-                .enum(US_EXCHANGES)
-                .describe("US exchange: amex, nasdaq, nyse"),
-            ticker: z.string().describe("Stock ticker symbol (case-sensitive)"),
-        },
-    }, async ({ exchange, ticker }) => {
+    server.registerTool("get_company_profile_us", {
+        title: "Get US company profile",
+        description: "Return business description and background information for a US-listed company by ticker. Supported exchanges: NASDAQ, NYSE, and AMEX.",
+        inputSchema: companyProfileSchema.shape,
+    }, async (input) => {
         try {
-            const securityInfo = await fetchSecurityInfo(exchange, ticker);
-            return createResponse({
-                info: INFO,
-                charts: createCharts(exchange),
-                ...securityInfo,
-            });
+            return createResponse(await getCompanyProfile(companyProfileSchema.parse(input)));
         }
         catch (error) {
             return createErrorResponse(error);

package/dist/stdio-server.js

@@ -4,7 +4,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 const server = new McpServer({
     name: "finmap-mcp",
-    version: "2.0.8",
+    version: "3.0.0",
 });
 registerFinmapTools(server);
 const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "finmap-mcp",
-	"version": "2.0.8",
+	"version": "3.0.0",
 	"description": "MCP server providing financial market data from finmap.org",
 	"main": "./dist/stdio-server.js",
 	"type": "module",
@@ -73,15 +73,15 @@
 		"package": "npm run build:stdio && npm pack --pack-destination dist"
 	},
 	"dependencies": {
-		"agents": "^0.7.5",
+		"agents": "^0.7.6",
 		"zod": "^4.3.6"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.4.6",
-		"@types/node": "^25.3.5",
+		"@biomejs/biome": "^2.4.7",
+		"@types/node": "^25.5.0",
 		"rimraf": "^6.1.3",
 		"tsx": "^4.21.0",
 		"typescript": "5.9.3",
-		"wrangler": "^4.71.0"
+		"wrangler": "^4.74.0"
 	}
 }