Finmap MCP Server

Instructions

Implementation Reference

• src/core.ts:710-776 (handler)

  The handler function that executes the 'rank_stocks' tool logic: fetches market data, filters stocks by sector if specified, sorts by chosen metric and order, applies limit, and formats the response.

  	async ({
  		stockExchange,
  		year,
  		month,
  		day,
  		sortBy,
  		order,
  		limit,
  		sector,
  	}: {
  		stockExchange: StockExchange;
  		year?: number;
  		month?: number;
  		day?: number;
  		sortBy: SortField;
  		order?: SortOrder;
  		limit?: number;
  		sector?: string;
  	}) => {
  		try {
  			const formattedDate = getDate(year, month, day);
  			const marketDataResponse = await fetchMarketData(
  				stockExchange,
  				formattedDate,
  			);
  
  			const stocks = marketDataResponse.securities.data
  				.filter(
  					(item: any[]) =>
  						item[INDICES.TYPE] !== "sector" && item[INDICES.SECTOR] !== "",
  				)
  				.filter((item: any[]) => !sector || item[INDICES.SECTOR] === sector)
  				.map((item: any[]) => ({
  					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: any, b: any) => {
  					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 as StockExchange].currency,
  				sortBy,
  				order,
  				limit,
  				count: stocks.length,
  				stocks,
  			});
  		} catch (error) {
  			return createErrorResponse(error);
  		}
  	},
  );

• src/core.ts:688-708 (schema)

  Input schema for 'rank_stocks' tool using Zod-like validation for parameters: stockExchange, date components, sortBy (enum), order (default desc), limit (1-500, default 10), optional sector.

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

• src/core.ts:682-682 (registration)

  Registration of the 'rank_stocks' tool in the registerFinmapTools function using server.registerTool.

  server.registerTool(

• src/core.ts:31-37 (helper)

  Type definitions for sortable fields and orders used in the rank_stocks tool.

  const SORT_FIELDS = [
  	"priceChangePct",
  	"marketCap",
  	"value",
  	"volume",
  	"numTrades",
  ] as const;