company_performance_us
Retrieve comprehensive U.S. company performance data, including income statements, balance sheets, cash flow, and financial metrics, for informed investment decisions. Analyze specific periods or date ranges with ease.
Instructions
获取美股上市公司综合表现数据，包括利润表、资产负债表、现金流量表和财务指标数据
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data_type | Yes | 数据类型：income(利润表)、balance(资产负债表)、cashflow(现金流量表)、indicator(财务指标) | |
| end_date | Yes | 结束日期，格式为YYYYMMDD，如'20231231' | |
| period | No | 特定报告期，格式为YYYYMMDD，如'20231231'表示2023年年报。指定此参数时将忽略start_date和end_date | |
| start_date | Yes | 起始日期，格式为YYYYMMDD，如'20230101' | |
| ts_code | Yes | 美股代码，如'NVDA'表示英伟达，'AAPL'表示苹果，'TSLA'表示特斯拉 |
Implementation Reference
- The main execution handler for the 'company_performance_us' tool. Fetches US stock financial data (income, balance, cashflow, indicators) from Tushare API based on input parameters, applies appropriate formatters, and returns formatted markdown content or error.
async run(args: { ts_code: string; data_type: string; start_date: string; end_date: string; period?: string; }) { try { console.log('美股公司综合表现查询参数:', args); const TUSHARE_API_KEY = TUSHARE_CONFIG.API_TOKEN; const TUSHARE_API_URL = TUSHARE_CONFIG.API_URL; if (!TUSHARE_API_KEY) { throw new Error('请配置TUSHARE_TOKEN环境变量'); } // 根据data_type选择对应的接口 let apiInterface = ''; let formatFunction: any = null; switch (args.data_type) { case 'income': apiInterface = 'us_income'; formatFunction = formatUsIncomeData; break; case 'balance': apiInterface = 'us_balancesheet'; formatFunction = formatUsBalanceData; break; case 'cashflow': apiInterface = 'us_cashflow'; formatFunction = formatUsCashflowData; break; case 'indicator': apiInterface = 'us_fina_indicator'; formatFunction = formatUsIndicatorData; break; default: throw new Error(`不支持的数据类型: ${args.data_type}`); } const result = await fetchUsFinancialData( apiInterface, args.ts_code, args.period, args.start_date, args.end_date, TUSHARE_API_KEY, TUSHARE_API_URL ); if (!result.data || result.data.length === 0) { return { content: [ { type: "text", text: `# ${args.ts_code} 美股${getDataTypeName(args.data_type)}数据\n\n❌ 未找到相关数据，请检查股票代码或日期范围` } ] }; } // 使用对应的格式化函数 if (formatFunction) { const formattedResult = formatFunction(result.data, args.ts_code, args.data_type); return formattedResult; } else { // 如果没有实现格式化器，返回原始数据 return { content: [ { type: "text", text: `# ${args.ts_code} 美股${getDataTypeName(args.data_type)}数据\n\n⚠️ 格式化器待实现，以下为原始数据：\n\n${JSON.stringify(result.data, null, 2)}` } ] }; } } catch (error) { console.error('美股公司业绩查询错误:', error); return { content: [ { type: "text", text: `❌ 美股公司业绩查询失败: ${error instanceof Error ? error.message : String(error)}` } ], isError: true }; } } - Input schema defining parameters for the tool: ts_code (required stock code), data_type (enum: income/balance/cashflow/indicator), date ranges, and optional period.
parameters: { type: "object", properties: { ts_code: { type: "string", description: "美股代码，如'NVDA'表示英伟达，'AAPL'表示苹果，'TSLA'表示特斯拉" }, data_type: { type: "string", description: "数据类型：income(利润表)、balance(资产负债表)、cashflow(现金流量表)、indicator(财务指标)", enum: ["income", "balance", "cashflow", "indicator"] }, start_date: { type: "string", description: "起始日期，格式为YYYYMMDD，如'20230101'" }, end_date: { type: "string", description: "结束日期，格式为YYYYMMDD，如'20231231'" }, period: { type: "string", description: "特定报告期，格式为YYYYMMDD，如'20231231'表示2023年年报。指定此参数时将忽略start_date和end_date" } }, required: ["ts_code", "data_type", "start_date", "end_date"] }, - src/index.ts:338-345 (registration)Registration and dispatch in the stdio MCP server's CallToolRequestSchema handler, extracting args and calling the tool's run method.
case "company_performance_us": { const ts_code = String(request.params.arguments?.ts_code); const data_type = String(request.params.arguments?.data_type); const start_date = String(request.params.arguments?.start_date); const end_date = String(request.params.arguments?.end_date); const period = request.params.arguments?.period ? String(request.params.arguments.period) : undefined; return await companyPerformance_us.run({ ts_code, data_type, start_date, end_date, period }); } - src/httpServer.ts:337-344 (registration)Registration and dispatch in the HTTP MCP server's tools/call handler, extracting args and calling the tool's run method.
case 'company_performance_us': return await companyPerformance_us.run({ ts_code: String(args?.ts_code), data_type: String(args?.data_type), start_date: String(args?.start_date), end_date: String(args?.end_date), period: args?.period ? String(args.period) : undefined, }); - Helper function to make POST request to Tushare API for US financial data, handles params construction, response parsing, and converts array format to object array.
async function fetchUsFinancialData( apiInterface: string, ts_code: string, period?: string, start_date?: string, end_date?: string, apiKey?: string, apiUrl?: string ): Promise<any> { const requestData: any = { api_name: apiInterface, token: apiKey, params: { ts_code: ts_code } }; // 根据是否指定period来设置参数 if (period) { requestData.params.period = period; } else if (start_date && end_date) { requestData.params.start_date = start_date; requestData.params.end_date = end_date; } const response = await fetch(apiUrl!, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(requestData), signal: AbortSignal.timeout(TUSHARE_CONFIG.TIMEOUT) }); if (!response.ok) { throw new Error(`Tushare API请求失败: ${response.status} ${response.statusText}`); } const data = await response.json(); if (data.code !== 0) { throw new Error(`Tushare API错误: ${data.msg || '未知错误'}`); } // 将返回的数组格式转换为对象数组 const items: any[] = []; if (data.data && data.data.items && data.data.items.length > 0) { const fields = data.data.fields; for (const item of data.data.items) { const obj: any = {}; fields.forEach((field: string, index: number) => { obj[field] = item[index]; }); items.push(obj); } } return { data: items }; }