Verity MCP Server

Instructions

Implementation Reference

• src/index.ts:380-394 (handler)

  Handler function that fetches the specific policy from Verity API endpoint `/policies/{policy_id}` using the shared verityRequest helper, formats the result with formatPolicy, and returns it as text content. Handles errors gracefully.

  async ({ policy_id, include }) => {
    try {
      const result = await verityRequest<any>(`/policies/${encodeURIComponent(policy_id)}`, {
        params: { include },
      });
  
      return {
        content: [{ type: "text", text: formatPolicy(result.data, true) }],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Error getting policy: ${error instanceof Error ? error.message : String(error)}` }],
      };
    }
  }

• src/index.ts:375-378 (schema)

  Zod input schema validating the required policy_id string and optional include string for additional data fields.

  inputSchema: {
    policy_id: z.string().min(1).describe("Policy ID (e.g., L33831, A52458, NCD220.6)"),
    include: z.string().optional().describe("Additional data: 'criteria', 'codes', 'attachments', 'versions'"),
  },

• src/index.ts:365-395 (registration)

  Registration of the 'get_policy' tool on the MCP server, including description, input schema, and handler function reference.

  server.registerTool(
    "get_policy",
    {
      description: `Get detailed information about a specific Medicare coverage policy.
  Use this after finding a policy ID from search_policies or lookup_code.
  Can include criteria, codes, attachments, and version history.
  
  Examples:
  - get_policy("L33831") - LCD for ultrasound guidance
  - get_policy("A52458", { include: "criteria,codes" }) - with coverage criteria`,
      inputSchema: {
        policy_id: z.string().min(1).describe("Policy ID (e.g., L33831, A52458, NCD220.6)"),
        include: z.string().optional().describe("Additional data: 'criteria', 'codes', 'attachments', 'versions'"),
      },
    },
    async ({ policy_id, include }) => {
      try {
        const result = await verityRequest<any>(`/policies/${encodeURIComponent(policy_id)}`, {
          params: { include },
        });
  
        return {
          content: [{ type: "text", text: formatPolicy(result.data, true) }],
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: `Error getting policy: ${error instanceof Error ? error.message : String(error)}` }],
        };
      }
    }
  );

• src/index.ts:107-163 (helper)

  Helper function formatPolicy used by the handler to generate a human-readable string representation of policy data, including title, status, sections, criteria, and codes.

  function formatPolicy(policy: any, detailed = false): string {
    const lines: string[] = [];
    lines.push(`Policy: ${policy.policy_id} - ${policy.title}`);
    lines.push(`Type: ${policy.policy_type} | Status: ${policy.status}`);
    if (policy.jurisdiction) lines.push(`Jurisdiction: ${policy.jurisdiction}`);
    if (policy.effective_date) lines.push(`Effective: ${policy.effective_date}`);
    if (policy.retire_date) lines.push(`Retired: ${policy.retire_date}`);
  
    if (detailed) {
      if (policy.description) lines.push(`\nDescription: ${policy.description}`);
      if (policy.summary) lines.push(`\nSummary: ${policy.summary}`);
  
      if (policy.mac) {
        lines.push(`\nMAC: ${policy.mac.name} (${policy.mac.jurisdiction_name})`);
        if (policy.mac.states) lines.push(`States: ${policy.mac.states.join(", ")}`);
      }
  
      if (policy.sections) {
        if (policy.sections.indications) {
          lines.push(`\n--- Indications ---\n${policy.sections.indications.slice(0, 1000)}${policy.sections.indications.length > 1000 ? "..." : ""}`);
        }
        if (policy.sections.limitations) {
          lines.push(`\n--- Limitations ---\n${policy.sections.limitations.slice(0, 1000)}${policy.sections.limitations.length > 1000 ? "..." : ""}`);
        }
        if (policy.sections.documentation) {
          lines.push(`\n--- Documentation Requirements ---\n${policy.sections.documentation.slice(0, 1000)}${policy.sections.documentation.length > 1000 ? "..." : ""}`);
        }
      }
  
      if (policy.criteria && Object.keys(policy.criteria).length > 0) {
        lines.push("\n--- Coverage Criteria ---");
        Object.entries(policy.criteria).forEach(([section, blocks]: [string, any]) => {
          lines.push(`\n[${section.toUpperCase()}]`);
          blocks.slice(0, 3).forEach((block: any) => {
            lines.push(`  - ${block.text.slice(0, 200)}${block.text.length > 200 ? "..." : ""}`);
            if (block.tags?.length) lines.push(`    Tags: ${block.tags.join(", ")}`);
          });
          if (blocks.length > 3) lines.push(`  ... and ${blocks.length - 3} more criteria`);
        });
      }
  
      if (policy.codes && Object.keys(policy.codes).length > 0) {
        lines.push("\n--- Associated Codes ---");
        Object.entries(policy.codes).forEach(([system, codes]: [string, any]) => {
          lines.push(`\n[${system}] (${codes.length} codes)`);
          codes.slice(0, 10).forEach((c: any) => {
            lines.push(`  - ${c.code}: ${c.display || "No description"} [${c.disposition}]`);
          });
          if (codes.length > 10) lines.push(`  ... and ${codes.length - 10} more codes`);
        });
      }
    }
  
    if (policy.source_url) lines.push(`\nSource: ${policy.source_url}`);
  
    return lines.join("\n");
  }

• src/index.ts:25-66 (helper)

  Shared helper function verityRequest for making authenticated API calls to the Verity service, used by all tools including get_policy.

  async function verityRequest<T>(
    endpoint: string,
    options: {
      method?: "GET" | "POST";
      params?: Record<string, string | number | boolean | undefined>;
      body?: unknown;
    } = {}
  ): Promise<T> {
    const { method = "GET", params, body } = options;
  
    // Build URL with query params
    const url = new URL(`${VERITY_API_BASE}${endpoint}`);
    if (params) {
      Object.entries(params).forEach(([key, value]) => {
        if (value !== undefined && value !== null && value !== "") {
          url.searchParams.append(key, String(value));
        }
      });
    }
  
    const headers: Record<string, string> = {
      Authorization: `Bearer ${VERITY_API_KEY}`,
      "Content-Type": "application/json",
      Accept: "application/json",
    };
  
    const response = await fetch(url.toString(), {
      method,
      headers,
      body: body ? JSON.stringify(body) : undefined,
    });
  
    const data = await response.json();
  
    if (!response.ok) {
      const errorMsg = data.error?.message || `API error: ${response.status}`;
      const hint = data.error?.hint || "";
      throw new Error(hint ? `${errorMsg}. Hint: ${hint}` : errorMsg);
    }
  
    return data as T;
  }