ming_iching_cast

Instructions

Implementation Reference

• src/tools/iching.ts:34-64 (handler)

  The main handler function for the ming_iching_cast tool. It calls castIching() with the user's question and optional casting_timestamp, then flattens the raw response into a clean JSON result with hexagram details, changing lines, transformed hexagram, and interpretation.

    handler: async (args) => {
      const raw = (await castIching({
        question: args.question as string,
        casting_timestamp: args.casting_timestamp as string | undefined,
      })) as Record<string, unknown>;
  
      // The /iching-cast endpoint returns { ok, hexagram, analysis }
      // Flatten for cleaner MCP response
      const hexagram = raw.hexagram as Record<string, unknown> | undefined;
      const analysis = raw.analysis as Record<string, unknown> | undefined;
  
      const result = {
        question: args.question,
        cast_date: args.casting_timestamp ?? "today (SGT)",
        hexagram_number: hexagram?.king_wen_number ?? hexagram?.number ?? null,
        hexagram_name_cn: hexagram?.name ?? null,
        hexagram_name_en: hexagram?.english_name ?? hexagram?.english ?? null,
        upper_trigram: hexagram?.upper_trigram ?? null,
        lower_trigram: hexagram?.lower_trigram ?? null,
        changing_lines: hexagram?.moving_lines ?? hexagram?.changing_lines ?? null,
        transformed_hexagram: hexagram?.changed_hexagram ?? hexagram?.transformed ?? null,
        world_line: hexagram?.world_line ?? null,
        response_line: hexagram?.response_line ?? null,
        useful_god: hexagram?.useful_god ?? analysis?.useful_god ?? null,
        interpretation: analysis?.interpretation ?? analysis?.summary ?? null,
        action_guidance: analysis?.guidance ?? analysis?.recommendation ?? null,
        raw: raw,
      };
      return JSON.stringify(result, null, 2);
    },
  };

• src/tools/iching.ts:11-31 (schema)

  Input schema for ming_iching_cast. Defines 'question' (required string) and 'casting_timestamp' (optional ISO 8601 datetime string).

  inputSchema: {
    type: "object",
    properties: {
      question: {
        type: "string",
        description:
          "The specific question to cast for. Must be a genuine question about a real situation. " +
          "Example: 'Should I accept the offer from Company X?' — not 'What will happen to the economy?'",
      },
      casting_timestamp: {
        type: "string",
        format: "date-time",
        description:
          "Optional. ISO 8601 timestamp of the casting moment (e.g. '2026-04-18T14:30:00'). " +
          "When provided, the date and time are both forwarded to the engine — the time component " +
          "determines the hour branch (地支) used for 納甲 analysis. " +
          "If omitted, uses the server's current SGT time.",
      },
    },
    required: ["question"],
  },

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

  The tool is registered in the TOOLS array alongside five other tools, making it discoverable by the MCP server.

  export const TOOLS = [baziTool, qmdjTool, zwdsTool, fengshuiTool, ichingTool, forecastTool];

• src/engines-client.ts:94-106 (helper)

  The castIching() helper function that sends a POST request to the FastAPI /iching-cast endpoint with query parameters (question, date, hour_branch, casting_timestamp).

  export async function castIching(params: IchingParams): Promise<unknown> {
    const url = buildUrl("/iching-cast", {
      question: params.question,
      date: params.date,
      hour_branch: params.hour_branch,
      casting_timestamp: params.casting_timestamp,
    });
    const res = await fetch(url.toString(), {
      method: "POST",
      signal: AbortSignal.timeout(TIMEOUT_MS),
    });
    return handleResponse(res, "/iching-cast");
  }

• src/index.ts:39-41 (registration)

  The MCP server's ListToolsRequestSchema handler, which iterates TOOLS and exposes their definitions (including ming_iching_cast) to the client.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: TOOLS.map((t) => t.definition),
  }));