DhanHQ MCP Server

Instructions

Implementation Reference

• src/index.ts:585-597 (handler)

  The MCP tool dispatcher handler for 'get_order_by_id'. Extracts orderId from input arguments, calls the getOrderByID helper function, and formats the response as MCP content.

  case 'get_order_by_id': {
    console.error('[Tool] Executing: get_order_by_id');
    const { orderId } = args as Record<string, unknown>;
    const order = await getOrderByID(orderId as string);
    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify(order, null, 2),
        },
      ],
    };
  }

• src/index.ts:210-221 (schema)

  Tool schema definition including name, description, and input schema that requires a single 'orderId' string parameter.

  {
    name: 'get_order_by_id',
    description:
      'Retrieves the details and status of a specific order by order ID. Requires authentication.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        orderId: { type: 'string', description: 'Order ID to retrieve' },
      },
      required: ['orderId'],
    },
  },

• src/authentication.ts:379-403 (helper)

  Core helper function that performs the actual API call to DhanHQ to retrieve the specific order details by order ID, handles errors, and returns OrderBook.

  export async function getOrderByID(orderId: string): Promise<OrderBook> {
    try {
      log(`Fetching order: ${orderId}`);
  
      const response = await axios.get<OrderBook>(
        `https://api.dhan.co/v2/orders/${orderId}`,
        {
          headers: getApiHeaders(),
        }
      );
  
      log(`✓ Order retrieved. Status: ${response.data.orderStatus}`);
      return response.data;
    } catch (error) {
      const errorMessage =
        error instanceof axios.AxiosError
          ? `API Error: ${error.response?.status} - ${JSON.stringify(error.response?.data)}`
          : error instanceof Error
            ? error.message
            : 'Unknown error';
  
      log(`✗ Failed to get order: ${errorMessage}`);
      throw new Error(`Failed to get order: ${errorMessage}`);
    }
  }

• src/types.ts:80-100 (schema)

  TypeScript interface defining the structure of the OrderBook response object used as return type.

  export interface OrderBook {
    dhanClientId: string;
    orderId: string;
    correlationId: string;
    orderStatus: string;
    transactionType: string;
    exchangeSegment: string;
    productType: string;
    orderType: string;
    validity: string;
    securityId: string;
    quantity: number;
    price: number;
    triggerPrice?: number;
    disclosedQuantity?: number;
    createTime: string;
    algoId?: string;
    remainingQuantity: number;
    filledQty: number;
    updateTime?: string;
  }

• src/index.ts:359-361 (registration)

  Registers the listTools handler which provides the full tools list including 'get_order_by_id'.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools,
  }));