mercury_get_organization

Instructions

Implementation Reference

• src/tools/organization.ts:5-25 (handler)

  Registers and implements the 'mercury_get_organization' tool. The handler (lines 19-21) calls client.get('/organization') and returns a sanitized JSON result containing organization info (id, legalName, ein, address, etc.).

  export function registerOrganizationTools(server: McpServer, client: MercuryClient): void {
    defineTool(
      server,
      "mercury_get_organization",
      [
        "Retrieve information about your Mercury organization (legal name, EIN, registered address, etc.).",
        "",
        "USE WHEN: fetching the workspace's legal identity for invoice generation, tax documents, or to confirm which organization the API token is bound to.",
        "",
        "DO NOT USE: for per-account info (use `mercury_get_account`). The Mercury API exposes only one organization per token, so there is no list variant.",
        "",
        "RETURNS: `{ id, legalName, ein, address, ... }`.",
      ].join("\n"),
      {},
      async () => {
        const data = await client.get("/organization");
        return textResult(data);
      },
      { title: "Get Organization", readOnlyHint: true, openWorldHint: true },
    );
  }

• src/tools/organization.ts:5-25 (schema)

  The input schema is an empty object '{}' (line 18) — no parameters are required for this tool.

  export function registerOrganizationTools(server: McpServer, client: MercuryClient): void {
    defineTool(
      server,
      "mercury_get_organization",
      [
        "Retrieve information about your Mercury organization (legal name, EIN, registered address, etc.).",
        "",
        "USE WHEN: fetching the workspace's legal identity for invoice generation, tax documents, or to confirm which organization the API token is bound to.",
        "",
        "DO NOT USE: for per-account info (use `mercury_get_account`). The Mercury API exposes only one organization per token, so there is no list variant.",
        "",
        "RETURNS: `{ id, legalName, ein, address, ... }`.",
      ].join("\n"),
      {},
      async () => {
        const data = await client.get("/organization");
        return textResult(data);
      },
      { title: "Get Organization", readOnlyHint: true, openWorldHint: true },
    );
  }

• src/tools/organization.ts:5-25 (registration)

  The tool is registered via defineTool() with name 'mercury_get_organization' on the MCP server. The registration function registerOrganizationTools() is called from src/tools/index.ts line 30.

  export function registerOrganizationTools(server: McpServer, client: MercuryClient): void {
    defineTool(
      server,
      "mercury_get_organization",
      [
        "Retrieve information about your Mercury organization (legal name, EIN, registered address, etc.).",
        "",
        "USE WHEN: fetching the workspace's legal identity for invoice generation, tax documents, or to confirm which organization the API token is bound to.",
        "",
        "DO NOT USE: for per-account info (use `mercury_get_account`). The Mercury API exposes only one organization per token, so there is no list variant.",
        "",
        "RETURNS: `{ id, legalName, ein, address, ... }`.",
      ].join("\n"),
      {},
      async () => {
        const data = await client.get("/organization");
        return textResult(data);
      },
      { title: "Get Organization", readOnlyHint: true, openWorldHint: true },
    );
  }

• src/tools/_shared.ts:16-26 (helper)

  textResult() helper used by the handler — sanitizes JSON values and wraps them in a ToolResult with both text content and structuredContent.

  export function textResult(data: unknown): ToolResult {
    // Walk the payload once, reuse the sanitized value for both the
    // LLM-display JSON string and the `structuredContent` object.
    // Calling sanitizeJsonForLlm(data) + sanitizeJsonValues(data)
    // separately would run the walker twice on the same input.
    const sanitized = sanitizeJsonValues(data);
    return {
      content: [{ type: "text", text: JSON.stringify(sanitized, null, 2) }],
      structuredContent: (sanitized ?? {}) as Record<string, unknown>,
    };
  }

• src/tools/_shared.ts:28-54 (helper)

  defineTool() helper that wraps the handler with rate-limiting/audit middleware (via wrapToolHandler) and registers the tool on the MCP server with strict input schema and annotations.

  export function defineTool<S extends ZodRawShape>(
    server: McpServer,
    name: string,
    description: string,
    inputSchema: S,
    handler: (args: z.infer<z.ZodObject<S>>) => Promise<ToolResult>,
    annotations: ToolAnnotations,
  ): void {
    const wrapped = wrapToolHandler(name, handler);
    const strictSchema = z.object(inputSchema).strict();
    // MCP behavioral annotations (readOnlyHint / destructiveHint /
    // idempotentHint / openWorldHint) — declared machine-readable so
    // hosts and rubrics (TDQS / Glama Behavior dimension) can detect
    // tool semantics without scraping the prose description. Required
    // (not optional) so every new tool ships with explicit semantics —
    // forgetting the annotation now fails typecheck instead of
    // silently shipping a tool with no hint set.
    // The MCP SDK overloads `registerTool` with shape narrowing the runtime
    // strict-schema and the wrapped callback can't satisfy through generics.
    // Both casts are runtime-safe — the signatures only diverge at the type
    // level. Asserted by the existing tool-registration tests.
    (server.registerTool as unknown as (...a: unknown[]) => unknown)(
      name,
      { description, inputSchema: strictSchema, annotations },
      wrapped,
    );
  }