FinanceMCP

Instructions

Implementation Reference

• src/tools/convertibleBond.ts:3-105 (handler)

  Core tool definition including handler (run function), schema (parameters), name, and description. The run method fetches convertible bond data (basic/issue/info) from Tushare API, handles errors, and formats output as formatted text.
  export const convertibleBond = { name: "convertible_bond", description: "获取可转债非行情数据，支持两种查询方式：1)使用issue类型按时间范围查询可转债发行数据；2)使用info类型按代码查询可转债详细信息", parameters: { type: "object", properties: { ts_code: { type: "string", description: "可转债代码，如'110001.SH'表示国电转债，'128001.SZ'表示平安转债。配合info类型使用可查询详细信息" }, data_type: { type: "string", description: "数据类型，可选值：issue(可转债发行数据)、info(可转债详细信息，通过代码查询)", enum: ["issue", "info"] }, start_date: { type: "string", description: "起始日期，格式为YYYYMMDD，如'20230101'。用于查询发行数据的公告日期范围" }, end_date: { type: "string", description: "结束日期，格式为YYYYMMDD，如'20230131'。用于查询发行数据的公告日期范围" } }, required: ["data_type"] }, async run(args: { ts_code?: string; data_type: string; start_date?: string; end_date?: 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环境变量'); } // 默认日期设置 const today = new Date(); const currentYear = today.getFullYear(); const defaultEndDate = `${currentYear}1231`; const defaultStartDate = `${currentYear - 1}0101`; const results: any[] = []; // 根据data_type决定要查询的API const dataTypes = args.data_type === 'info' ? ['basic', 'issue'] // info类型查询所有可用数据 : [args.data_type]; for (const dataType of dataTypes) { try { const result = await fetchConvertibleBondData( dataType, args.ts_code, args.start_date || defaultStartDate, args.end_date || defaultEndDate, TUSHARE_API_KEY, TUSHARE_API_URL ); if (result.data && result.data.length > 0) { results.push({ type: dataType, data: result.data, fields: result.fields }); } } catch (error) { console.warn(`获取${dataType}数据失败:`, error); results.push({ type: dataType, error: error instanceof Error ? error.message : '未知错误' }); } } if (results.length === 0) { throw new Error(`未找到相关可转债数据`); } // 格式化输出 const formattedOutput = formatConvertibleBondData(results, args.ts_code); return { content: [{ type: "text", text: formattedOutput }] }; } catch (error) { console.error('可转债数据查询错误:', error); return { content: [{ type: "text", text: `查询可转债数据时发生错误: ${error instanceof Error ? error.message : '未知错误'}` }] }; } }
• src/tools/convertibleBond.ts:109-209 (helper)

  Helper function to fetch raw data from Tushare API for specific data types (cb_basic, cb_issue), handling parameters mapping and response parsing.
  async function fetchConvertibleBondData( dataType: string, tsCode?: string, startDate?: string, endDate?: string, apiKey?: string, apiUrl?: string ) { const apiConfigs: Record<string, any> = { basic: { api_name: "cb_basic", default_fields: "ts_code,bond_short_name,stk_code,stk_short_name,maturity,par_value,issue_price,issue_size,remain_size,value_date,maturity_date,list_date,delist_date,exchange,conv_start_date,conv_end_date,first_conv_price,conv_price,rate_clause,put_clause,force_redeem_clause,resale_clause,cross_default_clause" }, issue: { api_name: "cb_issue", default_fields: "ts_code,ann_date,res_ann_date,plan_issue_size,issue_size,issue_price,issue_type,issue_cost,onl_code,onl_name,onl_date,onl_size,onl_pch_vol,onl_pch_num,onl_pch_excess,onl_winning_rate,shd_ration_code,shd_ration_name,shd_ration_date,shd_ration_record_date,shd_ration_pay_date,shd_ration_price,shd_ration_ratio,shd_ration_size,shd_ration_vol,shd_ration_num,shd_ration_excess,offl_size,offl_deposit,offl_pch_vol,offl_pch_num,offl_pch_excess,offl_winning_rate,lead_underwriter,lead_underwriter_vol" } }; const config = apiConfigs[dataType]; if (!config) { throw new Error(`不支持的数据类型: ${dataType}`); } // 构建请求参数 const params: any = { api_name: config.api_name, token: apiKey, params: {}, fields: config.default_fields }; // 根据Tushare文档严格映射参数 if (dataType === 'basic') { // cb_basic接口参数：ts_code, list_date, exchange if (tsCode) params.params.ts_code = tsCode; // 对于basic查询，如果提供了start_date，映射到list_date（上市日期） if (startDate) params.params.list_date = startDate; } else if (dataType === 'issue') { // cb_issue接口参数：ts_code, ann_date, start_date, end_date if (tsCode) params.params.ts_code = tsCode; // 对于issue查询，直接使用start_date和end_date作为公告日期范围 if (startDate) params.params.start_date = startDate; if (endDate) params.params.end_date = endDate; } // 设置请求超时 const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), TUSHARE_CONFIG.TIMEOUT); try { console.log(`请求Tushare API: ${params.api_name}，参数:`, params.params); // 发送请求 const response = await fetch(apiUrl!, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(params), signal: controller.signal }); if (!response.ok) { throw new Error(`Tushare API请求失败: ${response.status}`); } const data = await response.json(); // 处理响应数据 if (data.code !== 0) { throw new Error(`Tushare API错误: ${data.msg}`); } // 确保data.data和data.data.items存在 if (!data.data || !data.data.items) { throw new Error(`未找到${dataType}数据`); } // 获取字段名 const fields = data.data.fields; // 将数据转换为对象数组 const convertedData = data.data.items.map((item: any) => { const result: Record<string, any> = {}; fields.forEach((field: string, index: number) => { result[field] = item[index]; }); return result; }); return { data: convertedData, fields: fields }; } finally { clearTimeout(timeoutId); } }
• src/tools/convertibleBond.ts:212-244 (helper)

  Helper function to format fetched results into user-friendly markdown text report, with specialized formatters for basic and issue data.
  function formatConvertibleBondData(results: any[], tsCode?: string): string { let output = ` 🪙 可转债数据报告${tsCode ? ` - ${tsCode}` : ''}\n\n`; output += `📅 查询时间: ${new Date().toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' })}\n\n`; results.forEach((result, index) => { if (result.error) { output += ` ❌ ${getDataTypeName(result.type)}查询失败\n\n`; output += `错误信息: ${result.error}\n\n`; return; } const dataTypeName = getDataTypeName(result.type); output += ` 📊 ${dataTypeName} (${result.data.length}条记录)\n\n`; switch (result.type) { case 'basic': output += formatBasicInfo(result.data); break; case 'issue': output += formatIssueInfo(result.data); break; default: output += formatGenericCBData(result.data, result.fields); break; } if (index < results.length - 1) { output += "\n---\n\n"; } }); return output; }
• src/index.ts:215-217 (registration)

  Tool registration in listTools handler, exposing name, description, and input schema.
  name: convertibleBond.name, description: convertibleBond.description, inputSchema: convertibleBond.parameters
• src/index.ts:335-341 (registration)

  Tool execution handler in callToolRequestSchema switch case, extracting arguments and calling convertibleBond.run.
  case "convertible_bond": { const ts_code = request.params.arguments?.ts_code ? String(request.params.arguments.ts_code) : undefined; const data_type = String(request.params.arguments?.data_type); const start_date = request.params.arguments?.start_date ? String(request.params.arguments.start_date) : undefined; const end_date = request.params.arguments?.end_date ? String(request.params.arguments.end_date) : undefined; return normalizeResult(await convertibleBond.run({ ts_code, data_type, start_date, end_date })); }