ming_qmdj_direction

Instructions

Implementation Reference

• src/tools/qmdj.ts:4-63 (handler)

  Main tool definition for ming_qmdj_direction. Contains both the inputSchema (definition) and the async handler function that calls getQmdj() from the engine client, then shapes the response with optimal direction, door, star, hour, favorable hours, and avoidance info.

  export const qmdjTool: MingTool = {
    definition: {
      name: "ming_qmdj_direction",
      description:
        "Compute a Qi Men Dun Jia (奇門遁甲) reading for a specific date. Returns the optimal " +
        "direction, best timing windows, lead star, and strategic framing. Ju number computed " +
        "via sxtwl solar term library for classical accuracy.",
      inputSchema: {
        type: "object",
        properties: {
          date: {
            type: "string",
            format: "date",
            description:
              "Date for the QMDJ reading in YYYY-MM-DD format. Defaults to today (SGT) if omitted.",
          },
          hour: {
            type: "integer",
            minimum: 0,
            maximum: 23,
            description:
              "Optional hour for hour-level resolution. If omitted, returns the best hour block for the day.",
          },
          question: {
            type: "string",
            description:
              "The specific intention (e.g. 'Best direction for a job interview', " +
              "'Is today favourable for signing a contract?').",
          },
        },
        required: ["question"],
      },
    },
  
    handler: async (args) => {
      const raw = (await getQmdj({ date: args.date as string | undefined })) as Record<
        string,
        unknown
      >;
  
      // Shape the raw /qmdj response into the spec's return shape
      const best = (raw.best_now ?? {}) as Record<string, unknown>;
      const shaped = {
        ju_number: raw.ju,
        ju_type: raw.is_yang ? "Yang" : "Yin",
        structure: raw.structure,
        optimal_direction: best.direction ?? null,
        optimal_door: best.door ? `${best.door} (${doorCn(best.door as string)})` : null,
        lead_star: best.star ?? null,
        best_hour: best.hour ?? null,
        favorable_hours: buildFavorableHours(raw.hours as Record<string, unknown>[]),
        avoidance: buildAvoidance(raw.hours as Record<string, unknown>[]),
        date: raw.date,
        day_pillar: raw.day_pillar,
        formations_summary: (raw.formations_summary as Record<string, unknown> | undefined)
          ?.headline ?? null,
        raw_hours: raw.hours,
      };
      return JSON.stringify(shaped, null, 2);
    },

• src/tools/qmdj.ts:4-35 (schema)

  Input schema for ming_qmdj_direction: defines optional 'date' (string, date format), optional 'hour' (integer 0-23), and required 'question' (string) parameters.

  export const qmdjTool: MingTool = {
    definition: {
      name: "ming_qmdj_direction",
      description:
        "Compute a Qi Men Dun Jia (奇門遁甲) reading for a specific date. Returns the optimal " +
        "direction, best timing windows, lead star, and strategic framing. Ju number computed " +
        "via sxtwl solar term library for classical accuracy.",
      inputSchema: {
        type: "object",
        properties: {
          date: {
            type: "string",
            format: "date",
            description:
              "Date for the QMDJ reading in YYYY-MM-DD format. Defaults to today (SGT) if omitted.",
          },
          hour: {
            type: "integer",
            minimum: 0,
            maximum: 23,
            description:
              "Optional hour for hour-level resolution. If omitted, returns the best hour block for the day.",
          },
          question: {
            type: "string",
            description:
              "The specific intention (e.g. 'Best direction for a job interview', " +
              "'Is today favourable for signing a contract?').",
          },
        },
        required: ["question"],
      },

• src/tools/index.ts:9-16 (registration)

  Registration of qmdjTool into the TOOLS array, which is exported and consumed by src/index.ts to expose the tool via MCP server.

  import { baziTool } from "./bazi.js";
  import { qmdjTool } from "./qmdj.js";
  import { zwdsTool } from "./zwds.js";
  import { fengshuiTool } from "./fengshui.js";
  import { ichingTool } from "./iching.js";
  import { forecastTool } from "./forecast.js";
  
  export const TOOLS = [baziTool, qmdjTool, zwdsTool, fengshuiTool, ichingTool, forecastTool];

• src/engines-client.ts:58-66 (helper)

  The getQmdj() HTTP client function that makes a GET request to the /qmdj endpoint of the Ming FastAPI engine, used by the handler to fetch raw QMDJ data.

  export interface QmdjParams {
    date?: string;
  }
  
  export async function getQmdj(params: QmdjParams): Promise<unknown> {
    const url = buildUrl("/qmdj", { date: params.date });
    const res = await fetch(url.toString(), { signal: AbortSignal.timeout(TIMEOUT_MS) });
    return handleResponse(res, "/qmdj");
  }