macOS Tools MCP Server

Instructions

Implementation Reference

• src/tools/performance-monitor.ts:234-315 (handler)

  Main handler function implementing the system_performance tool logic, handling actions like current metrics, historical data, processes, and optimizations.

  export async function performanceMonitor(
    params: SystemPerformanceParams
  ): Promise<PerformanceResult> {
    try {
      const db = initDatabase();
      
      switch (params.action) {
        case "current": {
          const metrics = await getCurrentMetrics();
          storeMetrics(db, metrics);
          
          if (!params.metric || params.metric === "all") {
            return { status: "success", data: metrics };
          }
          
          // Return specific metric
          const filteredMetrics: SystemMetrics = {
            ...metrics,
            cpu: params.metric === "cpu" ? metrics.cpu : {} as any,
            memory: params.metric === "memory" ? metrics.memory : {} as any,
            disk: params.metric === "disk" ? metrics.disk : {} as any,
            network: params.metric === "network" ? metrics.network : {} as any,
          };
          
          return { status: "success", data: filteredMetrics };
        }
        
        case "history": {
          const timeRange = params.timeRange || "1h";
          const historicalData = getHistoricalMetrics(db, timeRange);
          
          if (params.metric && params.metric !== "all") {
            // Filter historical data by metric
            const filtered = historicalData;
            
            return { status: "success", data: filtered };
          }
          
          return { status: "success", data: historicalData };
        }
        
        case "processes": {
          const cacheKey = createCacheKey("processes", { metric: params.metric });
          
          const processes = await processListCache.get(cacheKey, async () => {
            const procs = await getTopProcesses();
            
            if (params.metric && params.metric !== "all") {
              // Sort by specific metric
              return procs.sort((a, b) => {
                switch (params.metric) {
                  case "cpu":
                    return b.cpu - a.cpu;
                  case "memory":
                    return b.memory - a.memory;
                  default:
                    return 0;
                }
              });
            }
            
            return procs;
          });
          
          return { status: "success", data: processes };
        }
        
        case "optimize": {
          const suggestions = await analyzeForOptimizations();
          return { status: "success", data: suggestions };
        }
        
        default:
          return { status: "error", error: "Invalid action" };
      }
    } catch (error) {
      return {
        status: "error",
        error: error instanceof Error ? error.message : String(error),
      };
    }
  }

• src/index.ts:42-64 (registration)

  Tool registration in the list of available tools, including name, description, and input schema.

    name: "system_performance",
    description: "Monitor system performance and analyze resource usage",
    inputSchema: {
      type: "object",
      properties: {
        action: {
          type: "string",
          enum: ["current", "history", "processes", "optimize"],
          description: "Type of performance analysis",
        },
        timeRange: {
          type: "string",
          description: "Time range for historical data (e.g., '1h', '24h', '7d')",
        },
        metric: {
          type: "string",
          enum: ["cpu", "memory", "disk", "network", "all"],
          description: "Specific metric to analyze",
        },
      },
      required: ["action"],
    },
  },

• src/index.ts:24-28 (schema)

  Zod schema for validating input parameters to the system_performance tool.

  const SystemPerformanceSchema = z.object({
    action: z.enum(["current", "history", "processes", "optimize"]),
    timeRange: z.string().optional(),
    metric: z.enum(["cpu", "memory", "disk", "network", "all"]).optional(),
  });

• src/tools/types.ts:1-5 (schema)

  TypeScript interface defining the parameters for the system_performance tool.

  export interface SystemPerformanceParams {
    action: "current" | "history" | "processes" | "optimize";
    timeRange?: string;
    metric?: "cpu" | "memory" | "disk" | "network" | "all";
  }

• src/index.ts:118-129 (registration)

  Dispatch handler in the MCP server that routes calls to the system_performance tool and formats the response.

  case "system_performance": {
    const params = SystemPerformanceSchema.parse(args);
    const result = await performanceMonitor(params);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }