npm - finmap-mcp - Versions diffs - 1.1.0 → 1.1.2 - Mend

finmap-mcp 1.1.0 → 1.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -60,249 +60,501 @@ npx finmap-mcp
 ## Available Tools
-### 1. `get-marketdata`
-Get market overview with sector breakdown for any exchange.
+### 1. `list_exchanges`
+  - Title: List exchanges
+  - Description: Return supported exchanges with IDs, names, country, currency, earliest available date, and update frequency.
-**Parameters:**
-- `stockExchange`: `"moex" | "nyse" | "nasdaq" | "amex" | "lse" | "bist" | "us-all"`
-- `year`, `month`, `day` (optional): Specific date, defaults to latest
+  **Example Promt:** `#finmap-mcp list available stock exchanges`
-**Example Response:**
-```json
-{
-  "date": "2025-08-19",
-  "exchange": "MOEX",
-  "marketTotal": {
-    "name": "Moscow Exchange",
-    "marketCap": 56179679584186.7,
-    "marketCapChangePct": -0.62,
-    "volume": 31210807020,
-    "value": 138591002400,
-    "numTrades": 3433146,
-    "itemsPerSector": 460
-  },
-  "sectors": [
-    {
-      "name": "Finance",
-      "marketCap": 11302744020274.61,
-      "marketCapChangePct": -0.41,
-      "volume": 246255138,
-      "value": 30553933296,
-      "numTrades": 465750,
-      "itemsPerSector": 30
-    }
-  ],
-  "charts": {
-    "histogram": "https://finmap.org/?chartType=histogram&dataType=marketcap&exchange=moex",
-    "treemap": "https://finmap.org/?chartType=treemap&dataType=marketcap&exchange=moex&date=2025-08-19"
+  **Example Response:**
+  ```json
+  {
+    "exchanges": [
+      {
+        "id": "amex",
+        "name": "American Stock Exchange",
+        "country": "United States",
+        "currency": "USD",
+        "availableSince": "2024-12-09",
+        "updateFrequency": "Hourly (weekdays)"
+      },
+      {
+        "id": "nasdaq",
+        "name": "NASDAQ Stock Market",
+        "country": "United States",
+        "currency": "USD",
+        "availableSince": "2024-12-09",
+        "updateFrequency": "Hourly (weekdays)"
+      },
+      {
+        "id": "nyse",
+        "name": "New York Stock Exchange",
+        "country": "United States",
+        "currency": "USD",
+        "availableSince": "2024-12-09",
+        "updateFrequency": "Hourly (weekdays)"
+      },
+      {
+        "id": "us-all",
+        "name": "US Combined (AMEX + NASDAQ + NYSE)",
+        "country": "United States",
+        "currency": "USD",
+        "availableSince": "2024-12-09",
+        "updateFrequency": "Hourly (weekdays)"
+      },
+      {
+        "id": "lse",
+        "name": "London Stock Exchange",
+        "country": "United Kingdom",
+        "currency": "GBP",
+        "availableSince": "2025-02-07",
+        "updateFrequency": "Hourly (weekdays)"
+      },
+      {
+        "id": "moex",
+        "name": "Moscow Exchange",
+        "country": "Russia",
+        "currency": "RUB",
+        "availableSince": "2011-12-19",
+        "updateFrequency": "Every 15 minutes (weekdays)"
+      },
+      {
+        "id": "bist",
+        "name": "Borsa Istanbul",
+        "country": "Turkey",
+        "currency": "TRY",
+        "availableSince": "2015-11-30",
+        "updateFrequency": "Every two months"
+      }
+    ]
   }
-}
-```
-### 2. `get-tickers`
-List all available company tickers for an exchange with optional sector filtering.
-**Parameters:**
-- `stockExchange`: Exchange identifier
-- `englishNames`: `true` (default) | `false` - Use English or original company names
-- `sector` (optional): Filter by specific sector
-### 3. `get-marketdata-by-ticker`
-Get detailed information for a specific company ticker.
-**Parameters:**
-- `stockExchange`: Exchange identifier
-- `ticker`: Company ticker symbol (case-sensitive)
-- `year`, `month`, `day` (optional): Historical date
-**Example Response:**
-```json
-{
-  "exchange": "MOEX",
-  "country": "",
-  "type": "",
-  "sector": "Finance",
-  "industry": "",
-  "currencyId": "",
-  "ticker": "T",
-  "nameEng": "IPJSC TCS Holding",
-  "nameEngShort": "",
-  "nameOriginal": "ТКС Холдинг МКПАО ао",
-  "nameOriginalShort": "ТКСХолд ао",
-  "priceOpen": 3406.2,
-  "priceLastSale": 3404.8,
-  "priceChangePct": -0.04,
-  "volume": 3720294,
-  "value": 12722573698,
-  "numTrades": 96979,
-  "marketCap": 914012195902,
-  "listedFrom": "2024-11-27",
-  "listedTill": "",
-  "wikiPageIdEng": "51138388\r",
-  "wikiPageIdOriginal": "3124277",
-  "itemsPerSector": 0
-}
-```
-### 4. `get-top-marketdata`
-Get top performing companies sorted by various metrics.
-**Parameters:**
-- `stockExchange`: Exchange identifier
-- `sortBy`: `"marketCap" | "priceChangePct" | "volume" | "value" | "numTrades"`
-- `order`: `"desc" | "asc"` (default: desc)
-- `limit`: Number of results (1-500, default: 10)
+  ```
-**Example Response:**
+### 2. `list_sectors`
+  - Title: List sectors
+  - Description: List available business sectors for an exchange on a specific date, including item counts.
-```json
-{
-  "date": "2025-08-19",
-  "exchange": "NASDAQ",
-  "sortBy": "marketCap",
-  "order": "desc",
-  "limit": 3,
-  "count": 3,
-  "filteredSecurities": [
-    {
-      "ticker": "NVDA",
-      "name": "NVIDIA Corporation Common Stock",
-      "sector": "Technology",
-      "priceLastSale": 175.64,
-      "priceChangePct": -3.5,
-      "marketCap": 4285616000000,
-      "volume": 183881555,
-      "value": 0,
-      "numTrades": 0
-    },
-    {
-      "ticker": "MSFT",
-      "name": "Microsoft Corporation Common Stock",
-      "sector": "Technology",
-      "priceLastSale": 509.77,
-      "priceChangePct": -1.418,
-      "marketCap": 3789205225023,
-      "volume": 21116203,
-      "value": 0,
-      "numTrades": 0
-    },
-    {
-      "ticker": "AAPL",
-      "name": "Apple Inc. Common Stock",
-      "sector": "Technology",
-      "priceLastSale": 230.56,
-      "priceChangePct": -0.143,
-      "marketCap": 3421600318400,
-      "volume": 37671194,
-      "value": 0,
-      "numTrades": 0
-    }
-  ]
-}
-```
-### 5. `get-company-info`
-Get detailed company information including business description (US market only).
-**Parameters:**
-- `stockExchange`: `"nasdaq" | "nyse" | "amex"`
-- `ticker`: Company ticker symbol
+  **Example Promt:** `#finmap-mcp List sectors for the Turkish stock exchange`
+  **Example Response:**
+  ```json
+  {
+    "date": "2024-08-28",
+    "exchange": "BIST",
+    "currency": "TRY",
+    "sectors": [
+      {
+        "name": "Finance",
+        "itemsPerSector": 164
+      },
+      {
+        "name": "MSPOTECW",
+        "itemsPerSector": 4669
+      },
+      {
+        "name": "MSPOTEPW",
+        "itemsPerSector": 3335
+      },
+      {
+        "name": "Industrials",
+        "itemsPerSector": 277
+      },
+      {
+        "name": "MSPOTXCR",
+        "itemsPerSector": 2
+      },
+      {
+        "name": "Real Estate",
+        "itemsPerSector": 4
+      },
+      {
+        "name": "Agriculture",
+        "itemsPerSector": 5
+      },
+      {
+        "name": "Utilities",
+        "itemsPerSector": 32
+      },
+      {
+        "name": "MSPOTGMF",
+        "itemsPerSector": 9
+      },
+      {
+        "name": "Technology",
+        "itemsPerSector": 39
+      },
+      {
+        "name": "Basic Materials",
+        "itemsPerSector": 7
+      },
+      {
+        "name": "MSPOTEMS",
+        "itemsPerSector": 1
+      },
+      {
+        "name": "MSPOTETF",
+        "itemsPerSector": 21
+      },
+      {
+        "name": "MSPOTGSF",
+        "itemsPerSector": 8
+      },
+      {
+        "name": "Consumer Staples",
+        "itemsPerSector": 27
+      },
+      {
+        "name": "Consumer Discretionary",
+        "itemsPerSector": 14
+      },
+      {
+        "name": "Health Care",
+        "itemsPerSector": 9
+      },
+      {
+        "name": "Miscellaneous",
+        "itemsPerSector": 13
+      },
+      {
+        "name": "Telecommunications",
+        "itemsPerSector": 7
+      },
+      {
+        "name": "MSPOTEQT",
+        "itemsPerSector": 4
+      }
+    ]
+  }
+  ```
-**Example Response:**
+### 3. `list_tickers`
+  - Title: List tickers by sector
+  - Description: Return company tickers and names for an exchange on a specific date, grouped by sector.
-```json
-{
+  **Example Promt:** `#finmap-mcp List companies in the Real Estate sector`
+  **Example Response:**
+  ```json
   {
-    "ModuleTitle": {
-      "label": "Module Title",
-      "value": "Company Description"
-    },
-    "CompanyName": {
-      "label": "Company Name",
-      "value": "Sprouts Farmers Market, Inc."
-    },
-    "Symbol": {
-      "label": "Symbol",
-      "value": "SFM"
-    },
-    "Address": {
-      "label": "Address",
-      "value": "5455 EAST HIGH STREET,SUITE 111, PHOENIX, Arizona, 85054, United States"
-    },
-    "Phone": {
-      "label": "Phone",
-      "value": "+1 480 814-8016"
-    },
-    "Industry": {
-      "label": "Industry",
-      "value": "Food Chains"
-    },
-    "Sector": {
-      "label": "Sector",
-      "value": "Consumer Staples"
-    },
-    "Region": {
-      "label": "Region",
-      "value": "North America"
-    },
-    "CompanyDescription": {
-      "label": "Company Description",
-      "value": "Sprouts Farmers Market is an American specialty grocer offering an assortment highlighting fresh and naturally derived products. Its offerings are especially focused on produce, which constituted around 21% of sales in fiscal 2021. Founded in 2002, the chain is most heavily concentrated in California, which accounted for over one third of its 374 stores as of the end of fiscal 2021. All of the company's operations are in the United States, with its stores largely located in the southern half of the country. The firm sells roughly 20,000 products (of which around 70% are attribute driven, such as organic, plant-based, or catering to the keto or paleo diet), with private-label products accounting for about 16% of sales in fiscal 2021. Perishable items accounted for 58% of fiscal 2021 sales."
-    },
-    "CompanyUrl": {
-      "label": "Company Url",
-      "value": "https://www.sprouts.com"
-    },
-    "KeyExecutives": {
-      "label": "Key Executives",
-      "value": [
+    "date": "2024-08-28",
+    "exchange": "BIST",
+    "currency": "TRY",
+    "sectors": {
+      "Real Estate": [
+        {
+          "ticker": "ADESE.E",
+          "name": "ADESE GAYRIMENKUL"
+        },
         {
-          "name": "Jack Loudon Sinclair",
-          "title": "Chief Executive Officer & Director"
+          "ticker": "IHLGM.E",
+          "name": "IHLAS GAYRIMENKUL"
         },
         {
-          "name": "James Bahrenburg",
-          "title": "Chief Technology Officer"
+          "ticker": "RGYAS.E",
+          "name": "RONESANS GAYRIMENKUL YAT."
         },
         {
-          "name": "Nicholas Konat",
-          "title": "President & Chief Operating Officer"
+          "ticker": "SONME.E",
+          "name": "SONMEZ FILAMENT"
         }
       ]
     }
-  },
-  "message": null,
-  "status": {
-    "rCode": 200,
-    "bCodeMessage": null,
-    "developerMessage": null
   }
-}
-```
+  ```
-## Example Prompts
+### 4. `search_companies`
+  - Title: Search companies
+  - Description: Find companies by partial name or ticker on an exchange and return best matches.
-### Market Analysis
-> "Get the current market data for MOEX and show me the top 3 sectors by market cap"
+  **Example Promt:** `#finmap-mcp Search for companies named 'Sprouts'`
-> "Compare the top 10 companies by market cap on NYSE vs NASDAQ"
+  **Example Response:**
+  ```json
+  {
+    "date": "2025-08-28",
+    "exchange": "NASDAQ",
+    "currency": "USD",
+    "query": "Sprouts",
+    "matches": [
+      {
+        "ticker": "SFM",
+        "name": "Sprouts Farmers Market Inc. Common Stock",
+        "sector": "Consumer Staples",
+        "score": 70
+      }
+    ]
+  }
+  ```
-> "Show me all energy sector companies on MOEX with their current prices"
+### 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.
-### Historical Data
-> "Get GAZP stock data for December 15, 2024"
+  **Example Promt:** `#finmap-mcp market overview for Nasdaq`
+  **Example Response:**
+  ```json
+  {
+    "date": "2025-08-28",
+    "exchange": "NASDAQ",
+    "currency": "USD",
+    "marketTotal": {
+      "name": "Market",
+      "marketCap": 41238186996017,
+      "marketCapChangePct": 0.6213636439596683,
+      "volume": 7606048313,
+      "value": 0,
+      "numTrades": 0,
+      "itemsPerSector": 7974
+    },
+    "sectors": [
+      {
+        "name": "Basic Materials",
+        "marketCap": 248122454077,
+        "marketCapChangePct": -0.19965738920998274,
+        "volume": 40489423,
+        "value": 0,
+        "numTrades": 0,
+        "itemsPerSector": 36
+      },
+      {
+        "name": "Consumer Discretionary",
+        "marketCap": 5313249666194,
+        "marketCapChangePct": 0.5556221951442668,
+        "volume": 1029152348,
+        "value": 0,
+        "numTrades": 0,
+        "itemsPerSector": 580
+      },
+      {
+        "name": "ETFS",
+        "marketCap": 0,
+        "marketCapChangePct": null,
+        "volume": 0,
+        "value": 0,
+        "numTrades": 0,
+        "itemsPerSector": 3976
+      },
+      ...
+      {
+        "name": "Utilities",
+        "marketCap": 333109407104,
+        "marketCapChangePct": -0.1881153782118469,
+        "volume": 39232326,
+        "value": 0,
+        "numTrades": 0,
+        "itemsPerSector": 48
+      }
+    ]
+  }
+  ```
+### 6. `get_sectors_overview`
+  - Title: Sector performance
+  - Description: Get aggregated performance metrics by sector for an exchange on a specific date.
+  **Example Promt:** `#finmap-mcp Get overview for the Utilities sector`
+  **Example Response:**
+  ```json
+  {
+    "date": "2025-08-28",
+    "exchange": "NASDAQ",
+    "currency": "USD",
+    "sectors": [
+      {
+        "name": "Utilities",
+        "marketCap": 333109407104,
+        "marketCapChangePct": -0.1881153782118469,
+        "volume": 39232326,
+        "value": 0,
+        "numTrades": 0,
+        "itemsPerSector": 48
+      }
+    ]
+  }
+  ```
+### 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.
-> "Show me the market performance of BIST for the last trading day of 2024"
+  **Example Promt:** `#finmap-mcp Dominion Energy, stock data`
+  **Example Response:**
+  ```json
+  {
+    "exchange": "nyse",
+    "country": "United States",
+    "currency": "USD",
+    "sector": "Utilities",
+    "ticker": "D",
+    "nameEng": "Dominion Energy Inc. Common Stock",
+    "nameOriginal": "",
+    "priceOpen": 60.34,
+    "priceLastSale": 59.81,
+    "priceChangePct": -0.878,
+    "volume": 3771759,
+    "value": 0,
+    "numTrades": 0,
+    "marketCap": 51043865111,
+    "listedFrom": "",
+    "listedTill": ""
+  }
+  ```
-### Sector Research
-> "List all technology companies on NASDAQ and sort them by trading volume"
+### 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.
-> "Get detailed information about Apple (AAPL) including company description"
+  **Example Promt:** `#finmap-mcp UK, rank stocks by market cap`
+  **Example Response:**
+  ```json
+  {
+    "date": "2025-08-28",
+    "exchange": "LSE",
+    "currency": "GBP",
+    "sortBy": "marketCap",
+    "order": "desc",
+    "limit": 5,
+    "count": 5,
+    "stocks": [
+      {
+        "ticker": "AZN",
+        "name": "ASTRAZENECA PLC ORD SHS $0.25",
+        "sector": "Health Care",
+        "priceLastSale": 11810,
+        "priceChangePct": -0.5557426743011115,
+        "marketCap": 184159063201,
+        "volume": 0,
+        "value": 0,
+        "numTrades": 0
+      },
+      {
+        "ticker": "HSBA",
+        "name": "HSBC HLDGS PLC ORD $0.50 (UK REG)",
+        "sector": "Finance",
+        "priceLastSale": 955.8,
+        "priceChangePct": 0.1676797317124293,
+        "marketCap": 165599631829,
+        "volume": 0,
+        "value": 0,
+        "numTrades": 0
+      },
+      {
+        "ticker": "SHEL",
+        "name": "SHELL PLC ORD EUR0.07",
+        "sector": "Energy",
+        "priceLastSale": 2715.5,
+        "priceChangePct": 0,
+        "marketCap": 158779785181,
+        "volume": 0,
+        "value": 0,
+        "numTrades": 0
+      },
+      {
+        "ticker": "ULVR",
+        "name": "UNILEVER PLC ORD 3 1/9P",
+        "sector": "Consumer Staples",
+        "priceLastSale": 4610,
+        "priceChangePct": -0.2812026822409691,
+        "marketCap": 113348756395,
+        "volume": 0,
+        "value": 0,
+        "numTrades": 0
+      },
+      {
+        "ticker": "BHP",
+        "name": "BHP GROUP LIMITED ORD NPV (DI)",
+        "sector": "Basic Materials",
+        "priceLastSale": 2073,
+        "priceChangePct": 0.6310679611650485,
+        "marketCap": 104611160052,
+        "volume": 0,
+        "value": 0,
+        "numTrades": 0
+      }
+    ]
+  }
+  ```
-### Interactive Exploration
-> "Show me a treemap visualization of MOEX market cap by sector"
+### 9. `get_company_profile`
+  - Title: Company profile (US)
+  - Description: Get business description, industry, and background for a US-listed company by ticker.
-> "Get the histogram view of market cap distribution for US markets"
+  **Example Promt:** `#finmap-mcp Sprouts Farmers Market, get company profile`
+  **Example Response:**
+  ```json
+  {
+    "data": {
+      "ModuleTitle": {
+        "label": "Module Title",
+        "value": "Company Description"
+      },
+      "CompanyName": {
+        "label": "Company Name",
+        "value": "Sprouts Farmers Market, Inc."
+      },
+      "Symbol": {
+        "label": "Symbol",
+        "value": "SFM"
+      },
+      "Address": {
+        "label": "Address",
+        "value": "5455 EAST HIGH STREET,SUITE 111, PHOENIX, Arizona, 85054, United States"
+      },
+      "Phone": {
+        "label": "Phone",
+        "value": "+1 480 814-8016"
+      },
+      "Industry": {
+        "label": "Industry",
+        "value": "Food Chains"
+      },
+      "Sector": {
+        "label": "Sector",
+        "value": "Consumer Staples"
+      },
+      "Region": {
+        "label": "Region",
+        "value": "North America"
+      },
+      "CompanyDescription": {
+        "label": "Company Description",
+        "value": "Sprouts Farmers Market is an American specialty grocer offering an assortment highlighting fresh and naturally derived products. Its offerings   are especially focused on produce, which constituted around 21% of sales in fiscal 2021. Founded in 2002, the chain is most heavily concentrated in   California, which accounted for over one third of its 374 stores as of the end of fiscal 2021. All of the company's operations are in the United States,   with its stores largely located in the southern half of the country. The firm sells roughly 20,000 products (of which around 70% are attribute driven,   such as organic, plant-based, or catering to the keto or paleo diet), with private-label products accounting for about 16% of sales in fiscal 2021.   Perishable items accounted for 58% of fiscal 2021 sales."
+      },
+      "CompanyUrl": {
+        "label": "Company Url",
+        "value": "https://www.sprouts.com"
+      },
+      "KeyExecutives": {
+        "label": "Key Executives",
+        "value": [
+          {
+            "name": "Jack Loudon Sinclair",
+            "title": "Chief Executive Officer & Director"
+          },
+          {
+            "name": "James Bahrenburg",
+            "title": "Chief Technology Officer"
+          },
+          {
+            "name": "Nicholas Konat",
+            "title": "President & Chief Operating Officer"
+          }
+        ]
+      }
+    },
+    "message": null,
+    "status": {
+      "rCode": 200,
+      "bCodeMessage": null,
+      "developerMessage": null
+    }
+  }
+  ```
 ## Data Provider

package/dist/core.js CHANGED Viewed

@@ -74,8 +74,8 @@ function createErrorResponse(error) {
 }
 function createCharts(exchange, date) {
     return {
-        histogram: `${BASE_URL}/?chartType=histogram&dataType=marketcap&exchange=${exchange}`,
-        treemap: `${BASE_URL}/?chartType=treemap&dataType=marketcap&exchange=${exchange}${date ? `&date=${date}` : ""}`,
+        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) {
@@ -224,7 +224,7 @@ export function registerFinmapTools(server) {
             });
             const sectors = Object.entries(sectorCounts).map(([name, count]) => ({
                 name,
-                count,
+                itemsPerSector: count,
             }));
             return createResponse({
                 info: INFO,

package/dist/stdio-server.js CHANGED Viewed

@@ -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: "1.1.0",
+    version: "1.1.2",
 });
 registerFinmapTools(server);
 const transport = new StdioServerTransport();

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
 	"name": "finmap-mcp",
-	"version": "1.1.0",
+	"version": "1.1.2",
 	"description": "MCP server providing financial market data from finmap.org",
 	"main": "./dist/stdio-server.js",
 	"type": "module",
@@ -73,7 +73,7 @@
 		"package": "npm run build:stdio && npm pack --pack-destination dist"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "1.17.4",
+		"@modelcontextprotocol/sdk": "1.17.5",
 		"agents": "^0.0.113",
 		"zod": "^3.25.76"
 	},
@@ -83,6 +83,6 @@
 		"rimraf": "^6.0.1",
 		"tsx": "^4.20.5",
 		"typescript": "5.9.2",
-		"wrangler": "^4.33.1"
+		"wrangler": "^4.33.2"
 	}
 }