Stock Market MCP Server

Instructions

Implementation Reference

• src/index.ts:191-219 (handler)

  The core handler function that validates input, maps statement type to Alpha Vantage API function, fetches the financial statement data, and returns it as JSON text.

  private async handleGetFinancialStatement(args: { statement: 'income' | 'balance' | 'cashflow'; symbol: string }) {
    if (!args || typeof args !== 'object' ||
      !args.statement || !['income', 'balance', 'cashflow'].includes(args.statement)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid statement parameter');
    }
    if (!args.symbol || typeof args.symbol !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid symbol parameter');
    }
  
    const functionMap = {
      income: 'INCOME_STATEMENT',
      balance: 'BALANCE_SHEET',
      cashflow: 'CASH_FLOW'
    };
  
    const response = await this.axiosInstance.get('', {
      params: {
        function: functionMap[args.statement],
        symbol: args.symbol
      }
    });
  
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(response.data, null, 2)
      }]
    };
  }

• src/index.ts:75-93 (registration)

  Registers the tool in the ListTools response, providing name, description, and input schema.

  {
    name: 'get_financial_statement',
    description: 'Get financial statements for a company',
    inputSchema: {
      type: 'object',
      properties: {
        symbol: {
          type: 'string',
          description: 'Stock ticker symbol'
        },
        statement: {
          type: 'string',
          enum: ['income', 'balance', 'cashflow'],
          description: 'Type of financial statement'
        }
      },
      required: ['symbol', 'statement']
    }
  },

• src/index.ts:78-92 (schema)

  Defines the input schema for validation: requires 'symbol' (string) and 'statement' (enum: 'income', 'balance', 'cashflow').

  inputSchema: {
    type: 'object',
    properties: {
      symbol: {
        type: 'string',
        description: 'Stock ticker symbol'
      },
      statement: {
        type: 'string',
        enum: ['income', 'balance', 'cashflow'],
        description: 'Type of financial statement'
      }
    },
    required: ['symbol', 'statement']
  }

• src/index.ts:118-124 (handler)

  Dispatcher case in CallToolRequestHandler that validates arguments and delegates to the specific handler.

  case 'get_financial_statement': {
    if (!request.params.arguments || typeof request.params.arguments !== 'object') {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid arguments');
    }
    const args = request.params.arguments as { statement: 'income' | 'balance' | 'cashflow'; symbol: string };
    return await this.handleGetFinancialStatement(args);
  }