Finmap MCP Server

Instructions

Implementation Reference

• src/core.ts:490-545 (handler)

  The handler function for the 'get_market_overview' tool. It fetches market data for the given exchange and date, filters sector items, aggregates market totals and sector metrics (marketCap, volume, value, numTrades, change %), and returns a formatted response including charts links.

  async ({
  	stockExchange,
  	year,
  	month,
  	day,
  }: {
  	stockExchange: StockExchange;
  	year?: number;
  	month?: number;
  	day?: number;
  }) => {
  	try {
  		const formattedDate = getDate(year, month, day);
  		const marketDataResponse = await fetchMarketData(
  			stockExchange,
  			formattedDate,
  		);
  
  		const sectorItems = marketDataResponse.securities.data.filter(
  			(item: any) => item[INDICES.TYPE] === "sector",
  		);
  
  		let marketTotal = {};
  		const sectors: any[] = [];
  
  		sectorItems.forEach((item: any) => {
  			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 as StockExchange].currency,
  			marketTotal,
  			sectors,
  		});
  	} catch (error) {
  		return createErrorResponse(error);
  	}
  },

• src/core.ts:484-489 (schema)

  Input schema and metadata (title, description) for the 'get_market_overview' tool, referencing shared exchangeSchema and dateSchema.

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

• src/core.ts:482-546 (registration)

  The server.registerTool call that registers the 'get_market_overview' tool within the registerFinmapTools function.

  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,
  	}: {
  		stockExchange: StockExchange;
  		year?: number;
  		month?: number;
  		day?: number;
  	}) => {
  		try {
  			const formattedDate = getDate(year, month, day);
  			const marketDataResponse = await fetchMarketData(
  				stockExchange,
  				formattedDate,
  			);
  
  			const sectorItems = marketDataResponse.securities.data.filter(
  				(item: any) => item[INDICES.TYPE] === "sector",
  			);
  
  			let marketTotal = {};
  			const sectors: any[] = [];
  
  			sectorItems.forEach((item: any) => {
  				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 as StockExchange].currency,
  				marketTotal,
  				sectors,
  			});
  		} catch (error) {
  			return createErrorResponse(error);
  		}
  	},
  );

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

  Helper function fetchMarketData used by the handler to retrieve market data JSON from GitHub for the specified exchange and 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();
  }