Finmap MCP Server

Instructions

Implementation Reference

• src/core.ts:342-402 (handler)

  The main handler function for the 'list_tickers' tool. It fetches market data for the specified exchange and date, filters by optional sector, groups companies by sector with their tickers and names (English or original), sorts tickers alphabetically within each sector, and returns a formatted JSON response.

  async ({
  	stockExchange,
  	year,
  	month,
  	day,
  	sector,
  	englishNames,
  }: {
  	stockExchange: StockExchange;
  	year?: number;
  	month?: number;
  	day?: number;
  	sector?: string;
  	englishNames?: boolean;
  }) => {
  	try {
  		const formattedDate = getDate(year, month, day);
  		const marketDataResponse = await fetchMarketData(
  			stockExchange,
  			formattedDate,
  		);
  
  		const sectorGroups: Record<
  			string,
  			Array<{ ticker: string; name: string }>
  		> = {};
  
  		marketDataResponse.securities.data.forEach((item: any[]) => {
  			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 as StockExchange].currency,
  			sectors: sectorGroups,
  		});
  	} catch (error) {
  		return createErrorResponse(error);
  	}
  },

• src/core.ts:328-341 (schema)

  The schema definition for the 'list_tickers' tool, including title, description, and Zod-based input schema for parameters like stockExchange, date components, optional sector filter, and englishNames flag.

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

• src/core.ts:326-403 (registration)

  The direct registration of the 'list_tickers' tool via server.registerTool within the registerFinmapTools function.

  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,
  	}: {
  		stockExchange: StockExchange;
  		year?: number;
  		month?: number;
  		day?: number;
  		sector?: string;
  		englishNames?: boolean;
  	}) => {
  		try {
  			const formattedDate = getDate(year, month, day);
  			const marketDataResponse = await fetchMarketData(
  				stockExchange,
  				formattedDate,
  			);
  
  			const sectorGroups: Record<
  				string,
  				Array<{ ticker: string; name: string }>
  			> = {};
  
  			marketDataResponse.securities.data.forEach((item: any[]) => {
  				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 as StockExchange].currency,
  				sectors: sectorGroups,
  			});
  		} catch (error) {
  			return createErrorResponse(error);
  		}
  	},
  );

• src/index.ts:12-12 (registration)

  Invocation of registerFinmapTools in the FinmapMcpServer class init method, which registers all tools including list_tickers.

  registerFinmapTools(this.server);

• src/stdio-server.ts:11-11 (registration)

  Invocation of registerFinmapTools on the MCP server for stdio transport, registering the list_tickers tool.

  registerFinmapTools(server);