Finmap MCP Server

Instructions

Implementation Reference

• src/core.ts:625-680 (handler)

  Handler function that implements the core logic of 'get_stock_data': fetches market data for the exchange and date, searches for the specific ticker, extracts and returns detailed stock metrics like price, change percentage, volume, market cap, etc.

  	async ({
  		stockExchange,
  		year,
  		month,
  		day,
  		ticker,
  	}: {
  		stockExchange: StockExchange;
  		year?: number;
  		month?: number;
  		day?: number;
  		ticker: string;
  	}) => {
  		try {
  			const formattedDate = getDate(year, month, day);
  			const marketDataResponse = await fetchMarketData(
  				stockExchange,
  				formattedDate,
  			);
  
  			const stockData = marketDataResponse.securities.data.find(
  				(item: any[]) =>
  					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 as 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],
  			});
  		} catch (error) {
  			return createErrorResponse(error);
  		}
  	},
  );

• src/core.ts:615-624 (schema)

  Input schema for the 'get_stock_data' tool, defining parameters: stockExchange (enum), optional date components (year, month, day), and required ticker string.

  {
  	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)"),
  	},
  },

• src/core.ts:613-680 (registration)

  Registration of the 'get_stock_data' tool via server.registerTool, including name, metadata/schema, and handler function.

  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,
  	}: {
  		stockExchange: StockExchange;
  		year?: number;
  		month?: number;
  		day?: number;
  		ticker: string;
  	}) => {
  		try {
  			const formattedDate = getDate(year, month, day);
  			const marketDataResponse = await fetchMarketData(
  				stockExchange,
  				formattedDate,
  			);
  
  			const stockData = marketDataResponse.securities.data.find(
  				(item: any[]) =>
  					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 as 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],
  			});
  		} catch (error) {
  			return createErrorResponse(error);
  		}
  	},
  );

• src/core.ts:219-235 (helper)

  Key helper function used by the handler to fetch the market data JSON from GitHub raw for the given exchange and formatted date.

  async function fetchMarketData(
  	stockExchange: StockExchange,
  	formattedDate: string,
  ): Promise<{ securities: { data: any[][] } }> {
  	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();
  }