ming_zwds_chart

Instructions

Implementation Reference

• src/tools/zwds.ts:52-67 (handler)

  Handler function for the ming_zwds_chart tool. Calls generateZwds() engine client and optionally adds focus_palace annotation.

  handler: async (args) => {
    const raw = (await generateZwds({
      date: args.birth_date as string,
      hour: args.birth_hour as number,
      gender: args.gender as string,
    })) as Record<string, unknown>;
  
    // If focus_palace requested, annotate which palace is highlighted
    const result: Record<string, unknown> = { ...raw };
    if (args.focus_palace) {
      result.focus_palace = args.focus_palace;
      result.focus_note =
        `Focused on ${args.focus_palace} palace. See 'palaces' key for full twelve-palace data.`;
    }
    return JSON.stringify(result, null, 2);
  },

• src/tools/zwds.ts:16-49 (schema)

  Input schema for ming_zwds_chart: requires birth_date, birth_hour, gender; optional birth_location and focus_palace.

  inputSchema: {
    type: "object",
    properties: {
      birth_date: {
        type: "string",
        format: "date",
        description: "Date of birth in YYYY-MM-DD format.",
      },
      birth_hour: {
        type: "integer",
        minimum: 0,
        maximum: 23,
        description:
          "Hour of birth (0–23). Required for accurate palace placement — " +
          "Zi Wei palace positions shift by birth hour.",
      },
      birth_location: {
        type: "string",
        description: "City and country of birth. Used for timezone context.",
      },
      gender: {
        type: "string",
        enum: ["male", "female"],
        description: "Gender affects 四化 (sihua) transformation assignments.",
      },
      focus_palace: {
        type: "string",
        enum: PALACE_KEYS,
        description:
          "Optional. Focus the narrative on this palace. If omitted, returns highlights across all twelve.",
      },
    },
    required: ["birth_date", "birth_hour", "gender"],
  },

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

  The tool is registered in the TOOLS array via zwdsTool export.

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

• src/engines-client.ts:70-83 (helper)

  generateZwds helper function — HTTP client that POSTs to the /zwds FastAPI endpoint.

  export interface ZwdsParams {
    date: string;
    hour: number;
    gender: string;
  }
  
  export async function generateZwds(params: ZwdsParams): Promise<unknown> {
    const url = buildUrl("/zwds", { date: params.date, hour: params.hour, gender: params.gender });
    const res = await fetch(url.toString(), {
      method: "POST",
      signal: AbortSignal.timeout(TIMEOUT_MS),
    });
    return handleResponse(res, "/zwds");
  }

• src/index.ts:11-40 (registration)

  MCP server registers all tools via TOOLS.map in ListToolsRequestSchema handler and dispatches to tool.handler in CallToolRequestSchema.

   *   ming_zwds_chart            Zi Wei Dou Shu twelve-palace chart
   *   ming_fengshui_flying_stars Kua number + directional analysis
   *   ming_iching_cast           I Ching hexagram (Liu Yao method)
   *   ming_full_forecast         Five-engine integrated forecast
   */
  
  import { Server } from "@modelcontextprotocol/sdk/server/index.js";
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
  import {
    CallToolRequestSchema,
    ErrorCode,
    ListToolsRequestSchema,
    McpError,
  } from "@modelcontextprotocol/sdk/types.js";
  import { TOOLS } from "./tools/index.js";
  
  const server = new Server(
    {
      name: "ming-metaphysics-mcp",
      version: "1.0.0",
    },
    {
      capabilities: { tools: {} },
    }
  );
  
  // ── List tools ────────────────────────────────────────────────────────────────
  
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: TOOLS.map((t) => t.definition),