mcp-openmediavault

Instructions

Implementation Reference

• src/tools/users.ts:89-99 (handler)

  The async handler function for 'get_group' tool that takes a group name and calls client.rpc('GroupMgmt', 'get', { name }) to fetch group details from OpenMediaVault, returning JSON-formatted results or an error message.

  async ({ name }) => {
    try {
      const result = await client.rpc("GroupMgmt", "get", { name });
      return toolResult(JSON.stringify(result, null, 2));
    } catch (error) {
      return toolResult(
        `Error fetching group '${name}': ${error}`,
        true,
      );
    }
  },

• src/tools/users.ts:86-88 (schema)

  Zod schema definition for 'get_group' tool input: a single required 'name' string parameter describing the group name to look up.

  {
    name: z.string().describe("Group name to look up"),
  },

• src/tools/users.ts:83-100 (registration)

  Registration of the 'get_group' tool using server.tool() with name, description, input schema, and handler function.

  server.tool(
    "get_group",
    "Get detailed information about a specific group",
    {
      name: z.string().describe("Group name to look up"),
    },
    async ({ name }) => {
      try {
        const result = await client.rpc("GroupMgmt", "get", { name });
        return toolResult(JSON.stringify(result, null, 2));
      } catch (error) {
        return toolResult(
          `Error fetching group '${name}': ${error}`,
          true,
        );
      }
    },
  );

• src/omv-client.ts:96-150 (helper)

  The OmvClient.rpc() method that handles authenticated API communication with OpenMediaVault, including session management, cookie handling, and error recovery for the get_group tool.

  async rpc(
    service: string,
    method: string,
    params: Record<string, unknown> = {},
  ): Promise<unknown> {
    if (!this.sessionId && !this.cookie) {
      await this.login();
    }
  
    const url = `${this.baseUrl}/rpc.php`;
    const body = {
      service,
      method,
      params,
      options: null,
    };
  
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
    };
  
    if (this.cookie) {
      headers["Cookie"] = this.cookie;
    }
    if (this.sessionId) {
      headers["X-OPENMEDIAVAULT-SESSIONID"] = this.sessionId;
    }
  
    const response = await fetch(url, {
      method: "POST",
      headers,
      body: JSON.stringify(body),
    });
  
    if (response.status === 401) {
      // Session expired — re-login and retry
      await this.login();
      return this.rpc(service, method, params);
    }
  
    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`OMV API error (${response.status}): ${errorText}`);
    }
  
    const data = (await response.json()) as OmvResponse;
  
    if (data.error) {
      throw new Error(
        `OMV RPC error [${service}.${method}]: ${data.error.message} (code ${data.error.code})`,
      );
    }
  
    return data.response;
  }