mcp-openmediavault

Instructions

Implementation Reference

• src/tools/system.ts:68-88 (handler)

  The handler function for get_network_interfaces tool. Takes an 'enumerate' parameter and either calls client.rpc('Network', 'enumerateDevices', {}) to enumerate all detected devices, or client.getList('Network', 'getInterfaceList', {...}) to list configured interfaces. Returns JSON result or error message.

  async ({ enumerate }) => {
    try {
      let result: unknown;
      if (enumerate) {
        result = await client.rpc("Network", "enumerateDevices", {});
      } else {
        result = await client.getList("Network", "getInterfaceList", {
          start: 0,
          limit: 100,
          sortfield: null,
          sortdir: null,
        });
      }
      return toolResult(JSON.stringify(result, null, 2));
    } catch (error) {
      return toolResult(
        `Error fetching network interfaces: ${error}`,
        true,
      );
    }
  },

• src/tools/system.ts:59-67 (schema)

  Input schema for get_network_interfaces tool using Zod. Defines 'enumerate' as an optional boolean parameter with default value false, describing whether to enumerate all detected devices or list configured interfaces.

  {
    enumerate: z
      .boolean()
      .optional()
      .default(false)
      .describe(
        "If true, enumerate all detected devices. If false, list configured interfaces.",
      ),
  },

• src/tools/system.ts:56-89 (registration)

  Registration of get_network_interfaces tool with the MCP server using server.tool(). Includes tool name, description, input schema, and handler function.

  server.tool(
    "get_network_interfaces",
    "List all network interfaces on the OpenMediaVault system with IP, netmask, gateway, and speed",
    {
      enumerate: z
        .boolean()
        .optional()
        .default(false)
        .describe(
          "If true, enumerate all detected devices. If false, list configured interfaces.",
        ),
    },
    async ({ enumerate }) => {
      try {
        let result: unknown;
        if (enumerate) {
          result = await client.rpc("Network", "enumerateDevices", {});
        } else {
          result = await client.getList("Network", "getInterfaceList", {
            start: 0,
            limit: 100,
            sortfield: null,
            sortdir: null,
          });
        }
        return toolResult(JSON.stringify(result, null, 2));
      } catch (error) {
        return toolResult(
          `Error fetching network interfaces: ${error}`,
          true,
        );
      }
    },
  );

• src/tools/system.ts:5-7 (helper)

  Helper function toolResult() that formats the response content for MCP tools. Returns an object with content array containing text and optional error flag.

  function toolResult(text: string, isError = false) {
    return { content: [{ type: "text" as const, text }], isError };
  }

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

  OmvClient.rpc() method used by the handler to make RPC calls to OpenMediaVault API. Handles authentication, session management, and error handling for API requests.

  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;
  }